Ko3: роутинг

Исполняю просьбу одного из комментаторов предыдущей статьи об изменениях в ORM и предлагаю ознакомиться с возможностями класса Route, используемого для работы с роутингом.

Структура маршрута

Маршрут (route) представляет собой именованный набор правил, содержащий инструкции по выбору имени контроллера и метода для дальнейшего их создания и выполнения. Чтобы не тратить лишних слов, давайте сразу рассмотрим классический пример из дефолтного файла bootstrap.php:

Route::set('default', '(<controller>(/<action>(/<id>)))')
	->defaults(array(
		'controller' => 'welcome',
		'action'     => 'index',
	));

Класс Route является по сути контейнером маршрутов, выполняющим также функции анализа имеющихся маршрутов на соответствие полученным от URI значениям. Статический метод Route::set() создает новый маршрут и добавляет его в перечень существующих. В качестве первого параметра он принимает имя маршрута, т.е. при последовательном добавлении двух маршрутов с одним именем первый будет замещен вторым. В примере имя маршрута — ‘default‘.

Второй параметр самый главный — это шаблон, описывающий структуру URI, который должен быть обработан данным маршрутом. В нем-то и определяется контроллер, метод и дополнительные параметры. В указанном выше примере предусмотрена типичная для Kohana структура ЧПУ — контроллер/метод/id (имя параметра указывается в угловых скобках, например ). Причем будет работать как URI вида ‘/welcome/index‘, так и просто ‘/welcome‘, т.е. параметры маршрута (даже имя контроллера) не являются обязательными. Дело в том, что опциональные параметры «обертываются» круглыми скобками. Таким образом, рассматриваем строку (<controller>(/<action>(/<id>))) и видим, что:

• Пустой URI также будет соответствовать данному правилу (т.к. в круглые скобки заключена вся строка шаблона).
• Если указан один параметр URI, то это будет имя контроллера (т.к. внутри главных скобок только этот ключ не заключен какие-либо другие скобки).
• Если и второй параметр, то он будет назначен имени метода (ключ action, он является главным в подстроке (/<action>(/<id>))).
• Ну и наименьший приоритет в данном разборе имеет ключ id, которому достанется только третий сегмент URI.

Необязательный участок URI, выделенный круглыми скобками, может состоять и из нескольких сегментов.

А если не будет ни одного параметра (обращение к корню сайта)? По идее URL не содержит информации об имени контроллера, как поступить системе? Для этого есть метод defaults(), который предоставляет значения по умолчанию для неуказанных сегментов. В данном случае будет обращение к методу index() контроллера Controller_Welcome.

Обратите внимание, что параметр id передан не будет! А вот если добавить с defaults() строчку 'id' => NULL, то он появится. Более того, в defaults() можно указать сколько угодно параметров, и они будут переданы в вызываемый метод даже если они не упомянуты в шаблоне маршрута.

Конечно, не все требуемые маршруты могут быть реализованы с помощью одного универсального. Давайте представим, что у нас есть контроллер Controller_Auth с методами login(), logout() и register(). Конечно же, можно использовать URL вида ‘/auth/login‘ для входа на сайт, но ведь хочется коротких адресов для подобных стандартных действий (список которых ограничен и мы его знаем), поэтому давайте реализуем это через маршруты (другой вариант — использование средств веб-сервера, например mod_rewrite для Apache, но это уже тема не касающаяся Kohana напрямую):

Route::set('auth', '<action>')
	->defaults(array(
		'controller' => 'auth',
		'action'     => 'login',
	));

Данный маршрут будет обработан в случае наличия только одного сегмента в URL, и в результате будет вызван метод контроллера Controller_Auth (он отсутствует в строке шаблона, но зато указан в качестве параметра по умолчанию). Однако есть и недостатки — ведь в случае URL ‘/welcome‘ будет произведена попытка вызова несуществующего метода welcome() контроллера Controller_Auth. Это неправильно, поэтому имеется возможность дополнительно фильтровать поступающие сегменты с помощью регулярных выражений. Дело в том, что Route::set() имеет третий, необязательный параметр, который является массивом регулярных выражений для сегментов. Вот как мы будем ограничивать методы контроллера Controller_Auth для нашего нового маршрута:

Route::set('auth', '<action>', array('action' => '(login|logout|register)'))
	->defaults(array(
		'controller' => 'auth',
		'action'     => 'login',
	));

