Все эти методы могут работать как с внутренними URI, так и с статичными URL (начинающимися с "http://", система маршрутизации их игнорирует) и с якорями (anchors). Тут важно понимать, что внутренние URI строятся с учетом некоторых динамических параметров. Следующий листинг демонстрирует это:

Пример 9-8 - URL, с которыми работают ссылочные методы-помошники

[php] 
// внутренний URI 
 
 => <a href="/routed/url/to/Finance_in_France">my article</a> 

// внутренний URI с динамическими параметрами
getTitle()) ?> 

// внутренний URI с якорем
 
 => <a href="/routed/url/to/Finance_in_France#foo">my article</a> 

// статичный абсолютный URL
 
 => <a href="http://www.example.com/foobar.html">my article</a> 

Опции в ссылочных методах-помошниках

Как показано в главе 7, методы-помошники позволяют использовать домолнительный аргумент опций, который может быть ассоциативным массивом, или строкой. Это так и для ссылочных помошников, как показано в листинге 9-9.

Пример 9-9 - Ссылочные помошники позволяют использовать опции

[php] 
// Дополнительные опции в виде ассоциативного массива
 'foobar', 
      'target' => '_blank' 
    )) ?> 

// Дополнительные опции в виде строки
 
 => <a href="/routed/url/to/Finance_in_France" class="foobar" target="_blank">my article</a> 

Вы так же можете использовать специфичные для symfony опции: "confirm" и "popup". Первая использует JS-диалоговое окно в момент клика по ссылке для подтверждения перехода (применимо для кнопок удаления в CMS, к примеру), а вторая - открывает документ, на который ведет ссылка в новом окне, как показано в листинге 9-10.

Пример 9-10 - 'confirm' и 'popup' опции

[php] 
 
 => <a onclick="return confirm('Are you sure?');" 
       href="/routed/url/to/delete/123.html">add to cart</a> 

 
 => <a onclick="window.open(this.href);return false;" 
       href="/fo_dev.php/shoppingCart/add/id/100.html">add to cart</a> 

 array('Window title', 'width=310,height=400,left=320,top=0') 
    )) ?> 
 => <a onclick="window.open(this.href,'Window title','width=310,height=400,left=320,top=0');return false;" 
       href="/fo_dev.php/shoppingCart/add/id/100.html">add to cart</a> 

Все эти опции можно использовать совместно.

Неверное использование GET и POST

Достаточно часто разработчик создает GET запрос в то время, как на самом деле подразумевается POST. Взгляните на этот пример:

http://www.example.com/index.php/shopping_cart/add/id/100 

Этот запрос изменит данные, хранящиеся в приложении, добавив товар в корзину, которая хранится в сессии или базе данных. Такой URL может быть внесен в закладки, может быть закэширован, или проиндексирован поисковыми машинами. Только представьте все последствия такого для ваший базы данных! На самом деле этот запрос должен передаваться как POST. Хотя бы потому, что поисковые боты не делают POST запросов и не индексируют их.

Symfony предоставляет нам возможность изменить поведение "link_to()" и "button_to()" так, чтобы они использовали POST. Для этого необходимо добавить опцию 'post=true', как показано в листинге 9-11.

Пример 9-11 - Делаем POST из простой ссылки

[php] 
 
 => <a onclick="f = document.createElement('form'); document.body.appendChild(f); 
                f.method = 'POST'; f.action = this.href; f.submit();return false;" 
       href="/shoppingCart/add/id/100.html">go to shopping cart</a> 

Когда происходит клик по ссылке, динамически создается форма с "action=post" и совершается переход по ней, а переход по исходной ссылке отменяется. Как видите, у этого тага есть аттрибут "href", и, если у пользователя отключен Javascript, или если по ссылке пройдет поисковый бот, он выполнит запрос GET по умолчанию. Чтобы избежать описанной выше ситуации вам необходимо ограничить ваш action таким образом, чтобы он отвечал только на POST запросы:

[php] 
$this->forward404If($request->getMethod() != sfRequest::POST); 

У этого подхода есть одно ограничение - нельзя использовать ссылки с "post=true" внутри форм, так как такая ссылка при клике создает собственную форму, что приведет к некорректной работе исходной формы.

Использовать ссылки с POST тогда, когда они действительно выполнают post считается хорошим тоном.

Принудительное представление параметров запроса как GET переменных

