documentation/manual/en/module_specs/Zend_Uri.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.uri.chapter">
   4     <title>Zend_Uri</title>
   5
   6     <sect2 id="zend.uri.overview">
   7         <title>Overview</title>
   8
   9         <para>
  10             <classname>Zend_Uri</classname> is a component that aids in manipulating and validating
  11             <ulink url="http://www.w3.org/Addressing/">Uniform Resource Identifiers</ulink> (URIs).
  12             <classname>Zend_Uri</classname> exists primarily to service other components, such as
  13             <classname>Zend_Http_Client</classname>, but is also useful as a standalone utility.
  14         </para>
  15
  16         <para>
  17             <acronym>URI</acronym>s always begin with a scheme, followed by a colon. The
  18             construction of the many different schemes varies significantly. The
  19             <classname>Zend_Uri</classname> class provides a factory that returns a subclass
  20             of itself which specializes in each scheme. The subclass will be named
  21             <classname>Zend_Uri_&lt;scheme&gt;</classname>, where <code>&lt;scheme&gt;</code>
  22             is the scheme, lowercased with the first letter capitalized. An exception to this
  23             rule is <acronym>HTTPS</acronym>, which is also handled by
  24             <classname>Zend_Uri_Http</classname>.
  25         </para>
  26     </sect2>
  27
  28     <sect2 id="zend.uri.creation">
  29         <title>Creating a New URI</title>
  30
  31         <para>
  32             <classname>Zend_Uri</classname> will build a new <acronym>URI</acronym> from scratch
  33             if only a scheme is passed to <methodname>Zend_Uri::factory()</methodname>.
  34         </para>
  35
  36         <example id="zend.uri.creation.example-1">
  37             <title>Creating a New URI with Zend_Uri::factory()</title>
  38
  39             <programlisting language="php"><![CDATA[
  40 // To create a new URI from scratch, pass only the scheme.
  41 $uri = Zend_Uri::factory('http');
  42
  43 // $uri instanceof Zend_Uri_Http
  44 ]]></programlisting>
  45         </example>
  46
  47         <para>
  48             To create a new <acronym>URI</acronym> from scratch, pass only the scheme to
  49             <methodname>Zend_Uri::factory()</methodname><footnote><para>At the time of writing,
  50             <classname>Zend_Uri</classname> only supports the <acronym>HTTP</acronym> and
  51             <acronym>HTTPS</acronym> schemes.</para></footnote>. If an unsupported scheme is
  52             passed, a <classname>Zend_Uri_Exception</classname> will be thrown.
  53         </para>
  54
  55         <para>
  56             If the scheme or <acronym>URI</acronym> passed is supported,
  57             <methodname>Zend_Uri::factory()</methodname> will return a subclass of itself that
  58             specializes in the scheme to be created.
  59         </para>
  60     </sect2>
  61
  62     <sect2 id="zend.uri.manipulation">
  63         <title>Manipulating an Existing URI</title>
  64
  65         <para>
  66             To manipulate an existing <acronym>URI</acronym>, pass the entire <acronym>URI</acronym>
  67             to <methodname>Zend_Uri::factory()</methodname>.
  68         </para>
  69
  70         <example id="zend.uri.manipulation.example-1">
  71             <title>Manipulating an Existing URI with Zend_Uri::factory()</title>
  72
  73             <programlisting language="php"><![CDATA[
  74 // To manipulate an existing URI, pass it in.
  75 $uri = Zend_Uri::factory('http://www.zend.com');
  76
  77 // $uri instanceof Zend_Uri_Http
  78 ]]></programlisting>
  79         </example>
  80
  81         <para>
  82             The <acronym>URI</acronym> will be parsed and validated. If it is found to be invalid,
  83             a <classname>Zend_Uri_Exception</classname> will be thrown immediately. Otherwise,
  84             <methodname>Zend_Uri::factory()</methodname> will return a subclass of itself that
  85             specializes in the scheme to be manipulated.
  86         </para>
  87     </sect2>
  88
  89     <sect2 id="zend.uri.validation">
  90         <title>URI Validation</title>
  91
  92         <para>
  93             The <methodname>Zend_Uri::check()</methodname> method can only be used if validation
  94             of an existing <acronym>URI</acronym> is needed.
  95         </para>
  96
  97         <example id="zend.uri.validation.example-1">
  98             <title>URI Validation with Zend_Uri::check()</title>
  99
 100             <programlisting language="php"><![CDATA[
 101 // Validate whether a given URI is well formed
 102 $valid = Zend_Uri::check('http://uri.in.question');
 103
 104 // $valid is TRUE for a valid URI, or FALSE otherwise.
 105 ]]></programlisting>
 106         </example>
 107
 108         <para>
 109             <methodname>Zend_Uri::check()</methodname> returns a boolean, which is more convenient
 110             than using <methodname>Zend_Uri::factory()</methodname> and catching the exception.
 111         </para>
 112
 113         <sect3 id="zend.uri.validation.allowunwise">
 114             <title>Allowing "Unwise" characters in URIs</title>
 115
 116             <para>
 117                 By default, <classname>Zend_Uri</classname> will not accept the following
 118                 characters: <code>"{", "}", "|", "\", "^", "`"</code>. These characters are defined
 119                 by the <acronym>RFC</acronym> as "unwise" and invalid; however, many
 120                 implementations do accept these characters as valid.
 121             </para>
 122
 123             <para>
 124                 <classname>Zend_Uri</classname> can be set to accept these "unwise" characters by
 125                 setting the 'allow_unwise' option to boolean <constant>TRUE</constant> using
 126                 <methodname>Zend_Uri::setConfig()</methodname>:
 127             </para>
 128
 129             <example id="zend.uri.validation.allowunwise.example-1">
 130                 <title>Allowing special characters in URIs</title>
 131
 132                 <programlisting language="php"><![CDATA[
 133 // Contains '|' symbol
 134 // Normally, this would return false:
 135 $valid = Zend_Uri::check('http://example.com/?q=this|that');
 136
 137 // However, you can allow "unwise" characters
 138 Zend_Uri::setConfig(array('allow_unwise' => true));
 139
 140 // will return 'true'
 141 $valid = Zend_Uri::check('http://example.com/?q=this|that');
 142
 143 // Reset the 'allow_unwise' value to the default FALSE
 144 Zend_Uri::setConfig(array('allow_unwise' => false));
 145 ]]></programlisting>
 146             </example>
 147
 148             <note>
 149                 <para>
 150                     <methodname>Zend_Uri::setConfig()</methodname> sets configuration options
 151                     globally. It is recommended to reset the 'allow_unwise' option to
 152                     '<constant>FALSE</constant>', like in the example above, unless you are certain
 153                     you want to always allow unwise characters globally.
 154                 </para>
 155             </note>
 156         </sect3>
 157     </sect2>
 158
 159     <sect2 id="zend.uri.instance-methods">
 160         <title>Common Instance Methods</title>
 161
 162         <para>
 163             Every instance of a <classname>Zend_Uri</classname> subclass (e.g.
 164             <classname>Zend_Uri_Http</classname>) has several instance methods that are useful for
 165             working with any kind of <acronym>URI</acronym>.
 166         </para>
 167
 168         <sect3 id="zend.uri.instance-methods.getscheme">
 169             <title>Getting the Scheme of the URI</title>
 170
 171             <para>
 172                 The scheme of the <acronym>URI</acronym> is the part of the <acronym>URI</acronym>
 173                 that precedes the colon. For example, the scheme of
 174                 <code>http://www.zend.com</code> is <code>http</code>.
 175             </para>
 176
 177             <example id="zend.uri.instance-methods.getscheme.example-1">
 178                 <title>Getting the Scheme from a Zend_Uri_* Object</title>
 179
 180                 <programlisting language="php"><![CDATA[
 181 $uri = Zend_Uri::factory('http://www.zend.com');
 182
 183 $scheme = $uri->getScheme();  // "http"
 184 ]]></programlisting>
 185             </example>
 186
 187             <para>
 188                 The <methodname>getScheme()</methodname> instance method returns only the scheme
 189                 part of the <acronym>URI</acronym> object.
 190             </para>
 191         </sect3>
 192
 193         <sect3 id="zend.uri.instance-methods.geturi">
 194             <title>Getting the Entire URI</title>
 195
 196             <example id="zend.uri.instance-methods.geturi.example-1">
 197                 <title>Getting the Entire URI from a Zend_Uri_* Object</title>
 198
 199                 <programlisting language="php"><![CDATA[
 200 $uri = Zend_Uri::factory('http://www.zend.com');
 201
 202 echo $uri->getUri();  // "http://www.zend.com"
 203 ]]></programlisting>
 204             </example>
 205
 206             <para>
 207                 The <methodname>getUri()</methodname> method returns the string representation
 208                 of the entire <acronym>URI</acronym>.
 209             </para>
 210         </sect3>
 211
 212         <sect3 id="zend.uri.instance-methods.valid">
 213             <title>Validating the URI</title>
 214
 215             <para>
 216                 <methodname>Zend_Uri::factory()</methodname> will always validate any
 217                 <acronym>URI</acronym> passed to it and will not instantiate a new
 218                 <classname>Zend_Uri</classname> subclass if the given <acronym>URI</acronym> is
 219                 found to be invalid. However, after the <classname>Zend_Uri</classname> subclass is
 220                 instantiated for a new <acronym>URI</acronym> or an existing valid one, it is
 221                 possible that the <acronym>URI</acronym> can later become invalid after it
 222                 is manipulated.
 223             </para>
 224
 225             <example id="zend.uri.instance-methods.valid.example-1">
 226                 <title>Validating a Zend_Uri_* Object</title>
 227
 228                 <programlisting language="php"><![CDATA[
 229 $uri = Zend_Uri::factory('http://www.zend.com');
 230
 231 $isValid = $uri->valid();  // TRUE
 232 ]]></programlisting>
 233             </example>
 234
 235             <para>
 236                 The <methodname>valid()</methodname> instance method provides a means to check that
 237                 the <acronym>URI</acronym> object is still valid.
 238             </para>
 239         </sect3>
 240     </sect2>
 241 </sect1>
 242 <!--
 243 vim:se ts=4 sw=4 et:
 244 -->