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 provides built-in support for the <acronym>HTTP</acronym>
  51             and <acronym>HTTPS</acronym> schemes.</para></footnote>. If an unsupported scheme is
  52             passed and no scheme-specific class is specified, a <classname>Zend_Uri_Exception</classname>
  53             will be thrown.
  54         </para>
  55
  56         <para>
  57             If the scheme or <acronym>URI</acronym> passed is supported,
  58             <methodname>Zend_Uri::factory()</methodname> will return a subclass of itself that
  59             specializes in the scheme to be created.
  60         </para>
  61
  62         <sect3>
  63             <title>Creating a New Custom-Class URI</title>
  64
  65             <para>
  66                 Starting from Zend Framework 1.10.5, you can specify a custom class to be
  67                 used when creating the Zend_Uri instance, as a second parameter to the
  68                 <methodname>Zend_Uri::factory()</methodname> method.
  69                 This enables you to subclass Zend_Uri and create your own custom URI classes,
  70                 and instantiate new URI objects based on your own custom classes.
  71             </para>
  72
  73             <para>
  74                 The 2nd parameter passed to <methodname>Zend_Uri::factory()</methodname> must
  75                 be a string with the name of a class extending <classname>Zend_Uri</classname>.
  76                 The class must either be alredy-loaded, or loadable using <methodname>Zend_Loader::loadClass()</methodname> -
  77                 that is, it must follow the Zend Framework class and file naming conventions, and
  78                 must be in your include_path.
  79             </para>
  80
  81             <example id="zend.uri.creation.custom.example-1">
  82                 <title>Creating a URI using a custom class</title>
  83
  84                 <programlisting language="php"><![CDATA[
  85 // Create a new 'ftp' URI based on a custom class
  86 $ftpUri = Zend_Uri::factory(
  87     'ftp://user@ftp.example.com/path/file',
  88     'MyLibrary_Uri_Ftp'
  89 );
  90
  91 // $ftpUri is an instance of MyLibrary_Uri_Ftp, which is a subclass of Zend_Uri
  92 ]]></programlisting>
  93             </example>
  94         </sect3>
  95
  96     </sect2>
  97
  98     <sect2 id="zend.uri.manipulation">
  99         <title>Manipulating an Existing URI</title>
 100
 101         <para>
 102             To manipulate an existing <acronym>URI</acronym>, pass the entire <acronym>URI</acronym>
 103             to <methodname>Zend_Uri::factory()</methodname>.
 104         </para>
 105
 106         <example id="zend.uri.manipulation.example-1">
 107             <title>Manipulating an Existing URI with Zend_Uri::factory()</title>
 108
 109             <programlisting language="php"><![CDATA[
 110 // To manipulate an existing URI, pass it in.
 111 $uri = Zend_Uri::factory('http://www.zend.com');
 112
 113 // $uri instanceof Zend_Uri_Http
 114 ]]></programlisting>
 115         </example>
 116
 117         <para>
 118             The <acronym>URI</acronym> will be parsed and validated. If it is found to be invalid,
 119             a <classname>Zend_Uri_Exception</classname> will be thrown immediately. Otherwise,
 120             <methodname>Zend_Uri::factory()</methodname> will return a subclass of itself that
 121             specializes in the scheme to be manipulated.
 122         </para>
 123     </sect2>
 124
 125     <sect2 id="zend.uri.validation">
 126         <title>URI Validation</title>
 127
 128         <para>
 129             The <methodname>Zend_Uri::check()</methodname> method can only be used if validation
 130             of an existing <acronym>URI</acronym> is needed.
 131         </para>
 132
 133         <example id="zend.uri.validation.example-1">
 134             <title>URI Validation with Zend_Uri::check()</title>
 135
 136             <programlisting language="php"><![CDATA[
 137 // Validate whether a given URI is well formed
 138 $valid = Zend_Uri::check('http://uri.in.question');
 139
 140 // $valid is TRUE for a valid URI, or FALSE otherwise.
 141 ]]></programlisting>
 142         </example>
 143
 144         <para>
 145             <methodname>Zend_Uri::check()</methodname> returns a boolean, which is more convenient
 146             than using <methodname>Zend_Uri::factory()</methodname> and catching the exception.
 147         </para>
 148
 149         <sect3 id="zend.uri.validation.allowunwise">
 150             <title>Allowing "Unwise" characters in URIs</title>
 151
 152             <para>
 153                 By default, <classname>Zend_Uri</classname> will not accept the following
 154                 characters: <code>"{", "}", "|", "\", "^", "`"</code>. These characters are defined
 155                 by the <acronym>RFC</acronym> as "unwise" and invalid; however, many
 156                 implementations do accept these characters as valid.
 157             </para>
 158
 159             <para>
 160                 <classname>Zend_Uri</classname> can be set to accept these "unwise" characters by
 161                 setting the 'allow_unwise' option to boolean <constant>TRUE</constant> using
 162                 <methodname>Zend_Uri::setConfig()</methodname>:
 163             </para>
 164
 165             <example id="zend.uri.validation.allowunwise.example-1">
 166                 <title>Allowing special characters in URIs</title>
 167
 168                 <programlisting language="php"><![CDATA[
 169 // Contains '|' symbol
 170 // Normally, this would return false:
 171 $valid = Zend_Uri::check('http://example.com/?q=this|that');
 172
 173 // However, you can allow "unwise" characters
 174 Zend_Uri::setConfig(array('allow_unwise' => true));
 175
 176 // will return 'true'
 177 $valid = Zend_Uri::check('http://example.com/?q=this|that');
 178
 179 // Reset the 'allow_unwise' value to the default FALSE
 180 Zend_Uri::setConfig(array('allow_unwise' => false));
 181 ]]></programlisting>
 182             </example>
 183
 184             <note>
 185                 <para>
 186                     <methodname>Zend_Uri::setConfig()</methodname> sets configuration options
 187                     globally. It is recommended to reset the 'allow_unwise' option to
 188                     '<constant>FALSE</constant>', like in the example above, unless you are certain
 189                     you want to always allow unwise characters globally.
 190                 </para>
 191             </note>
 192         </sect3>
 193     </sect2>
 194
 195     <sect2 id="zend.uri.instance-methods">
 196         <title>Common Instance Methods</title>
 197
 198         <para>
 199             Every instance of a <classname>Zend_Uri</classname> subclass (e.g.
 200             <classname>Zend_Uri_Http</classname>) has several instance methods that are useful for
 201             working with any kind of <acronym>URI</acronym>.
 202         </para>
 203
 204         <sect3 id="zend.uri.instance-methods.getscheme">
 205             <title>Getting the Scheme of the URI</title>
 206
 207             <para>
 208                 The scheme of the <acronym>URI</acronym> is the part of the <acronym>URI</acronym>
 209                 that precedes the colon. For example, the scheme of
 210                 <code>http://www.zend.com</code> is <code>http</code>.
 211             </para>
 212
 213             <example id="zend.uri.instance-methods.getscheme.example-1">
 214                 <title>Getting the Scheme from a Zend_Uri_* Object</title>
 215
 216                 <programlisting language="php"><![CDATA[
 217 $uri = Zend_Uri::factory('http://www.zend.com');
 218
 219 $scheme = $uri->getScheme();  // "http"
 220 ]]></programlisting>
 221             </example>
 222
 223             <para>
 224                 The <methodname>getScheme()</methodname> instance method returns only the scheme
 225                 part of the <acronym>URI</acronym> object.
 226             </para>
 227         </sect3>
 228
 229         <sect3 id="zend.uri.instance-methods.geturi">
 230             <title>Getting the Entire URI</title>
 231
 232             <example id="zend.uri.instance-methods.geturi.example-1">
 233                 <title>Getting the Entire URI from a Zend_Uri_* Object</title>
 234
 235                 <programlisting language="php"><![CDATA[
 236 $uri = Zend_Uri::factory('http://www.zend.com');
 237
 238 echo $uri->getUri();  // "http://www.zend.com"
 239 ]]></programlisting>
 240             </example>
 241
 242             <para>
 243                 The <methodname>getUri()</methodname> method returns the string representation
 244                 of the entire <acronym>URI</acronym>.
 245             </para>
 246         </sect3>
 247
 248         <sect3 id="zend.uri.instance-methods.valid">
 249             <title>Validating the URI</title>
 250
 251             <para>
 252                 <methodname>Zend_Uri::factory()</methodname> will always validate any
 253                 <acronym>URI</acronym> passed to it and will not instantiate a new
 254                 <classname>Zend_Uri</classname> subclass if the given <acronym>URI</acronym> is
 255                 found to be invalid. However, after the <classname>Zend_Uri</classname> subclass is
 256                 instantiated for a new <acronym>URI</acronym> or an existing valid one, it is
 257                 possible that the <acronym>URI</acronym> can later become invalid after it
 258                 is manipulated.
 259             </para>
 260
 261             <example id="zend.uri.instance-methods.valid.example-1">
 262                 <title>Validating a Zend_Uri_* Object</title>
 263
 264                 <programlisting language="php"><![CDATA[
 265 $uri = Zend_Uri::factory('http://www.zend.com');
 266
 267 $isValid = $uri->valid();  // TRUE
 268 ]]></programlisting>
 269             </example>
 270
 271             <para>
 272                 The <methodname>valid()</methodname> instance method provides a means to check that
 273                 the <acronym>URI</acronym> object is still valid.
 274             </para>
 275         </sect3>
 276     </sect2>
 277 </sect1>
 278 <!--
 279 vim:se ts=4 sw=4 et:
 280 -->