repo_zf1/documentation/manual/ja/module_specs/Zend_Uri.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 24249 -->
<sect1 id="zend.uri.chapter">
    <title>Zend_Uri(日本語)</title>

    <sect2 id="zend.uri.overview">
        <title>概要</title>

        <para>
            <classname>Zend_Uri</classname> は、 <ulink
             url="http://www.w3.org/Addressing/">Uniform Resource Identifiers</ulink>
              (<acronym>URI</acronym>s) の操作および検証を行うためのコンポーネントです。
            <classname>Zend_Uri</classname> の本来の目的は
            <classname>Zend_Http_Client</classname> のような他のコンポーネントを支援することですが、
            単体で使用しても便利です。
        </para>

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

    <sect2 id="zend.uri.creation">
        <title>新しい URI の作成</title>

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

        <example id="zend.uri.creation.example-1">
            <title>Zend_Uri::factory() による新しい URI の作成</title>

            <programlisting language="php"><![CDATA[
// 何もないところから新しい URI を作成するには、スキームのみを渡します
$uri = Zend_Uri::factory('http');

// $uri は Zend_Uri_Http のインスタンスとなります
]]></programlisting>
        </example>

        <para>
            新しい <acronym>URI</acronym> を作成するには、スキームのみを
            <methodname>Zend_Uri::factory()</methodname> に渡します
            <footnote><para>
            現時点では、
             <acronym>HTTP</acronym> および <acronym>HTTPS</acronym> に対する組み込みサポートだけを
            <classname>Zend_Uri</classname> では提供しています。
             </para></footnote>。
            サポートしていないスキームが渡された場合は、
            <classname>Zend_Uri_Exception</classname> がスローされます。
        </para>

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

        <!-- TODO : to be translated -->
        <sect3>
            <title>Creating a New Custom-Class URI</title>
            
            <para>
                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 
                <methodname>Zend_Uri::factory()</methodname> 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. 
            </para>
            
            <para>
                The 2nd parameter passed to <methodname>Zend_Uri::factory()</methodname> must
                be a string with the name of a class extending <classname>Zend_Uri</classname>. 
                The class must either be alredy-loaded, or loadable using <methodname>Zend_Loader::loadClass()</methodname> - 
                that is, it must follow the Zend Framework class and file naming conventions, and 
                must be in your include_path.   
            </para>
            
            <example id="zend.uri.creation.custom.example-1">
                <title>Creating a URI using a custom class</title>
                
                <programlisting language="php"><![CDATA[
// 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 
]]></programlisting>
            </example>
        </sect3>
    </sect2>

    <sect2 id="zend.uri.manipulation">
        <title>既存の URI の操作</title>

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

        <example id="zend.uri.manipulation.example-1">
            <title>Zend_Uri::factory() による既存の URI の操作</title>

            <programlisting language="php"><![CDATA[
// 既存の URI を操作するには、それを渡します
$uri = Zend_Uri::factory('http://www.zend.com');

// $uri は Zend_Uri_Http のインスタンスです
]]></programlisting>
        </example>

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

    <sect2 id="zend.uri.validation">
        <title>URI の検証</title>

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

        <example id="zend.uri.validation.example-1">
            <title>Zend_Uri::check() による URI の検証</title>

            <programlisting language="php"><![CDATA[
// 指定した URI が正しい形式かどうかを調べます
$valid = Zend_Uri::check('http://uri.in.question');

// $valid は、正しければ TRUE、そうでなければ FALSE となります
]]></programlisting>
        </example>

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

        <sect3 id="zend.uri.validation.allowunwise">
            <title>URL 内での "Unwise" 文字の許可</title>

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

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

            <example id="zend.uri.validation.allowunwise.example-1">
                <title>URI における特殊文字の許可</title>

                <programlisting language="php"><![CDATA[
// '|' 記号を含んでいます
// 通常は、これは 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));
]]></programlisting>
            </example>

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

    <sect2 id="zend.uri.instance-methods">
        <title>共通のインスタンスメソッド</title>

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

        <sect3 id="zend.uri.instance-methods.getscheme">
            <title>URI のスキームの取得</title>

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

            <example id="zend.uri.instance-methods.getscheme.example-1">
                <title>Zend_Uri_* オブジェクトからのスキームの取得</title>

                <programlisting language="php"><![CDATA[
$uri = Zend_Uri::factory('http://www.zend.com');

$scheme = $uri->getScheme();  // "http"
]]></programlisting>
            </example>

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

        </sect3>

        <sect3 id="zend.uri.instance-methods.geturi">
            <title>URI 全体の取得</title>

            <example id="zend.uri.instance-methods.geturi.example-1">
                <title>Zend_Uri_* オブジェクトからの URI 全体の取得</title>

                <programlisting language="php"><![CDATA[
$uri = Zend_Uri::factory('http://www.zend.com');

echo $uri->getUri();  // "http://www.zend.com"
]]></programlisting>
            </example>

            <para>
                <methodname>getUri()</methodname> メソッドは、<acronym>URI</acronym> 全体を文字列として返します。
            </para>
        </sect3>

        <sect3 id="zend.uri.instance-methods.valid">
            <title>URI の検証</title>

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

            <example id="zend.uri.instance-methods.valid.example-1">
                <title>Zend_Uri_* オブジェクトの検証</title>

                    <programlisting language="php"><![CDATA[
$uri = Zend_Uri::factory('http://www.zend.com');

$isValid = $uri->valid();  // TRUE
]]></programlisting>
            </example>

            <para>
                インスタンスメソッド <methodname>valid()</methodname> により、
                <acronym>URI</acronym> オブジェクトが妥当なものかどうかを調べることができます。
            </para>
        </sect3>
    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->