Теперь маршрут отработает только если единственный сегмент адреса соответствует одному из значений (login, logout или register). Если же надо ограничить перечень символов данного сегмента, можно использовать что-то вроде ‘[a-z0-9]‘ (тут разрешены латинские символы и цифры). Возможностей много, по сути это весь мощный арсенал регулярных выражений.

Стоп, скажете Вы. А что же будет, если при дефолтном маршруте ввести адрес с четырьмя параметрами, например /welcome/index/param1/param2? Мы получим ошибку Kohana_Request_Exception [ 0 ]: Unable to find a route to match the URI. Это означает, что не нашлось ни одного маршрута, удовлетворяющего данному адресу. Так что даже дефолтный маршрут не всемогущ, он может манипулировать максимум тремя сегментами. Впрочем, можно использовать все те же регулярные выражения, что весь хвост собрать в одном сегменте:

Route::set('default', '(<controller>(/<action>(/<id>)))', array('id' => '.+'))
	->defaults(array(
		'controller'	=> 'forum_category',
		'action'	=> 'index',
	));

Теперь параметр id будет содержать все, что указано после второго сегмента. Для этого мы использовали маску ‘.+‘, что означает ‘один или более любых символов’.

Мало? Вот вам еще одна возможность. Существует дополнительный параметр, отсутствующий в списке сегментов URI, но играющий роль при вызове метода контроллера — это параметр directory. Часто контроллеры находятся не непосредственно в директории classes/controller, а вложены еще в какие-то папки. Конечно, можно использовать преобразование знака подчеркивания в слэш, и вызывать URI вида ‘admin_users/manage‘, который будет использовать контроллер Controller_Admin_Users, но ведь это некрасиво. Давайте сделаем так, что все URI, начинающиеся с ‘admin/‘, будут вызвать контроллеры из папки admin:

Route::set('admin', 'admin/(<controller>(/<action>(/<id>)))')
	->defaults(array(
		'controller'	=> 'welcome',
		'action'	=> 'index',
		'directory'   => 'admin',
	));

Управление маршрутами

Объявлять маршруты мы научились, но это не все. Имеет значение не только содержимое маршрута, но и его номер в списке маршрутов объекта Route. Т.е. порядок добавления маршрутов важен. Поэтому если Вы добавляете в bootstrap.php свои маршруты, располагайте их ДО дефолтного маршрута. И вообще, тут действует правило — «общие (абстрактные) маршруты должы объявляться позже точных». Поэтому маршруты, нацеленные на отслеживание строго ограниченного числа адресов (к примеру, созданный нами маршрут ‘auth‘), должны быть объявлены первыми.

Метод Route::set(), хоть и является статическим, возвращает вполне конкретный объект Route (который уже добавлен в список маршрутов). Далее можно к нему применить метод defaults(), который мы разбирали. Однако работа с ним на этом не заканчивается, есть два полезных метода:

• matches($uri). Данный метод проверяет указанный URI на соответствие правилам маршрута. В частности, именно с помощью данного метода система выбирает из перечня маршрутов подходящий. Если маршрут не подходит, то метод возвращает FALSE, а иначе — массив пар параметр => значение.
• uri(array $params = NULL). Метод являет собой полную противоположность методу matches(), он осуществляет обратную маршрутизацию (т.е. формирует URI из описания маршрута и массива известных параметров). Например, $this->request->route->uri($this->request->route->matches($this->request->uri)) должен вернуть то же значение, что и просто $this->request->uri.

Помимо обычных методов, можно использовать статические (один из них, Route::set() мы же видели). Вот они:

