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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.uri.chapter">
  <title>Zend_Uri</title>

  <sect2 id="zend.uri.overview">
    <title>Обзор</title>

    <para>
      <classname>Zend_Uri</classname> является компонентой, которая призвана облегчить
      работу с URI (<ulink url="http://www.w3.org/Addressing/">Uniform Resource
      Identifiers</ulink>) и их валидацию. <classname>Zend_Uri</classname> был создан для
      обслуживания других компонент, таких, как <classname>Zend_Http_Client</classname>,
      но полезен и как отдельная утилита.
    </para>

    <para>
      URI всегда начинаются со схемы, после которой следует двоеточие. Структура
      для разных схем может сильно отличаться. Класс <classname>Zend_Uri</classname>
      предоставляет фабрику (паттерн factory), которая возвращает его подклассы,
      специализирующиеся в различных схемах. Подклассы называются
      <classname>Zend_Uri_&lt;scheme&gt;</classname>, где <code>&lt;scheme&gt;</code> -
      схема в нижнем регистре, с прописной первой буквой. Исключением из этого
      правила является HTTPS, который обрабатывается подклассом
      <classname>Zend_Uri_Http</classname>.
    </para>
  </sect2>

  <sect2 id="zend.uri.creation">
    <title>Создание нового URI</title>

    <para>
      <classname>Zend_Uri</classname> будет строить с нуля новый URI, если
      <code>Zend_Uri::factory()</code> была передана только схема.
    </para>

    <example id="zend.uri.creation.example-1">
      <title>Создание нового URI с Zend_Uri::factory()</title>

      <programlisting language="php"><![CDATA[
// Для того, чтобы создать с нуля новый URI, передайте только схему.
$uri = Zend_Uri::factory('http');

// $uri является экземпляром Zend_Uri_Http
]]></programlisting>
    </example>

    <para>
      Для того, чтобы создать с нуля новый URI, передайте
      <code>Zend_Uri::factory()</code> только схему. <footnote><para>На момент
      написания этой документации Zend_Uri поддерживает только схемы HTTP и
      HTTPS.</para></footnote>. При передаче не поддерживаемой схемы
      генерируется исключение <classname>Zend_Uri_Exception</classname>.
    </para>

    <para>
      Если переданные схема или URI поддерживаются, то
      <code>Zend_Uri::factory()</code> вернет свой подкласс, который
      специализируется на данной схеме.
    </para>
  </sect2>

  <sect2 id="zend.uri.manipulation">
    <title>Работа с существующим URI</title>

    <para>
      Для того, чтобы работать с существующим URI, передайте его весь целиком
      <code>Zend_Uri::factory()</code>.
    </para>

    <example id="zend.uri.manipulation.example-1">
      <title>Работа с существующим URI через Zend_Uri::factory()</title>

    <programlisting language="php"><![CDATA[
// Чтобы работать с существующим URI, передайте его как параметр
$uri = Zend_Uri::factory('http://www.zend.com');

// $uri является экземпляром Zend_Uri_Http
]]></programlisting>
    </example>

    <para>
      URI будет распарсен и проверен на валидность. Если он оказался невалидным,
      то сразу же будет сгенерировано исключение
      <classname>Zend_Uri_Exception</classname>. Иначе <code>Zend_Uri::factory()</code>
      вернет свой подкласс, который специализируется на данной схеме.
    </para>
  </sect2>

  <sect2 id="zend.uri.validation">
    <title>Проверка URI</title>

    <para>
      Функция <code>Zend_Uri::check()</code> может использоваться в том случае,
      когда нужна только проверка существующего URI.
    </para>

    <example id="zend.uri.validation.example-1">
      <title>Проверка URI с помощью Zend_Uri::check()</title>

    <programlisting language="php"><![CDATA[
// Проверка, является ли данный URI синтаксически корректным
$valid = Zend_Uri::check('http://uri.in.question');

// $valid равен TRUE при валидном URI, иначе FALSE
]]></programlisting>
    </example>

    <para>
      <code>Zend_Uri::check()</code> возвращает булево значение, использование
      этой функции более удобно, чем вызов <code>Zend_Uri::factory()</code> и
      отлов исключения.
    </para>

    <sect3 id="zend.uri.validation.allowunwise">
        <title>Разрешение использования "неумных" символов в URI</title>

        <para>
            По умолчанию <classname>Zend_Uri</classname> не будет принимать
            следующие символы, которые в спецификации определены как "неумные"
            (unwise) и невалидные: <code>"{", "}", "|", "\", "^", "`"</code>.
            Тем не менее, многие реализации принимают эти символы как валидные.
        </para>

        <para>
            Можно заставить <classname>Zend_Uri</classname> принимать эти
            символы путем установки 'allow_unwise' в TRUE, используя метод
            <code>Zend_Uri::setConfig()</code>:
        </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');

// Тем не менее, вы можете разрешить "неумные" символы
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>
                <code>Zend_Uri::setConfig()</code> глобально устанавливает опции
                конфигурации. Рекомендуется сбрасывать опцию
                'allow_unwise' в 'false', как показано в примере выше,
                если только вы не хотите разрешить использование "неумных"
                символов на все время во всем приложении.
            </para>
        </note>
    </sect3>
  </sect2>

  <sect2 id="zend.uri.instance-methods">
    <title>Общие методы экземпляров</title>

    <para>
      Каждый экземпляр подкласса <classname>Zend_Uri</classname> (например,
      <classname>Zend_Uri_Http</classname>) имеет несколько методов,
      полезных для работы с любыми видами URI.
    </para>

    <sect3 id="zend.uri.instance-methods.getscheme">
      <title>Получение схемы URI</title>

      <para>
        Схема URI – часть URI, завершающаяся двоеточием. Например, схемой в
        <code>http://www.zend.com</code> является <code>http</code>.
      </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>
        Метод экземпляра <code>getScheme()</code> возвращает схему из URI.
      </para>

    </sect3>

    <sect3 id="zend.uri.instance-methods.geturi">
      <title>Получение всего URI</title>

      <example id="zend.uri.instance-methods.geturi.example-1">
        <title>Получение всего URI из объекта Zend_Uri_*</title>

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

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

      <para>
        Метод <code>getUri()</code> возвращает строковое представление всего
        URI.
      </para>
    </sect3>

    <sect3 id="zend.uri.instance-methods.valid">
      <title>Проверка URI на валидность</title>

      <para>
        <code>Zend_Uri::factory()</code> всегда производит синтаксическую
        проверку переданных ему URI и не будет создавать новый экземпляр
        подкласса <classname>Zend_Uri</classname>, если данный URI не прошел проверку.
        Тем не менее, после того, как был инстанцирован подкласс
        <classname>Zend_Uri</classname> для нового URI или на основе уже существующего,
        в результате манипуляций с ним этот URI может стать невалидным.
      </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>
        Метод <code>valid()</code> дает возможность проверить, является ли URI
        по-прежнему валидным.
      </para>
    </sect3>

  </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->