В системе маршрутизации переменные, используемые в качестве аргументов для "link_to()" преобразовываются в шаблоны. Если сформированный внутренний URI не подпадает ни под одно правило, используется маршрут по умолчанию "module/action?key=value" => "module/action/key/value", как показано в листинге 9-12.

Пример 9-12 - Правило маршрутизации по умолчанию

[php] 
 
=> <a href="/article/read/title/Finance_in_France">my article</a> 

Если вам нужно использовать синтакс GET и сохранить формат ?key=value для ваших параметров - вам необходимо использовать эти параметры вне передаваемого URL, в опции "query_string". Эту опцию поддерживают все ссылочные помощники.

Пример 9-13 - Используем GET параметры в query_string

[php] 
 'title=Finance_in_France' 
    )) ?> 
=> <a href="/article/read?title=Finance_in_France">my article</a> 

Переменные, переданные в качестве GET параметров могут быть использованы в скриптах на стороне клиента и в переменных $_GET и $_REQUEST на стороне сервера.

SIDEBAR Методы помошники для статических ресурсов

В седьмой главе вы познакомились с методами "image_tag()", "stylesheet_tag()", и "javascript_include_tag()", которые позволяют покдлючать к документу изображение, файл стиля или javasctipt файл. Пути в таких хэлперах не обрабатываются системой маршрутизации, так как они указывают на ресурсы, расположенные в публично доступной директории.

Нет необходимости указывать расширение файла, Symfony автоматически использует ".png", ".js", ".css" для подключения изображения, js-файла или стиля. Более того, по умолчанию Symfony будет искать указанные файлы в директориях "web/images", "web/css", "web js". Однако, если вы хотите использовать нестандартное расширение файла, или файл из какой-то нестандартной директории, вы можете указать путь к файлу. И не беспокойтесь о атрибуте "alt" выших изображений, symfony определит его автоматически.

[php] 
 
 
 
 => <img href="/images/test.png" alt="Test" /> 
    <img href="/images/test.gif" alt="Test" /> 
    <img href="/my_images/test.gif" alt="Test" /> 

Чтобы изменить размер изображения, используйте атрибут "size", он принимает ширину и высоту, разделенную символом x.

[php] 
 
 => <img href="/images/test.png" alt="Test" width="100" height="20"/> 

Если вы хотите использовать стиль или js файл в секции документа - используйте методы "use_stylesheet()" и "use_javascript" в шаблонах, вместо "*_tag()" в обрамлениях. Их использование приведет к вставке ссылки на необходимые файлы до тега "".

Использование абсолютных путей

По умолчанию генерируемые ссылки используют относительные пути. Если по той или иной причине вам надо работать с абслютными, используйте опцию "absolete=true". Такой подход бывает полезен при работе с Email, API или RSS лентами.

Пример 9-14 - Использование абсолютных путей

[php] 
 
 => '/routed/url/to/Finance_in_France' 
 
 => 'http://www.example.com/routed/url/to/Finance_in_France' 

 
 => <a href="/routed/url/to/Finance_in_France">finance</a> 
 
 => <a href=" http://www.example.com/routed/url/to/Finance_in_France">finance</a> 

// The same goes for the asset helpers 
 
 

SIDEBAR Метод-помошник Mail. В наши дни по вебу гуляет туча ботов, собирающих опубликованные email адреса, и, опубликовав где-либо свой адрес, вы рискуете стать жертвой спамеров уже через несколько дней. Вот почему в symfony разработан специальный помошник "mail_to()". Этот хелпер принимает в параметры два аргумента - настоящий email адрес и строку, которую надо вывести, так же можно использовать опцию "encode=true", которая превратит адрес во что-то нечитаемое. Ссылку поймет браузер, но не поймет спамерский бот:

[php] 
 
 => <a href="mailto:myaddress@mydomain.com'>contact</a> 
<?php echo mail_to('myaddress@mydomain.com', 'contact', 'encode=true') ?> 
 => <a href="ma... om">ct... ess</a> 

Эта технология позволяет заменять символы алфавита числовыми последовательностями, и, на данный момент, большинство ботов не понимают такого шифра, но, к сожалению, спамерз технолоджис развиваются слишком быстро...

Настройка маршрутизации

Система маршрутизации выполняет следующие процедуры:

• Интерпретирует входящие абсолютные URL, определяя внутренний URI, модуль, действие (action) и параметры запроса.
• Форматирует внутренние URI, указанные в методах-помошниках во внешние URL.

