Programmer's Reference Guide

Zend_Uri

Zend_Uri(日本語)

概要

Zend_Uri は、 » Uniform Resource Identifiers (URIs) の操作および検証を行うためのコンポーネントです。 Zend_Uri の本来の目的は Zend_Http_Client のような他のコンポーネントを支援することですが、単体で使用しても便利です。

URI の最初は常にスキームから始まり、その後にコロンが続きます。スキームにはさまざまなものがあります。 Zend_Uri クラスは、各スキームに特化した自身のサブクラスを返すファクトリメソッドを提供しています。サブクラスの名前は Zend_Uri_<scheme> となり、<scheme> の部分にはスキーム名の最初の文字だけを大文字にしたものがあてはまります。この規則にはひとつ例外があり、HTTPS スキームについては Zend_Uri_Http で扱われます。

新しい URI の作成

スキームのみを Zend_Uri::factory() に渡すと、 Zend_Uri は新しい URI をゼロから作成します。

例1 Zend_Uri::factory() による新しい URI の作成

// 何もないところから新しい URI を作成するには、スキームのみを渡します
$uri = Zend_Uri::factory('http');
 
// $uri は Zend_Uri_Http のインスタンスとなります

新しい URI を作成するには、スキームのみを Zend_Uri::factory() に渡します ^[1]HTTPHTTPSZend_Uri。サポートしていないスキームが渡された場合は、 Zend_Uri_Exception がスローされます。

渡されたスキームあるいは URI をサポートしている場合は、 Zend_Uri::factory() は自分自身のサブクラスを返します。これは、指定したスキームに特化したものとなります。

Creating a New Custom-Class URI

Starting from Zend Framework 1.10.5, you can specify a custom class to be used when creating the Zend_Uri instance, as a second parameter to the Zend_Uri::factory() method. This enables you to subclass Zend_Uri and create your own custom URI classes, and instantiate new URI objects based on your own custom classes.

The 2nd parameter passed to Zend_Uri::factory() must be a string with the name of a class extending Zend_Uri. The class must either be alredy-loaded, or loadable using Zend_Loader::loadClass() - that is, it must follow the Zend Framework class and file naming conventions, and must be in your include_path.

例2 Creating a URI using a custom class

// Create a new 'ftp' URI based on a custom class
$ftpUri = Zend_Uri::factory(
    'ftp://user@ftp.example.com/path/file', 
    'MyLibrary_Uri_Ftp'
);
 
// $ftpUri is an instance of MyLibrary_Uri_Ftp, which is a subclass of Zend_Uri

既存の URI の操作

既存の URI を操作するには、完全な URI を Zend_Uri::factory() に渡します。

例3 Zend_Uri::factory() による既存の URI の操作

// 既存の URI を操作するには、それを渡します
$uri = Zend_Uri::factory('http://www.zend.com');
 
// $uri は Zend_Uri_Http のインスタンスです

このとき、URI のパースと検証が行われます。もし妥当な形式でなかった場合は、そこで Zend_Uri_Exception がスローされます。それ以外の場合は Zend_Uri::factory() は自分自身のサブクラスを返します。これは、操作するスキームに特化したものとなります。

URI の検証

Zend_Uri::check() 関数を使用すると、既存の URI の検証のみを行うことができます。

例4 Zend_Uri::check() による URI の検証

// 指定した URI が正しい形式かどうかを調べます
$valid = Zend_Uri::check('http://uri.in.question');
 
// $valid は、正しければ TRUE、そうでなければ FALSE となります

Zend_Uri::check() は boolean 値を返します。これは Zend_Uri::factory() を使用して例外を処理するよりも便利です。

URL 内での "Unwise" 文字の許可

デフォルトでは、Zend_Uri は次の文字を許可しません。 "{", "}", "|", "\", "^", "`" これらは RFC で "unwise" と定義されており無効なものです。しかし、多くの実装ではこれらの文字を妥当なものとして扱います。

Zend_Uri でもこれらの "unwise" 文字を許可することができます。そのためには、 Zend_Uri::setConfig() メソッドで 'allow_unwise' オプションを TRUE に設定します。

例5 URI における特殊文字の許可

// '|' 記号を含んでいます
// 通常は、これは false を返します
$valid = Zend_Uri::check('http://example.com/?q=this|that');
 
// しかし、"unwise" 文字を許可することもできます
Zend_Uri::setConfig(array('allow_unwise' => true));
// これは 'true' を返します
$valid = Zend_Uri::check('http://example.com/?q=this|that');
 
// 'allow_unwise' の値をデフォルトの FALSE に戻します
Zend_Uri::setConfig(array('allow_unwise' => false));

注意: Zend_Uri::setConfig() は、全体の設定オプションを変更します。そのため、上の例のように最後は 'allow_unwise' を 'FALSE' に戻すことを推奨します。unwise な文字を常に許可したいという場合は別です。

共通のインスタンスメソッド

すべての Zend_Uri のサブクラス (例 Zend_Uri_Http) のインスタンスには、 URI 操作のために便利なインスタンスメソッドがいくつか提供されています。

URI のスキームの取得

URI のスキームとは、URI でカンマの前にくる部分のことです。たとえば http://www.zend.com のスキームは "http" となります。

例6 Zend_Uri_* オブジェクトからのスキームの取得

$uri = Zend_Uri::factory('http://www.zend.com');
 
$scheme = $uri->getScheme();  // "http"

インスタンスメソッド getScheme() は、 URI オブジェクトからスキームの部分のみを返します。

URI 全体の取得

例7 Zend_Uri_* オブジェクトからの URI 全体の取得

$uri = Zend_Uri::factory('http://www.zend.com');
 
echo $uri->getUri();  // "http://www.zend.com"

getUri() メソッドは、URI 全体を文字列として返します。

URI の検証

Zend_Uri::factory() は渡された URI を常に検証しており、渡された URI が無効な場合は Zend_Uri のサブクラスのインスタンスを作成しません。しかし、いったん Zend_Uri のサブクラスのインスタンスを (新規に、あるいは既存のものから) 作成し、それを操作した後でもまだ妥当な形式であるかどうかを調べることもできます。

例8 Zend_Uri_* オブジェクトの検証

$uri = Zend_Uri::factory('http://www.zend.com');
 
$isValid = $uri->valid();  // TRUE

インスタンスメソッド valid() により、 URI オブジェクトが妥当なものかどうかを調べることができます。

^[1] 現時点では、およびに対する組み込みサポートだけをでは提供しています。

Zend_Uri

Zend_Uri
プログラマ向けリファレンスガイド

Zend_Validate

Comments

Posted by: cyril bele on: 2010-04-14 13:49:56 ⁋

It is really a pity that the creator of the class hardcoded the allowed URI scheme, especially when only allow HTTP(s) is allowed

Here is the bad code

switch ($scheme) {
case 'http':
// Break intentionally omitted
case 'https':
$className = 'Zend_Uri_Http';
break;

case 'mailto':
// TODO
default:
require_once 'Zend/Uri/Exception.php';
throw new Zend_Uri_Exception("Scheme \"$scheme\" is not supported");
break;
}

Especially a pity when zend loader is called thus something a la zend_serializer could be done where user can create their own implementation

Posted by: Hervé Piedvache on: 2010-05-30 12:55:06 ⁋

I fully agree with Cyril ... we are blocked here with a really bad basic object usage ...

Posted by: Hervé Piedvache on: 2010-05-30 12:55:27 ⁋

I fully agree with Cyril ... we are blocked here with a really bad basic object usage ...