documentation/manual/ru/module_specs/Zend_Controller-Router-Route.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect3 id="zend.controller.router.routes.standard">
   4     <title>Zend_Controller_Router_Route</title>
   5
   6     <para>
   7         <classname>Zend_Controller_Router_Route</classname> - стандартный маршрут
   8         фреймворка. Он сочетает в себе легкость использования и гибкость
   9         определения маршрутов. Каждый маршрут состоит в основном из карты URL
  10         (статических и динамических частей (переменных)), и может быть
  11         инициализирован со значениями по умолчанию и требованиями к переменным.
  12     </para>
  13
  14     <para>
  15         Давайте представим себе некое приложение, в котором нужно разместить
  16         несколько информационных страниц об авторах. Мы хотим, чтобы адрес
  17         <code>http://domain.com/author/martel</code> вел
  18         на страницу с информацией об авторе с именем "martel". Маршрут для
  19         обеспечения такой функциональности может выглядеть следующим образом:
  20     </para>
  21
  22     <programlisting language="php"><![CDATA[
  23 $route = new Zend_Controller_Router_Route(
  24     'author/:username',
  25     array(
  26         'controller' => 'profile',
  27         'action'     => 'userinfo'
  28     )
  29 );
  30
  31 $router->addRoute('user', $route);
  32 ]]></programlisting>
  33
  34     <para>
  35         Первый параметр конструктора <classname>Zend_Controller_Router_Route</classname> -
  36         определение маршрута, которое будет сопоставляться с URL. Определения
  37         маршрутов содержат статические и динамические части, разделенные
  38         символом косой черты ('/'). Статические части являются обычным текстом:
  39         <code>author</code>. Динамические части, называемые переменными,
  40         помечаются знаком двоеточия в начале имени переменной:
  41         <code>:username</code>.
  42     </para>
  43
  44     <note>
  45         <title>Использование символов</title>
  46         <para>
  47             Текущая реализация позволяет использовать любые (за исключением
  48             косой черты) символы в идентификаторе переменной,
  49             но сильно рекомендуется использовать в них только символы,
  50             допустимые для переменных в php. Есть вероятность, что в
  51             будущем реализация изменится, и это может вызвать скрытые ошибки в
  52             вашем коде.
  53         </para>
  54     </note>
  55
  56     <para>
  57         Этот маршрут должен сработать, когда вы вводите
  58         <code>http://domain.com/author/martel</code> в своем броузере, в этом
  59         случае все его переменные будут добавлены в объект
  60         <classname>Zend_Controller_Request</classname> и будут доступны в вашем
  61         контроллере <code>ProfileController</code>.
  62         Переменные, возвращаемые в этом примере, могут быть представленые в виде
  63         следующего массива пар ключ/значение:
  64     </para>
  65
  66     <programlisting language="php"><![CDATA[
  67 $values = array(
  68     'username'   => 'martel',
  69     'controller' => 'profile',
  70     'action'     => 'userinfo'
  71 );
  72 ]]></programlisting>
  73
  74     <para>
  75         Затем <classname>Zend_Controller_Dispatcher_Standard</classname> должен вызвать
  76         метод <code>userinfoAction()</code> вашего класса
  77         <code>ProfileController</code> (используется модуль по умолчанию),
  78         основываясь на этих значениях. Вы сможете получать эти переменные через
  79         методы <code>Zend_Controller_Action::_getParam()</code> или
  80         <code>Zend_Controller_Request::getParam()</code>.
  81     </para>
  82
  83     <programlisting language="php"><![CDATA[
  84 public function userinfoAction()
  85 {
  86     $request = $this->getRequest();
  87     $username = $request->getParam('username');
  88
  89     $username = $this->_getParam('username');
  90 }
  91 ]]></programlisting>
  92
  93     <para>
  94         Определение маршрута может содержать в себе еще один специальный символ
  95         (метасимвол), представленный символом '*'. Он используется для сбора
  96         параметров, как в маршруте Module, используемом по умолчанию
  97         (пары переменная => значение, определенные в URI). Следующий маршрут
  98         приближенно воспроизводит поведение маршрута Module:
  99     </para>
 100
 101     <programlisting language="php"><![CDATA[
 102 $route = new Zend_Controller_Router_Route(
 103     ':module/:controller/:action/*',
 104     array('module' => 'default')
 105 );
 106 $router->addRoute('default', $route);
 107 ]]></programlisting>
 108
 109     <sect4 id="zend.controller.router.routes.standard.variable-defaults">
 110         <title>Значения переменных по умолчанию</title>
 111
 112         <para>
 113             Любая переменная в маршруте может иметь значение по умолчанию, для
 114             этого используется второй параметр конструктора
 115             <classname>Zend_Controller_Router_Route</classname>. Этот параметр является
 116             массивом с ключами, представляющими имена переменных, и со
 117             значениями в качестве значений переменных по умолчанию:
 118         </para>
 119
 120         <programlisting language="php"><![CDATA[
 121 $route = new Zend_Controller_Router_Route(
 122     'archive/:year',
 123     array('year' => 2006)
 124 );
 125 $router->addRoute('archive', $route);
 126 ]]></programlisting>
 127
 128         <para>
 129             Маршрут выше будет соответствовать URL-ам
 130             <code>http://domain.com/archive/2005</code> и
 131             <code>http://example.com/archive</code>. В последнем случае
 132             переменная year будет иметь начальное значение по умолчанию 2006.
 133         </para>
 134
 135         <para>
 136             В этом примере переменная <code>year</code> будет добавлена в объект запроса.
 137             Поскольку не была предоставлена информация для маршрутизации (не
 138             определены параметры <code>controller</code> и <code>action</code>), то управление будет
 139             передано контроллеру и методу действия, используемым по умолчанию
 140             (оба определены в <classname>Zend_Controller_Dispatcher_Abstract</classname>).
 141             Для того, чтобы сделать этот пример более полезным, нужно
 142             передать действительные контроллер и действие в качестве значений по
 143             умолчанию:
 144         </para>
 145
 146         <programlisting language="php"><![CDATA[
 147 $route = new Zend_Controller_Router_Route(
 148     'archive/:year',
 149     array(
 150         'year'       => 2006,
 151         'controller' => 'archive',
 152         'action'     => 'show'
 153     )
 154 );
 155 $router->addRoute('archive', $route);
 156 ]]></programlisting>
 157
 158         <para>
 159             В результате будет вызван метод <code>showAction()</code> класса
 160             <code>ArchiveController</code>.
 161         </para>
 162
 163     </sect4>
 164
 165     <sect4 id="zend.controller.router.routes.standard.variable-requirements">
 166         <title>Требования к переменным</title>
 167
 168         <para>
 169             Можно передать конструктору
 170             <classname>Zend_Controller_Router_Route</classname> третий параметр, в котором
 171             установлены требования к переменным. Они определяются как части
 172             регулярных выражений:
 173         </para>
 174
 175         <programlisting language="php"><![CDATA[
 176 $route = new Zend_Controller_Router_Route(
 177     'archive/:year',
 178     array(
 179         'year'       => 2006,
 180         'controller' => 'archive',
 181         'action'     => 'show'
 182     ),
 183     array('year' => '\d+')
 184 );
 185 $router->addRoute('archive', $route);
 186 ]]></programlisting>
 187
 188         <para>
 189             В случае маршрута, определенного таким образом, маршрутизатор будет
 190             считать URL соответствующим ему только если переменная year
 191             содержит числовые данные - например,
 192             <code>http://domain.com/archive/2345</code>. URL вида
 193             <code>http://example.com/archive/test</code> не будет
 194             соответствовать этому маршруту, вместо этого будет произведен
 195             переход к следующему маршруту в цепочке.
 196         </para>
 197     </sect4>
 198
 199     <sect4 id="zend.controller.router.routes.standard.translated-segments">
 200         <title>Переводимые сегменты</title>
 201
 202         <para>
 203             Стандартный маршрут поддерживает переводимые сегменты. Для того,
 204             чтобы использовать эту возможность, нужно как минимум указать,
 205             какой переводчик (экземпляр <classname>Zend_Translate</classname>)
 206             должен использоваться - одним из следующих способов:
 207         </para>
 208
 209         <itemizedlist>
 210             <listitem>
 211                 <para>
 212                     Поместить его в реестр с ключом <code>Zend_Translate</code>.
 213                 </para>
 214             </listitem>
 215             <listitem>
 216                 <para>
 217                     Установить через статический метод
 218                     <classname>Zend_Controller_Router_Route::setDefaultTranslator()</classname>.
 219                 </para>
 220             </listitem>
 221             <listitem>
 222                 <para>
 223                     Передать его конструктору в качестве четвертого параметра.
 224                 </para>
 225             </listitem>
 226         </itemizedlist>
 227
 228         <para>
 229             По умолчанию используется локаль, указанная в экземпляре
 230             <classname>Zend_Translate</classname>. Для того, чтобы
 231             переопределить ее, вы можете установить ее значение (экземпляр
 232             <classname>Zend_Locale</classname> или строка с локалью)
 233             одним из следующих способов:
 234         </para>
 235
 236         <itemizedlist>
 237             <listitem>
 238                 <para>
 239                     Поместить ее в реестр с ключом
 240                     <classname>Zend_Locale</classname>.
 241                 </para>
 242             </listitem>
 243             <listitem>
 244                 <para>
 245                     Установить через статический метод
 246                     <classname>Zend_Controller_Router_Route::setDefaultLocale()</classname>.
 247                 </para>
 248             </listitem>
 249             <listitem>
 250                 <para>
 251                     Передать ее конструктору в качестве пятого параметра.
 252                 </para>
 253             </listitem>
 254             <listitem>
 255                 <para>
 256                     Передать ее как параметр <code>@locale</code> методу
 257                     <code>assemble()</code>.
 258                 </para>
 259             </listitem>
 260         </itemizedlist>
 261
 262         <para>
 263             Переводимые сегменты делятся на два типа. У статических
 264             сегментов в начале ставится один символ <code>@</code>,
 265             они будут переведены в соответствии текущей локалью при сборке URL
 266             и преобразованы обратно в идентификатор сообщения при сопоставлении
 267             URL с маршрутом.
 268             У динамических сегментов в начале ставится <code>:@</code>.
 269             При сборке URL данный параметр будет переведен и результат перевода
 270             будет добавлен на его место.
 271             При сопоставлении переведенный параметр из URL будет преобразован
 272             обратно в идентификатор сообщения.
 273         </para>
 274
 275         <note>
 276             <title>Идентификаторы сообщений и отдельный языковый файл</title>
 277             <para>
 278                 Может случайно получиться так, что идентификатор сообщения,
 279                 который вы собираетесь использовать в одном из своих
 280                 маршрутов, уже используется в ваших скриптах вида или где-то
 281                 еще.
 282                 Для того, чтобы иметь полный контроль над вашими
 283                 URL-ами, следует использовать отдельный языковый файл для
 284                 сообщений, используемых в маршруте.
 285             </para>
 286         </note>
 287
 288         <para>
 289             Следующий пример демонстрирует наиболее простой способ подготовки
 290             стандартного маршрута с использованием переводимых сегментов:
 291         </para>
 292
 293         <programlisting language="php"><![CDATA[
 294 // Подготовка переводчика
 295 $translator = new Zend_Translate('array', array(), 'en');
 296 $translator->addTranslation(array('archive' => 'archiv',
 297                                   'year'    => 'jahr',
 298                                   'month'   => 'monat',
 299                                   'index'   => 'uebersicht'),
 300                             'de');
 301
 302 // Установка текущей локали для переводчика
 303 $translator->setLocale('en');
 304
 305 // Установка его в качестве используемого по умолчанию для маршрутов
 306 Zend_Controller_Router_Route::setDefaultTranslator($translator);
 307 ]]></programlisting>
 308
 309         <para>
 310             Этот пример демонстрирует использование статических сегментов:
 311         </para>
 312
 313         <programlisting language="php"><![CDATA[
 314 // Создание маршрута
 315 $route = new Zend_Controller_Router_Route(
 316     '@archive',
 317     array(
 318         'controller' => 'archive',
 319         'action'     => 'index'
 320     )
 321 );
 322 $router->addRoute('archive', $route);
 323
 324 // Сборка URL в локали, используемой по умолчанию: archive
 325 $route->assemble(array());
 326
 327 // Сборка URL в немецкой локали: archiv
 328 $route->assemble(array());
 329 ]]></programlisting>
 330
 331         <para>
 332             Вы можете использовать динамические сегменты для создания
 333             переведенных версий как в случае использования маршрутов основанных
 334             на модулях:
 335         </para>
 336
 337         <programlisting language="php"><![CDATA[
 338 // Создание маршрута
 339 $route = new Zend_Controller_Router_Route(
 340     ':@controller/:@action/*',
 341     array(
 342         'controller' => 'index',
 343         'action'     => 'index'
 344     )
 345 );
 346 $router->addRoute('archive', $route);
 347
 348 // Сборка URL в локали, используемой по умолчанию: archive/index/foo/bar
 349 $route->assemble(array('controller' => 'archive', 'foo' => 'bar'));
 350
 351 // Сборка URL в немецкой локали: archiv/uebersicht/foo/bar
 352 $route->assemble(array('controller' => 'archive', 'foo' => 'bar'));
 353 ]]></programlisting>
 354
 355         <para>
 356             Вы можете также комбинировать статические и динамические сегменты:
 357         </para>
 358
 359         <programlisting language="php"><![CDATA[
 360 // Создание маршрута
 361 $route = new Zend_Controller_Router_Route(
 362     '@archive/:@mode/:value',
 363     array(
 364         'mode'       => 'year'
 365         'value'      => 2005,
 366         'controller' => 'archive',
 367         'action'     => 'show'
 368     ),
 369     array('mode'  => '(month|year)'
 370           'value' => '\d+')
 371 );
 372 $router->addRoute('archive', $route);
 373
 374 // Сборка URL в локали, используемой по умолчанию: archive/month/5
 375 $route->assemble(array('mode' => 'month', 'value' => '5'));
 376
 377 // Сборка URL в немецкой локали: archiv/monat/5
 378 $route->assemble(array('mode' => 'month', 'value' => '5', '@locale' => 'de'));
 379 ]]></programlisting>
 380     </sect4>
 381 </sect3>
 382 <!--
 383 vim:se ts=4 sw=4 et:
 384 -->