documentation/manual/ja/module_specs/Zend_Uri.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 20799 -->
   4 <sect1 id="zend.uri.chapter">
   5     <title>Zend_Uri</title>
   6
   7     <sect2 id="zend.uri.overview">
   8         <title>概要</title>
   9
  10         <para>
  11             <classname>Zend_Uri</classname> は、 <ulink
  12              url="http://www.w3.org/Addressing/">Uniform Resource Identifiers</ulink>
  13               (<acronym>URI</acronym>s) の操作および検証を行うためのコンポーネントです。
  14             <classname>Zend_Uri</classname> の本来の目的は
  15             <classname>Zend_Http_Client</classname> のような他のコンポーネントを支援することですが、
  16             単体で使用しても便利です。
  17         </para>
  18
  19         <para>
  20             <acronym>URI</acronym> の最初は常にスキームから始まり、その後にコロンが続きます。
  21             スキームにはさまざまなものがあります。
  22             <classname>Zend_Uri</classname> クラスは、
  23             各スキームに特化した自身のサブクラスを返すファクトリメソッドを提供しています。
  24             サブクラスの名前は <classname>Zend_Uri_&lt;scheme&gt;</classname>
  25             となり、<code>&lt;scheme&gt;</code> の部分には
  26             スキーム名の最初の文字だけを大文字にしたものがあてはまります。
  27             この規則にはひとつ例外があり、<acronym>HTTPS</acronym> スキームについては
  28             <classname>Zend_Uri_Http</classname> で扱われます。
  29         </para>
  30     </sect2>
  31
  32     <sect2 id="zend.uri.creation">
  33         <title>新しい URI の作成</title>
  34
  35         <para>
  36             スキームのみを <methodname>Zend_Uri::factory()</methodname> に渡すと、
  37             <classname>Zend_Uri</classname> は新しい <acronym>URI</acronym> をゼロから作成します。
  38         </para>
  39
  40         <example id="zend.uri.creation.example-1">
  41             <title>Zend_Uri::factory() による新しい URI の作成</title>
  42
  43             <programlisting language="php"><![CDATA[
  44 // 何もないところから新しい URI を作成するには、スキームのみを渡します
  45 $uri = Zend_Uri::factory('http');
  46
  47 // $uri は Zend_Uri_Http のインスタンスとなります
  48 ]]></programlisting>
  49         </example>
  50
  51         <para>
  52             新しい <acronym>URI</acronym> を作成するには、スキームのみを
  53             <methodname>Zend_Uri::factory()</methodname> に渡します
  54             <footnote><para>現時点では、
  55             <classname>Zend_Uri</classname> がサポートしているスキームは <acronym>HTTP</acronym> および <acronym>HTTPS</acronym> だけです。</para></footnote>。
  56             サポートしていないスキームが渡された場合は、
  57             <classname>Zend_Uri_Exception</classname> がスローされます。
  58         </para>
  59
  60         <para>
  61             渡されたスキームあるいは <acronym>URI</acronym> をサポートしている場合は、
  62             <methodname>Zend_Uri::factory()</methodname> は自分自身のサブクラスを返します。
  63             これは、指定したスキームに特化したものとなります。
  64         </para>
  65     </sect2>
  66
  67     <sect2 id="zend.uri.manipulation">
  68         <title>既存の URI の操作</title>
  69
  70         <para>
  71             既存の <acronym>URI</acronym> を操作するには、完全な <acronym>URI</acronym> を
  72             <methodname>Zend_Uri::factory()</methodname> に渡します。
  73         </para>
  74
  75         <example id="zend.uri.manipulation.example-1">
  76             <title>Zend_Uri::factory() による既存の URI の操作</title>
  77
  78             <programlisting language="php"><![CDATA[
  79 // 既存の URI を操作するには、それを渡します
  80 $uri = Zend_Uri::factory('http://www.zend.com');
  81
  82 // $uri は Zend_Uri_Http のインスタンスです
  83 ]]></programlisting>
  84         </example>
  85
  86         <para>
  87             このとき、<acronym>URI</acronym> のパースと検証が行われます。
  88             もし妥当な形式でなかった場合は、そこで
  89             <classname>Zend_Uri_Exception</classname> がスローされます。それ以外の場合は
  90             <methodname>Zend_Uri::factory()</methodname> は自分自身のサブクラスを返します。
  91             これは、操作するスキームに特化したものとなります。
  92         </para>
  93     </sect2>
  94
  95     <sect2 id="zend.uri.validation">
  96         <title>URI の検証</title>
  97
  98         <para>
  99             <methodname>Zend_Uri::check()</methodname> 関数を使用すると、
 100             既存の <acronym>URI</acronym> の検証のみを行うことができます。
 101         </para>
 102
 103         <example id="zend.uri.validation.example-1">
 104             <title>Zend_Uri::check() による URI の検証</title>
 105
 106             <programlisting language="php"><![CDATA[
 107 // 指定した URI が正しい形式かどうかを調べます
 108 $valid = Zend_Uri::check('http://uri.in.question');
 109
 110 // $valid は、正しければ TRUE、そうでなければ FALSE となります
 111 ]]></programlisting>
 112         </example>
 113
 114         <para>
 115             <methodname>Zend_Uri::check()</methodname> は boolean 値を返します。
 116             これは <methodname>Zend_Uri::factory()</methodname>
 117             を使用して例外を処理するよりも便利です。
 118         </para>
 119
 120         <sect3 id="zend.uri.validation.allowunwise">
 121             <title>URL 内での "Unwise" 文字の許可</title>
 122
 123             <para>
 124                 デフォルトでは、<classname>Zend_Uri</classname> は次の文字を許可しません。
 125                 <code>"{", "}", "|", "\", "^", "`"</code>
 126                 これらは <acronym>RFC</acronym> で "unwise" と定義されており無効なものです。
 127                 しかし、多くの実装ではこれらの文字を妥当なものとして扱います。
 128             </para>
 129
 130             <para>
 131                 <classname>Zend_Uri</classname> でもこれらの "unwise" 文字を許可することができます。
 132                 そのためには、<methodname>Zend_Uri::setConfig()</methodname> メソッドで
 133                 'allow_unwise' オプションを <constant>TRUE</constant> に設定します。
 134             </para>
 135
 136             <example id="zend.uri.validation.allowunwise.example-1">
 137                 <title>URI における特殊文字の許可</title>
 138
 139                 <programlisting language="php"><![CDATA[
 140 // '|' 記号を含んでいます
 141 // 通常は、これは false を返します
 142 $valid = Zend_Uri::check('http://example.com/?q=this|that');
 143
 144 // しかし、"unwise" 文字を許可することもできます
 145 Zend_Uri::setConfig(array('allow_unwise' => true));
 146 // これは 'true' を返します
 147 $valid = Zend_Uri::check('http://example.com/?q=this|that');
 148
 149 // 'allow_unwise' の値をデフォルトの FALSE に戻します
 150 Zend_Uri::setConfig(array('allow_unwise' => false));
 151 ]]></programlisting>
 152             </example>
 153
 154             <note>
 155                 <para>
 156                     <methodname>Zend_Uri::setConfig()</methodname> は、全体の設定オプションを変更します。
 157                     そのため、上の例のように最後は 'allow_unwise' を '<constant>FALSE</constant>'
 158                     に戻すことを推奨します。unwise な文字を常に許可したいという場合は別です。
 159                 </para>
 160             </note>
 161         </sect3>
 162     </sect2>
 163
 164     <sect2 id="zend.uri.instance-methods">
 165         <title>共通のインスタンスメソッド</title>
 166
 167         <para>
 168             すべての <classname>Zend_Uri</classname> のサブクラス (例
 169             <classname>Zend_Uri_Http</classname>) のインスタンスには、
 170             <acronym>URI</acronym> 操作のために便利なインスタンスメソッドがいくつか提供されています。
 171         </para>
 172
 173         <sect3 id="zend.uri.instance-methods.getscheme">
 174             <title>URI のスキームの取得</title>
 175
 176             <para>
 177                 <acronym>URI</acronym> のスキームとは、<acronym>URI</acronym> でカンマの前にくる部分のことです。
 178                 たとえば <code>http://www.zend.com</code> のスキームは
 179                 <code>http</code> となります。
 180             </para>
 181
 182             <example id="zend.uri.instance-methods.getscheme.example-1">
 183                 <title>Zend_Uri_* オブジェクトからのスキームの取得</title>
 184
 185                 <programlisting language="php"><![CDATA[
 186 $uri = Zend_Uri::factory('http://www.zend.com');
 187
 188 $scheme = $uri->getScheme();  // "http"
 189 ]]></programlisting>
 190             </example>
 191
 192             <para>
 193                 インスタンスメソッド <methodname>getScheme()</methodname> は、
 194                 <acronym>URI</acronym> オブジェクトからスキームの部分のみを返します。
 195             </para>
 196
 197         </sect3>
 198
 199         <sect3 id="zend.uri.instance-methods.geturi">
 200             <title>URI 全体の取得</title>
 201
 202             <example id="zend.uri.instance-methods.geturi.example-1">
 203                 <title>Zend_Uri_* オブジェクトからの URI 全体の取得</title>
 204
 205                 <programlisting language="php"><![CDATA[
 206 $uri = Zend_Uri::factory('http://www.zend.com');
 207
 208 echo $uri->getUri();  // "http://www.zend.com"
 209 ]]></programlisting>
 210             </example>
 211
 212             <para>
 213                 <methodname>getUri()</methodname> メソッドは、<acronym>URI</acronym> 全体を文字列として返します。
 214             </para>
 215         </sect3>
 216
 217         <sect3 id="zend.uri.instance-methods.valid">
 218             <title>URI の検証</title>
 219
 220             <para>
 221                 <methodname>Zend_Uri::factory()</methodname> は渡された <acronym>URI</acronym> を常に検証しており、
 222                 渡された <acronym>URI</acronym> が無効な場合は <classname>Zend_Uri</classname>
 223                 のサブクラスのインスタンスを作成しません。しかし、いったん
 224                 <classname>Zend_Uri</classname> のサブクラスのインスタンスを
 225                 (新規に、あるいは既存のものから) 作成し、
 226                 それを操作した後でもまだ妥当な形式であるかどうかを調べることもできます。
 227             </para>
 228
 229             <example id="zend.uri.instance-methods.valid.example-1">
 230                 <title>Zend_Uri_* オブジェクトの検証</title>
 231
 232                     <programlisting language="php"><![CDATA[
 233 $uri = Zend_Uri::factory('http://www.zend.com');
 234
 235 $isValid = $uri->valid();  // TRUE
 236 ]]></programlisting>
 237             </example>
 238
 239             <para>
 240                 インスタンスメソッド <methodname>valid()</methodname> により、
 241                 <acronym>URI</acronym> オブジェクトが妥当なものかどうかを調べることができます。
 242             </para>
 243         </sect3>
 244     </sect2>
 245 </sect1>
 246 <!--
 247 vim:se ts=4 sw=4 et:
 248 -->