• Route::get($name) возвращает маршрут с указанным именем. Если маршрут не найден, генерируется Kohana_Exception.
• Route::all() возвращает все маршруты в виде массива объектов класса Route (в качестве ключей имена маршрутов).
• Route::cache($save = FALSE) выполняет как кэширование маршрутов, так и извлечение их из кэша — в зависимости от параметра $save (по умолчанию загружает). Если загрузка прошла успешна, то сами маршруты сохраняются в объекте Route, как результат возвращается TRUE, в противном случае приходит FALSE. Так что можно вместо обычного добавления маршрутов действовать так:
  

  if ( ! Route::cache()) { // маршруты не были загружены из кэша // добавляем маршруты вручную Route::set(...) // сохраняем маршруты в кэш Route::cache(TRUE); }

Из свойств объекта Route доступна только статическая переменная Route::$default_action, которая определяет выполняемый метод по умолчанию (изначально это конечно ‘index‘). Таким образом, сегмент ‘action‘ может вообще отсутствовать в правилах маршрута, в таком случае будет использован дефолтный. А вот с контроллером такое не пройдет.

Работа с маршрутами через Request

Объект Request является одним из центральных в Ko3. Именно в нем производится поиск нужного маршрута, создание экземпляра контроллера и выполнение его метода. Результаты поиска сохраняются в свойствах $controller, $action и $directory, а сам выбранный маршрут — в свойстве $route. Получить параметры маршрута можно через метод param($key = NULL, $default = NULL), причем если имя параметра не указано, будут возвращены все параметры.

Также доступен и обратный роутинг, через все тот же метод uri(array $params = NULL). В качестве маршрута для формирования URI будет использован маршрут, хранящийся в свойстве $route объекта Request.

Дополнительная информация

Имена контроллера и метода могут отсутствовать в шаблоне маршрута, но в таком случае должны быть приведены в методе Route::defaults(). Иначе как система определит, как контроллер вызвать? Кстати, для имени метода еще есть лазейка. Дело в том, что после нахождения нужного маршрута Kohana выполняет следующие операции:

• Попытка создания экземпляра контроллера. Если он абстрактный, генерируется Kohana_Exception.
• Выполняется метод before() контроллера.
• Определяется имя метода. Если оно до сих пор не определено (свойство $action объекта Request), то используется приведенное в $default_action значение.
• Выполняется метод.
• Выполняется метод after().

Как мы видим, имя контроллера может быть определено только на основании анализа маршрутов, а вот для изменения имени метода есть «последний шанс» — можно использовать метод before(), и в нем изменить свойство $this->request->action (в принципе, это возможно и в конструкторе контроллера).

Маршруты могут быть добавлены не только через bootstrap.php. Например, любой подключаемый модуль может содержать файл init.php, который будет подключен во время добавления этого модуля методом kohana::modules(). Напомню, что обычно это происходит ДО добавления дефолтного маршрута (см. содержимое файла bootstrap.php).

Необязательные сегменты маршрута разбираются слева направо, с учетом уровня вложенности. Например, при маршруте '(<controller>(/<action>(/<param1>(/<param2>))(/<param3>)))' вызов URI вида ‘test/test/1/2‘ передаст в метод test() параметры $param1 и $param2, хотя вроде бы $param3 на уровень выше, чем $param2. Другой пример — ‘(<controller>(/<action>(/<param1>(/<param2>))/<param3>))‘. Здесь $param3 вообще находится по уровню важности рядом с названием метода, однако в случае передачи ‘test/test/1/2‘ его значение будет не 1, а 2. Почему я об этом говорю? Дело в том, что данные параметры передаются в метод контроллера именно слева на право. Т.е., если метод объявлен как test($param1 = NULL, $param2 = NULL, $param3 = NULL) и происходит вызов URI вида ‘test/test/1/2‘, то будут переданы первый и третий аргумент, что не совсем очевидно. Вообще, при работе с плавающим числом доп. аргументов в маршруте лучше вообще не объявлять аргументы методов, а работать напрямую с $this->request->param().

По умолчанию сегмент не может содержать слэш, точку, запятую, точку с запятой или вопросительный знак. Чтобы решить эту проблему (например, для передачи в URI имени файла) необходимо добавить в маршруте маску для этого сегмента, например ‘.+‘, как мы раньше это сделали для параметра id, чтобы включить поддержку более трех сегментов в URI.

Ну, и напоследок, пример маршрута для блога в виде blog/YYYY/MM/DD/some-blog-article. Надеюсь, объяснения не понадобятся.

Route::set('blog', '(blog(/<year>(/<month>(/<day>(/<slug>)))))',
		array(
			'year' 	=> '[0-9]{4}',
			'month'	=> '[0-9]{1,2}',
			'day'	=> '[0-9]{1,2}',
		))
	->defaults(array(
		'controller'	=> 'blog',
		'action'	=> 'show',
		)
	);

UPDATE. Zabex в комментариях подсказал, как сделать более точную регулярку для данного маршрута, так что встречаем новый вариант:

Route::set('blog', '(blog(/<year>(/<month>(/<day>(/<slug>)))))',
		array(
			'year' 	=> '[0-9]{4}',
			'month'	=> '(?:0[1-9]|1[0-2])',
			'day'	=> '(?:[0][1-9]|[1-2][0-9]|3[0-1])',
		))
	->defaults(array(
		'controller'	=> 'blog',
		'action'	=> 'show',
		)
	);

Надеюсь, получилось расказать все доступно и ничего не забыть.