Преобразования выполняются по правилам, указанным в конфигурационном файле "routing.yml", который вы найдете в директории "config" приложения. В листинге 9-15 показан дефолтный файл конфигурации маршрутизации.

Пример 9-15 - Файл конфигурации маршрутизации по-умолчанию, он находится в myapp/config/routing.yml

# default rules 
homepage: 
  url:   / 
  param: { module: default, action: index } 

default_symfony: 
  url:   /symfony/:action/* 
  param: { module: default } 

default_index: 
  url:   /:module 
  param: { action: index } 

default: 
  url:   /:module/:action/* 

Правила и шаблоны

Правила маршрутизации это бинарные отношения между внутренним URI и внешним URL. Они состоят из:

• Имя маршрута - уникальная метка, она может быть использована в методах-помошниках.
• Ключ "url" - шаблон внешнего URL, по которому сверяется URL.
• Массив параметров запроса (ключ param)

Шаблон может включать в себя групповые символы ( "*" к примеру) и проименованные групповые символы, которые начинаются с двоеточия. Совпадающие проименованные групповые символы преобразуются в параметры запроса. В качестве примера, в маршруте по умолчанию (:module/:action) при запросе "/foo/bar" параметр "action" примет значение "bar", а "module" => "foo", а в маршруте "default_symfony" в качестве модуля будет использоваться "symfony".

Система шаблонов сверяет URL запроса со всеми правилами сверху вниз и останавливается при первом совпадении, по этому ваши более конкретизированные правила надо указывать выше более общих.

Пример 9-16 - Правила проверяются сверху вниз.

my_rule: 
  url:   /foo/:bar 
  param: { module: mymodule, action: myaction } 

# default rules 
default: 
  url:   /:module/:action/* 

NOTE Когда вы создаете новое действие (action), вам не обязательно менять что-либо в системе маршрутизации, если правило по умолчанию вас устраивает. Если же вам необходимо изменить внешний URL действия - необходимо будет создать маршрут к нему в routing.yml.

Пример 9-17 показывает, как сменить внешний формат URL для действия "article/read"

Пример 9-17 - Меняем формат внешнего URL для "article/read"

[php] 
<?php echo url_for('my article', 'article/read?id=123) ?> 
 => /article/read/id/123       // Default formatting 

// To change it to /article/123, add a new rule at the beginning 
// of your routing.yml 
article_by_id: 
  url:   /article/:id 
  param: { module: article, action: read } 

В этом примере есть одна проблема: маршрут "article_by_id" перекрывает все маршруты, которые используют модуль "article". Фактически, при запросе "article/delete" symfony будет использовать действие "read" и id = delete. Чтобы обойти такое поведение, надо использовать шаблонное ограничение для правила, указывающее, что ":id" должно быть числом.

Шаблонные ограничения

В случае, если URL подпадает под несколько правил, вам придется переназначить правила путем добавления ограничений или требований к шаблону. Требование - это набор регулярных выражений, с которыми должны совпадать групповые символы (wildcards) URL чтобы оно подпадало под данное правило.

К примеру, чтобы добавить ограничение к правилу "article_by_id", надо дописать следующую строчку:

Пример 9-18 - Добавляем требование к правилу.

article_by_id: 
  url:   /article/:id 
  param: { module: article, action: read } 
  requirements: { id: \d+ } 

Теперь при запросе "article/delete" действие "read" вызвано не будет, так как не выполняется требование.

SIDEBAR Постоянные ссылки ака пермалинки

Хорошей практикой по улучшению безопасности вашего сайта в плане маршрутизации является использование уникальных строк вместо первичных ключей в URL. К прмеру, вы можете использовать метод для чтения статей по названию статьи, а не по ее идентификатору:

http://www.example.com/article/Finance_in_France 

Вы можете использовать и оба подхода вместе следующим образом:

article_by_id: 
  url:          /article/:id 
  param:        { module: article, action: read } 
  requirements: { id: \d+ } 

article_by_slug: 
  url:          /article/:slug 
  param:        { module: article, action: permalink } 

Действие "permalink" будет возвращать статью по ее названию, а значит у вашей модели должен быть соответствущий метод.

[php] 
public function executePermalink() 
{ 
  $article = ArticlePeer::retrieveBySlug($this->getRequestParameter('slug'); 
  $this->forward404Unless($article);  // Display 404 if no article matches slug 
  $this->article = $article;          // Pass the object to the template 
} 

Так же вам надо будет заменить действие "read" на "permalink" в ваших ссылочных методах-помошниках.

[php] 
// Replace 
<?php echo link_to('my article', 'article/read?id='.$article->getId()) ?> 

// With 
<?php echo link_to('my article', 'article/permalink?slug='.$article->getSlug()) ?> 

Благодаря системе требований, url article/bla_bla_bla будет подпадать под правило article_by_slug, несмотря на то, что article_by_id написано выше него.

Для оптимизации быстродействия БД, при использовании метода получения статьи по названию вам не мешало бы проиндексировать вашу таблицу по полю title.

Установка значений по умолчанию

Вы можете указать переменным (wildcards) правила значения по умолчанию для того, чтобы правило сработало даже при отсутствии некоторых параметров, указывайте значения по умолчанию в массиве "params".

К примеру, правило "article_by_id" не сработает, если не указан "id", но это можно обойти, форсировав значение "id", как показано в листинге 9-19:

Пример 9-19 - Установка значения по умолчанию для wildcard.

article_by_id: 
  url:          /article/:id 
  param:        { module: article, action: read, 
id: 1 
 } 

Параметрам по умолчанию не обязательно присутствовать в шаблоне. Таким образом вы можете управлять параметрами запроса:

Пример 9-20 - Установка значения по умолчанию для параметра запроса:

article_by_id: 
  url:          /article/:id 
  param:        { module: article, action: read, id: 1, display: true } 

TIP Вы можете назначить один и тот же парамет для всех правил системы маршрутизации! Для этого надо назначить переменную конфигурации "sf_routing_defaults". К примеру, если вы хотите, чтобы все ваши маршруты имели параметр "theme" равный "default" по умолчанию, вы можете добавить строчку "sfConfig::set("sf_routing_defaults", array("theme" => "default"))" в ваш config.php.

Ускорение системы маршрутизации средствами использования имени маршрута

Методы-помошники для генерации ссылок поддерживают использование имени маршрута вместо пары модуль/действие, если перед ним стоит знак "@". Пример:

Пример 9-21 - Использование имени маршрута

[php] 
getId()) ?> 

// can also be written as 
getId()) ?> 

Вот все за и против этой технологии:

• Система маршрутизации мгновенно найдет нужный маршрут, а не будет его искать, что даст ощутимый прирост в производительности, если на странице находится большое количество ссылок.
• Использование имени маршрута помогает разграничить логику и представление. Если вам понадобится сменить имя действия, но оставить URL прежним - будет достаточно изменить действие в файле routing.yml. Все вызовы "link_to()" будут работать как прежде.
• Логика функции-помощника более очевидна при использовании имени маршрута.

Но у этого подхода есть и свои минусы. Один из них - ссылки становятся более завуалированными, вам постоянно приходится ссылаться на routing.yml.

Что лучше - решать вам. Во многом это зависит от конкретного проекта.

TIP При тестировании в вашем "dev" окружении, если вы хотите узнать, совпал ли с шаблоном данный запрос в браузере, откройте вкладку "logs and msgs" в тулбаре отладки и найдите строку "matched route XXX". Вы можете прочитать об отладке маршрутов подробнее в 16ой главе.

Добавляем расширение .html

Взгляните на следующие адреса:

http://myapp.example.com/article/Finance_in_France 
http://myapp.example.com/article/Finance_in_France.html 

Даже если за ними скрывается одна и та же страница, пользователи (и поисковые боты) будут воспринимать их по разному только из-за адреса. Второй требует хорошо организованной структуры старических веб-страниц, а это как раз то, что очень здорово индексируется поисковиками.

Чтобы приписать ".html" ко всем внешним URL, которые генерируют ваши методы, установите переменную "suffix" в файле "settings.yml" конфиги приложения так, как это показано в примере 9-22.

Пример 9-22 - Установка суффикса для всех адресов в myapp/config/settings.yml

prod: 
  .settings 
    suffix:         .html 

По умолчанию суффикс установлен в точку ("."), что означает, что система маршрутов не будет использовать суффиксы, если вы их не назначите дополнительно.

Иногда бывает необходимость назначить суффикс только для одного правила - тогда вы можете добавить его прямо в строчку "url" в описании правила в "routing.yml", глобальный суффикс в таком случае будет проигнорирован.

Пример 9-23 - Установка суффикса для одного адреса, in myapp/config/routing.yml

article_list: 
  url:          /latest_articles 
  param:        { module: article, action: list } 

article_list_feed: 
  url:          /latest_articles.rss 
  param:        { module: article, action: list, type: feed } 

Создаем правила без routing.yml

Как и большинство других конфигурационных файлов, routing.yml - не единственный метод создать правила системы маршрутов. Вы можете создавать правила в PHP - либо в config.php, либо в контроллере до вызова "dispatch()", так как он определяет, какой модуль и действие вызвать исходя из уже существующих маршрутов. Создание маршрутов в PHP позволяет вам создавать правила динамически с учетом конфигураций либо каких-то других факторов.

Обработкой маршрутов занимается объект класса sfRouting (модель factory). Он доступен в любом месте кода посредствам вызова sfContext::getInstance()->getRouting(). Его метод prependRoute() создает маршрут и "кладет" его поверх уже существующих в файле routing.yml. Он принимает четыре параметра, которые совпадают с параметрами, необходимыми для создания правила: название маршрута, его шаблон, массив значений по умолчанию и массив ограничений / требований. К примеру, определение маршрута из листинга 9-18 эквивалентно определению в 9-24.

** Новое в devel версии **

NOTE Класс маршрутизации можно сменить в файле конфигурации factories.yml (подробности в 17ой главе). В этой главе говорится о sfPatternRouting, это класс, используемый для маршрутизации по умолчанию.

Пример 9-24 - Создаем маршрут в PHP.

[php] 
sfContext::getInstance()->getRouting()->prependRoute( 
  'article_by_id',                                  // Route name 
  '/article/:id',                                   // Route pattern 
  array('module' => 'article', 'action' => 'read'), // Default values 
  array('id' => '\d+'),                             // Requirements 
); 

Класс sfRouting имеет еще несколько методов, полезных при работе с маршрутами вручную: clearRoutes(), hasRoutes() и так далее. Подробнее об этом можно прочитать в документации API(http://www.symfony-project.com/api/symfony.html).

TIP Когда вы полностью поймете то, о чем говорится в этой книге, мы рекомендуем вам почитать symfony API, или просмотреть исходные коды, что было бы даже лучше, так как не обо всем мы смогли написать в книге, многие вещи описаны в API.

Работа с маршрутами в действиях (actions)

Если вам необходимо работать с текущим маршрутом в действии, к примеру, для создания ссылки "назад к странице XXX", вы должны работать с объектом класса sfRouting. Используйте адрес, возвращаемый методом getCurrentInternalUri() в качестве аргумента для link_to(), как показано в листинге 9-25:

Пример 9-25 - Используем sfRouting для получения информации о текущем маршруте

[php] 
// If you require a URL like 
http://myapp.example.com/article/21 

$routing = sfContext::getInstance()->getRouting(); 

// Use the following in article/read action 
$uri = $routing->getCurrentInternalUri(); 
 => article/read?id=21 

$uri = $routing->getCurrentInternalUri(true); 
 => @article_by_id?id=21 

$rule = $routing->getCurrentRouteName(); 
 => article_by_id 

// If you just need the current module/action names, 
// remember that they are actual request parameters 
$module = $this->getRequestParameter('module'); 
$action = $this->getRequestParameter('action'); 

Если вам нужно получить внешний url из внутреннего так же, как это делает url_for() в шаблоне - используейте genUrl() - метод класса sfController:

Пример 9-26 - Используем sfController для трансформации url в действиях.

[php] 
$uri = 'article/read?id=21'; 

$url = $this->getController()->genUrl($uri); 
 => /article/21 

$url = $this->getController()->genUrl($uri, true); 
=> http://myapp.example.com/article/21 

Итог

Маршрутизация - двунаправленный механизм, который позволяет преобразовывать адреса таким образом, что они становятся более удобочитаемы. URL rewriting необходим для того, чтобы опускать имя контроллера ("index.php", к примеру) в ваших адресах. Если вы хотите, чтобы маршрутизация работала в обоих направлениях - вам необходимо использовать методы-помощники для вывода ссылок в ваших шаблонах. Файл routing.ymlконфигурирует правила маршрутизации и использует порядок появления правил и требования / ограничения к правилам для поиска совпадений. Файл settings.yml содержит дополнительные настройки, которые позволяют регулировать присутствие имени контроллера и суффикса во внешних адресах.

Перевод Алексея Гоголева и Ната (natts) Гаджибалаева.