documentation/manual/ru/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>Обзор</title>
   8
   9     <para>
  10       <classname>Zend_Uri</classname> является компонентой, которая призвана облегчить
  11       работу с URI (<ulink url="http://www.w3.org/Addressing/">Uniform Resource
  12       Identifiers</ulink>) и их валидацию. <classname>Zend_Uri</classname> был создан для
  13       обслуживания других компонент, таких, как <classname>Zend_Http_Client</classname>,
  14       но полезен и как отдельная утилита.
  15     </para>
  16
  17     <para>
  18       URI всегда начинаются со схемы, после которой следует двоеточие. Структура
  19       для разных схем может сильно отличаться. Класс <classname>Zend_Uri</classname>
  20       предоставляет фабрику (паттерн factory), которая возвращает его подклассы,
  21       специализирующиеся в различных схемах. Подклассы называются
  22       <classname>Zend_Uri_&lt;scheme&gt;</classname>, где <code>&lt;scheme&gt;</code> -
  23       схема в нижнем регистре, с прописной первой буквой. Исключением из этого
  24       правила является HTTPS, который обрабатывается подклассом
  25       <classname>Zend_Uri_Http</classname>.
  26     </para>
  27   </sect2>
  28
  29   <sect2 id="zend.uri.creation">
  30     <title>Создание нового URI</title>
  31
  32     <para>
  33       <classname>Zend_Uri</classname> будет строить с нуля новый URI, если
  34       <code>Zend_Uri::factory()</code> была передана только схема.
  35     </para>
  36
  37     <example id="zend.uri.creation.example-1">
  38       <title>Создание нового URI с Zend_Uri::factory()</title>
  39
  40       <programlisting language="php"><![CDATA[
  41 // Для того, чтобы создать с нуля новый URI, передайте только схему.
  42 $uri = Zend_Uri::factory('http');
  43
  44 // $uri является экземпляром Zend_Uri_Http
  45 ]]></programlisting>
  46     </example>
  47
  48     <para>
  49       Для того, чтобы создать с нуля новый URI, передайте
  50       <code>Zend_Uri::factory()</code> только схему. <footnote><para>На момент
  51       написания этой документации Zend_Uri поддерживает только схемы HTTP и
  52       HTTPS.</para></footnote>. При передаче не поддерживаемой схемы
  53       генерируется исключение <classname>Zend_Uri_Exception</classname>.
  54     </para>
  55
  56     <para>
  57       Если переданные схема или URI поддерживаются, то
  58       <code>Zend_Uri::factory()</code> вернет свой подкласс, который
  59       специализируется на данной схеме.
  60     </para>
  61   </sect2>
  62
  63   <sect2 id="zend.uri.manipulation">
  64     <title>Работа с существующим URI</title>
  65
  66     <para>
  67       Для того, чтобы работать с существующим URI, передайте его весь целиком
  68       <code>Zend_Uri::factory()</code>.
  69     </para>
  70
  71     <example id="zend.uri.manipulation.example-1">
  72       <title>Работа с существующим URI через Zend_Uri::factory()</title>
  73
  74     <programlisting language="php"><![CDATA[
  75 // Чтобы работать с существующим URI, передайте его как параметр
  76 $uri = Zend_Uri::factory('http://www.zend.com');
  77
  78 // $uri является экземпляром Zend_Uri_Http
  79 ]]></programlisting>
  80     </example>
  81
  82     <para>
  83       URI будет распарсен и проверен на валидность. Если он оказался невалидным,
  84       то сразу же будет сгенерировано исключение
  85       <classname>Zend_Uri_Exception</classname>. Иначе <code>Zend_Uri::factory()</code>
  86       вернет свой подкласс, который специализируется на данной схеме.
  87     </para>
  88   </sect2>
  89
  90   <sect2 id="zend.uri.validation">
  91     <title>Проверка URI</title>
  92
  93     <para>
  94       Функция <code>Zend_Uri::check()</code> может использоваться в том случае,
  95       когда нужна только проверка существующего URI.
  96     </para>
  97
  98     <example id="zend.uri.validation.example-1">
  99       <title>Проверка URI с помощью Zend_Uri::check()</title>
 100
 101     <programlisting language="php"><![CDATA[
 102 // Проверка, является ли данный URI синтаксически корректным
 103 $valid = Zend_Uri::check('http://uri.in.question');
 104
 105 // $valid равен TRUE при валидном URI, иначе FALSE
 106 ]]></programlisting>
 107     </example>
 108
 109     <para>
 110       <code>Zend_Uri::check()</code> возвращает булево значение, использование
 111       этой функции более удобно, чем вызов <code>Zend_Uri::factory()</code> и
 112       отлов исключения.
 113     </para>
 114
 115     <sect3 id="zend.uri.validation.allowunwise">
 116         <title>Разрешение использования "неумных" символов в URI</title>
 117
 118         <para>
 119             По умолчанию <classname>Zend_Uri</classname> не будет принимать
 120             следующие символы, которые в спецификации определены как "неумные"
 121             (unwise) и невалидные: <code>"{", "}", "|", "\", "^", "`"</code>.
 122             Тем не менее, многие реализации принимают эти символы как валидные.
 123         </para>
 124
 125         <para>
 126             Можно заставить <classname>Zend_Uri</classname> принимать эти
 127             символы путем установки 'allow_unwise' в TRUE, используя метод
 128             <code>Zend_Uri::setConfig()</code>:
 129         </para>
 130
 131         <example id="zend.uri.validation.allowunwise.example-1">
 132             <title>Разрешение использования спецсимволов в URI</title>
 133             <programlisting language="php"><![CDATA[
 134 // Содержит символ '|'
 135 // Обычно такой вызов будет возвращать 'false':
 136 $valid = Zend_Uri::check('http://example.com/?q=this|that');
 137
 138 // Тем не менее, вы можете разрешить "неумные" символы
 139 Zend_Uri::setConfig(array('allow_unwise' => true));
 140 // будет возвращать 'true'
 141 $valid = Zend_Uri::check('http://example.com/?q=this|that');
 142
 143 // Установка 'allow_unwise' обратно в FALSE
 144 Zend_Uri::setConfig(array('allow_unwise' => false));
 145 ]]></programlisting>
 146         </example>
 147
 148         <note>
 149             <para>
 150                 <code>Zend_Uri::setConfig()</code> глобально устанавливает опции
 151                 конфигурации. Рекомендуется сбрасывать опцию
 152                 'allow_unwise' в 'false', как показано в примере выше,
 153                 если только вы не хотите разрешить использование "неумных"
 154                 символов на все время во всем приложении.
 155             </para>
 156         </note>
 157     </sect3>
 158   </sect2>
 159
 160   <sect2 id="zend.uri.instance-methods">
 161     <title>Общие методы экземпляров</title>
 162
 163     <para>
 164       Каждый экземпляр подкласса <classname>Zend_Uri</classname> (например,
 165       <classname>Zend_Uri_Http</classname>) имеет несколько методов,
 166       полезных для работы с любыми видами URI.
 167     </para>
 168
 169     <sect3 id="zend.uri.instance-methods.getscheme">
 170       <title>Получение схемы URI</title>
 171
 172       <para>
 173         Схема URI – часть URI, завершающаяся двоеточием. Например, схемой в
 174         <code>http://www.zend.com</code> является <code>http</code>.
 175       </para>
 176
 177       <example id="zend.uri.instance-methods.getscheme.example-1">
 178         <title>Получение схемы из объекта Zend_Uri_*</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         Метод экземпляра <code>getScheme()</code> возвращает схему из URI.
 189       </para>
 190
 191     </sect3>
 192
 193     <sect3 id="zend.uri.instance-methods.geturi">
 194       <title>Получение всего URI</title>
 195
 196       <example id="zend.uri.instance-methods.geturi.example-1">
 197         <title>Получение всего URI из объекта Zend_Uri_*</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         Метод <code>getUri()</code> возвращает строковое представление всего
 208         URI.
 209       </para>
 210     </sect3>
 211
 212     <sect3 id="zend.uri.instance-methods.valid">
 213       <title>Проверка URI на валидность</title>
 214
 215       <para>
 216         <code>Zend_Uri::factory()</code> всегда производит синтаксическую
 217         проверку переданных ему URI и не будет создавать новый экземпляр
 218         подкласса <classname>Zend_Uri</classname>, если данный URI не прошел проверку.
 219         Тем не менее, после того, как был инстанцирован подкласс
 220         <classname>Zend_Uri</classname> для нового URI или на основе уже существующего,
 221         в результате манипуляций с ним этот URI может стать невалидным.
 222       </para>
 223
 224       <example id="zend.uri.instance-methods.valid.example-1">
 225         <title>Проверка объекта Zend_Uri_*</title>
 226
 227         <programlisting language="php"><![CDATA[
 228 $uri = Zend_Uri::factory('http://www.zend.com');
 229
 230 $isValid = $uri->valid();  // TRUE
 231 ]]></programlisting>
 232       </example>
 233
 234       <para>
 235         Метод <code>valid()</code> дает возможность проверить, является ли URI
 236         по-прежнему валидным.
 237       </para>
 238     </sect3>
 239
 240   </sect2>
 241 </sect1>
 242 <!--
 243 vim:se ts=4 sw=4 et:
 244 -->