Маршрутизация

Маршрутизатор позаботится обо всём, что связано с URL-адресами, так что вам больше не придется о них думать. Давайте покажем:

как настроить маршрутизатор так, чтобы URL-адреса были такими, какими вы хотите их видеть
как настроить SEO и перенаправления
как написать свой собственный маршрутизатор

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

Маршрутизатор в Nette особенный, потому что он двунаправленный, он может как декодировать URL HTTP-запросов, так и создавать ссылки. Поэтому он играет важную роль в Nette Application, поскольку он решает, какой ведущий и действие будут выполнять текущий запрос, а также используется для генерации URL в шаблоне и т.д.

Однако маршрутизатор не ограничивается этим применением, вы можете использовать его в приложениях, где ведущие вообще не используются, для REST API и т.д. Подробнее в разделе раздельное использование.

Коллекция маршрутов

Наиболее приятным способом определения URL-адресов в приложении является класс Nette\Application\Routers\RouteList. Определение состоит из списка так называемых маршрутов, то есть масок URL-адресов и связанных с ними презентеров и действий с помощью простого API. Нам не нужно называть маршруты.

$router = new Nette\Application\Routers\RouteList;
$router->addRoute('rss.xml', 'Feed:rss');
$router->addRoute('article/<id>', 'Article:view');
// ...

В примере говорится, что если мы откроем https://any-domain.com/rss.xml в браузере, то будет отображен презентер Feed с действием rss и т. д. Если подходящий маршрут не найден, приложение Nette отвечает исключением BadRequestException, которое отображается для пользователя как страница ошибки 404 Not Found.

Порядок маршрутов

Порядок, в котором перечислены маршруты, очень важен, потому что они оцениваются последовательно сверху вниз. Правило заключается в том, что мы объявляем маршруты от конкретных к общим:

// ОШИБКА: 'rss.xml' соответствует первому маршруту и неправильно воспринимает его как <slug>.
$router->addRoute('<slug>', 'Article:view');
$router->addRoute('rss.xml', 'Feed:rss');

// ПОДРОБНЕЕ
$router->addRoute('rss.xml', 'Feed:rss');
$router->addRoute('<slug>', 'Article:view');

Маршруты также оцениваются сверху вниз при генерации ссылок:

// ОШИБКА: генерирует ссылку на 'Feed:rss' как 'admin/feed/rss'
$router->addRoute('admin/<presenter>/<action>', 'Admin:default');
$router->addRoute('rss.xml', 'Feed:rss');

// ПОДРОБНЕЕ
$router->addRoute('rss.xml', 'Feed:rss');
$router->addRoute('admin/<presenter>/<action>', 'Admin:default');

Мы не будем скрывать от вас, что для правильного построения списка требуется определенный навык. Пока вы не научитесь, панель routing panel будет полезным инструментом.

Маска и параметры

Маска описывает относительный путь, основанный на корне сайта. Самая простая маска — это статический URL:

$router->addRoute('products', 'Products:default');

Часто маски содержат так называемые параметры. Они заключены в угловые скобки (например, <year>) и передаются в целевой презентер, например, в метод renderShow(int $year) или в постоянный параметр $year:

$router->addRoute('chronicle/<year>', 'History:show');

В примере говорится, что если мы откроем https://any-domain.com/chronicle/2020 в браузере, презентер History и действие show с параметром year: 2020 будет отображаться.

Мы можем указать значение по умолчанию для параметров непосредственно в маске, и таким образом она становится необязательной:

$router->addRoute('chronicle/<year=2020>', 'History:show');

Теперь маршрут будет принимать URL https://any-domain.com/chronicle/, который снова отобразит History:show с параметром year: 2020`.

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

$router->addRoute('<presenter>/<action>', 'Home:default');

Этот маршрут принимает, например, URL в форме /article/edit и /catalog/list соответственно, и переводит их в презентеры и действия Article:edit и Catalog:list соответственно.

Он также придает параметрам presenter и action значения по умолчанию Home и default и поэтому они являются необязательными. Поэтому маршрут также принимает URL /article и переводит его как Article:default. Или наоборот, ссылка на Product:default генерирует путь /product, ссылка на стандартную Home:default генерирует путь /.

Маска может описывать не только относительный путь, основанный на корне сайта, но и абсолютный путь, если он начинается со слэша, или даже весь абсолютный URL, если он начинается с двух слэшей:

// относительный путь к корню приложения
$router->addRoute('<presenter>/<action>', /* ... */);

// абсолютный путь, относительно имени хоста сервера
$router->addRoute('/<presenter>/<action>', /* ... */);

// абсолютный URL, включая имя хоста (относительно схемы)
$router->addRoute('//<lang>.example.com/<presenter>/<action>', /* ... */);

// абсолютный URL, включая схему
$router->addRoute('https://<lang>.example.com/<presenter>/<action>', /* ... */);

Валидационные выражения

Для каждого параметра можно задать условие проверки с помощью регулярного выражения. Например, давайте зададим id только числовым, используя \d+ regexp:

$router->addRoute('<presenter>/<action>[/<id \d+>]', /* ... */);

По умолчанию регулярным выражением для всех параметров является [^/]+, то есть всё, кроме слэша. Если параметр должен соответствовать также косой черте, мы задаем регулярное выражение .+.

// принимает https://example.com/a/b/c, path — 'a/b/c'
$router->addRoute('<path .+>', /* ... */);

Необязательные последовательности

Квадратные скобки обозначают необязательные части маски. Любая часть маски может быть задана как необязательная, включая те, которые содержат параметры:

$router->addRoute('[<lang [a-z]{2}>/]<name>', /* ... */);

// Принимаемые URL-адреса:  Параметры:
//   /en/download           lang => en, name => download
//   /download              lang => null, name => download

Конечно, когда параметр является частью необязательной последовательности, он также становится необязательным. Если у него нет значения по умолчанию, он будет равен null.

Необязательные части также могут быть в домене:

$router->addRoute('//[<lang=en>.]example.com/<presenter>/<action>', /* ... */);

Последовательности могут быть свободно вложены и объединены:

$router->addRoute(
	'[<lang [a-z]{2}>[-<sublang>]/]<name>[page-<page=0>]',
	'Home:default',
);

// Принимаемые URL-адреса:
//   /ru/hello
//   /en-us/hello
//   /hello
//   /hello/page-12

Генератор URL старается сделать URL как можно короче, поэтому то, что можно опустить, опускается. Поэтому, например, маршрут index[.html] генерирует путь /index. Вы можете изменить это поведение, написав восклицательный знак после левой квадратной скобки:

// принимает /hello и /hello.html, генерирует /hello
$router->addRoute('<name>[.html]', /* ... */);

// принимает /hello и /hello.html, генерирует /hello.html
$router->addRoute('<name>[!.html]', /* ... */);

Необязательные параметры (т. е. параметры, имеющие значение по умолчанию) без квадратных скобок ведут себя так, как если бы они были обернуты таким образом:

$router->addRoute('<presenter=Home>/<action=default>/<id=>', /* ... */);

// equals to:
$router->addRoute('[<presenter=Home>/[<action=default>/[<id>]]]', /* ... */);

Чтобы изменить способ генерации самой правой косой черты, т. е. вместо /home/ получить /home, настройте маршрут таким образом:

$router->addRoute('[<presenter=Home>[/<action=default>[/<id>]]]', /* ... */);

Символы подстановки

В маске абсолютного пути мы можем использовать следующие подстановочные знаки, чтобы избежать, например, необходимости записывать в маску домен, который может отличаться в среде разработки и производственной среде:

%tld% = домен верхнего уровня, например, com или org
%sld% = домен второго уровня, например, example
%domain% = домен без поддоменов, например, example.com
%host% = весь хост, например, www.example.com
%basePath% = путь к корневому каталогу

$router->addRoute('//www.%domain%/%basePath%/<presenter>/<action>', /* ... */);
$router->addRoute('//www.%sld%.%tld%/%basePath%/<presenter>/<action', /* ... */);

Расширенная нотация

Цель маршрута, обычно записываемая в виде Presenter:action, также может быть выражена с помощью массива, определяющего отдельные параметры и их значения по умолчанию:

$router->addRoute('<presenter>/<action>[/<id \d+>]', [
	'presenter' => 'Home',
	'action' => 'default',
]);

Для более детальной спецификации можно использовать еще более расширенную форму, в которой помимо значений по умолчанию можно задать другие свойства параметров, например, регулярное выражение для проверки (см. параметр id ):

use Nette\Routing\Route;

$router->addRoute('<presenter>/<action>[/<id>]', [
	'presenter' => [
		Route::Value => 'Home',
	],
	'action' => [
		Route::Value => 'default',
	],
	'id' => [
		Route::Pattern => '\d+',
	],
]);

Важно отметить, что если параметры, определенные в массиве, не включены в маску пути, их значения не могут быть изменены, даже с помощью параметров запроса, указанных после вопросительного знака в URL.

Фильтры и переводы

Хорошей практикой является написание исходного кода на английском языке, но что если вам нужно, чтобы URL вашего сайта был переведен на другой язык?

$router->addRoute('<presenter>/<action>', 'Home:default');

будет генерировать английские URL, такие как /product/123 или /cart. Если мы хотим, чтобы презентеры и действия в URL были переведены на немецкий язык (например, /produkt/123 или /einkaufswagen), мы можем использовать словарь переводов. Чтобы добавить его, нам уже нужен «более понятный» вариант второго параметра:

use Nette\Routing\Route;

$router->addRoute('<presenter>/<action>', [
	'presenter' => [
		Route::Value => 'Home',
		Route::FilterTable => [
			// строка в URL => ведущий
			'produkt' => 'Product',
			'einkaufswagen' => 'Cart',
			'katalog' => 'Catalog',
		],
	],
	'action' => [
		Route::Value => 'default',
		Route::FilterTable => [
			'liste' => 'list',
		],
	],
]);

Для одного и того же презентера можно использовать несколько ключей словаря. Они будут создавать для него различные псевдонимы. Последний ключ считается каноническим вариантом (т. е. тот, который будет в сгенерированном URL).

Таблица перевода может быть применена к любому параметру таким образом. Однако если перевода не существует, берется исходное значение. Мы можем изменить это поведение, добавив Route::FilterStrict => true, и тогда маршрут будет отклонять URL, если значение отсутствует в словаре.

В дополнение к словарю перевода в виде массива можно задать собственные функции перевода:

use Nette\Routing\Route;

$router->addRoute('<presenter>/<action>/<id>', [
	'presenter' => [
		Route::Value => 'Home',
		Route::FilterIn => function (string $s): string { /* ... */ },
		Route::FilterOut => function (string $s): string { /* ... */ },
	],
	'action' => 'default',
	'id' => null,
]);

Функция Route::FilterIn осуществляет преобразование между параметром в URL и строкой, которая затем передается презентеру, функция FilterOut обеспечивает преобразование в обратном направлении.

Параметры presenter, action и module уже имеют предопределенные фильтры, которые конвертируют между PascalCase, camelCase и kebab-case соответственно, используемые в URL. Значение параметров по умолчанию уже записано в преобразованной форме, поэтому, например, в случае с презентером мы пишем <presenter=ProductEdit> вместо <presenter=product-edit>.

Общие фильтры

Помимо фильтров для конкретных параметров, вы также можете определить общие фильтры, получающие ассоциативный массив всех параметров, которые они могут изменять любым способом, а затем возвращать. Общие фильтры определяются по ключу null.

use Nette\Routing\Route;

$router->addRoute('<presenter>/<action>', [
	'presenter' => 'Home',
	'action' => 'default',
	null => [
		Route::FilterIn => function (array $params): array { /* ... */ },
		Route::FilterOut => function (array $params): array { /* ... */ },
	],
]);

Общие фильтры дают вам возможность настроить поведение маршрута абсолютно любым способом. Мы можем использовать их, например, для изменения параметров на основе других параметров. Например, перевод <presenter> и <action> на основе текущего значения параметра <lang>.

Если для параметра определен пользовательский фильтр и одновременно существует общий фильтр, пользовательский FilterIn выполняется перед общим, и наоборот, общий FilterOut выполняется перед пользовательским. Таким образом, внутри общего фильтра находятся значения параметров presenter и action соответственно, написанное на языке PascalCase и camelCase соответственно.

Флаг OneWay

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

// старый URL /product-info?id=123
$router->addRoute('product-info', 'Product:detail', $router::ONE_WAY);
// новый URL /product/123
$router->addRoute('product/<id>', 'Product:detail');

При обращении к старому URL-адресу презентер автоматически перенаправляет на новый URL-адрес, чтобы поисковые системы не индексировали эти страницы дважды (см. SEO и канонизация).

Динамическая маршрутизация с обратными вызовами

Динамическая маршрутизация с обратными вызовами позволяет напрямую назначать маршрутам функции (обратные вызовы), которые будут выполняться при посещении указанного пути. Эта гибкая возможность позволяет быстро и эффективно создавать различные конечные точки для вашего приложения:

$router->addRoute('test', function () {
	echo 'You are at the /test address';
});

Вы также можете задать параметры в маске, которые будут автоматически передаваться в обратный вызов:

$router->addRoute('<lang cs|en>', function (string $lang) {
	echo match ($lang) {
		'cs' => 'Welcome to the Czech version of our website!',
		'en' => 'Welcome to the English version of our website!',
	};
});

Модули

Если у нас есть несколько маршрутов, принадлежащих одному модулю, мы можем использовать withModule() для их группировки:

$router = new RouteList;
$router->withModule('Forum') // следующие маршрутизаторы входят в состав модуля Forum
	->addRoute('rss', 'Feed:rss') // презентер Forum:Feed
	->addRoute('<presenter>/<action>')

	->withModule('Admin') // следующие маршрутизаторы являются частью модуля Forum:Admin
		->addRoute('sign:in', 'Sign:in');

Альтернативой является использование параметра module:

// URL manage/dashboard/default отображается на ведущего Admin:Dashboard
$router->addRoute('manage/<presenter>/<action>', [
	'module' => 'Admin',
]);

Субдомены

Коллекции маршрутов могут быть сгруппированы по поддоменам:

$router = new RouteList;
$router->withDomain('example.com')
	->addRoute('rss', 'Feed:rss')
	->addRoute('<presenter>/<action>');

Вы также можете использовать Символы подстановки в своем доменном имени:

$router = new RouteList;
$router->withDomain('example.%tld%')
	// ...

Префикс пути

Коллекции маршрутов могут быть сгруппированы по пути в URL:

$router = new RouteList;
$router->withPath('eshop')
	->addRoute('rss', 'Feed:rss') // соответствует URL /eshop/rss
	->addRoute('<presenter>/<action>'); //  соответствует URL /eshop/<presenter>/<action>

Комбинации

Вышеуказанные варианты использования можно комбинировать:

$router = (new RouteList)
	->withDomain('admin.example.com')
		->withModule('Admin')
			->addRoute(/* ... */)
			->addRoute(/* ... */)
		->end()
		->withModule('Images')
			->addRoute(/* ... */)
		->end()
	->end()
	->withDomain('example.com')
		->withPath('export')
			->addRoute(/* ... */)
			// ...

Параметры запроса

Маски также могут содержать параметры запроса (параметры после знака вопроса в URL). Они не могут определить выражение проверки, но они могут изменить имя, под которым они передаются презентеру:

// используем параметр запроса 'cat' в качестве 'categoryId' в приложении
$router->addRoute('product ? id=<productId> & cat=<categoryId>', /* ... */);

Параметры Foo

Теперь мы идем глубже. Параметры Foo — это, по сути, неименованные параметры, которые позволяют сопоставить регулярное выражение. Следующий маршрут соответствует /index, /index.html, /index.htm и /index.php:

$router->addRoute('index<? \.html?|\.php|>', /* ... */);

Также можно явно задать строку, которая будет использоваться для генерации URL. Строка должна располагаться непосредственно после знака вопроса. Следующий маршрут похож на предыдущий, но генерирует /index.html вместо /index, потому что строка .html установлена как «генерируемое значение».

$router->addRoute('index<?.html \.html?|\.php|>', /* ... */);

Интеграция

Чтобы подключить наш маршрутизатор к приложению, мы должны сообщить о нем контейнеру DI. Самый простой способ – это подготовить фабрику, которая будет создавать объект маршрутизатора, и сообщить конфигурации контейнера, чтобы она его использовала. Допустим, мы напишем для этого метод App\Core\RouterFactory::createRouter():

namespace App\Core;

use Nette\Application\Routers\RouteList;

class RouterFactory
{
	public static function createRouter(): RouteList
	{
		$router = new RouteList;
		$router->addRoute(/* ... */);
		return $router;
	}
}

Затем мы пишем в configuration:

services:
	- App\Core\RouterFactory::createRouter

Любые зависимости, такие как подключение к базе данных и т.д., передаются методу фабрики в качестве параметров с помощью autowiring:

public static function createRouter(Nette\Database\Connection $db): RouteList
{
	// ...
}

SimpleRouter

Гораздо более простым маршрутизатором, чем коллекция маршрутов, является SimpleRouter. Его можно использовать, когда нет необходимости в определенном формате URL, когда mod_rewrite (или альтернативы) недоступен или когда мы просто не хотим пока возиться с удобными для пользователя URL.

Генерирует адреса примерно такой формы:

http://example.com/?presenter=Product&action=detail&id=123

Параметром конструктора SimpleRouter является презентер и действие по умолчанию, т. е. действие, которое будет выполнено, если мы откроем, например, http://example.com/ без дополнительных параметров.

// используем презентер 'Home' и действие 'default'
$router = new Nette\Application\Routers\SimpleRouter('Home:default');

Мы рекомендуем определять SimpleRouter непосредственно в конфигурации:

services:
	- Nette\Application\Routers\SimpleRouter('Home:default')

SEO и канонизация

Фреймворк улучшает SEO, предотвращая дублирование контента на разных URL. Если несколько адресов ссылаются на одно и то же место назначения, например /index и /index.html, фреймворк определяет первый из них как основной (канонический) и перенаправляет на него остальные с помощью HTTP-кода 301. Благодаря этому поисковые системы не будут индексировать страницы дважды и не нарушат их страничный рейтинг.

Этот процесс называется канонизацией. Канонический URL — это URL, сгенерированный маршрутизатором, т. е. первым подходящим маршрутом в коллекции без флага OneWay. Поэтому в коллекции мы перечисляем первичные маршруты первыми.

Канонизация осуществляется презентером, подробнее в главе Канонизация.

HTTPS

Для того чтобы использовать протокол HTTPS, необходимо активировать его на хостинге и настроить сервер.

Перенаправление всего сайта на HTTPS должно быть выполнено на уровне сервера, например, с помощью файла .htaccess в корневом каталоге нашего приложения, с HTTP-кодом 301. Настройки могут отличаться в зависимости от хостинга и выглядят примерно так:

<IfModule mod_rewrite.c>
	RewriteEngine On
	...
	RewriteCond %{HTTPS} off
	RewriteRule .* https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
	...
</IfModule>

Маршрутизатор генерирует URL с тем же протоколом, по которому была загружена страница, поэтому нет необходимости задавать что-либо ещё.

Однако, если нам исключительно нужно, чтобы разные маршруты работали под разными протоколами, мы поместим это в маску маршрута:

// Сгенерирует HTTP адрес
$router->addRoute('http://%host%/<presenter>/<action>', /* ... */);

// Сгенерирует HTTPS адрес
$router->addRoute('https://%host%/<presenter>/<action>', /* ... */);

Отладчик маршрутизации

Полоса маршрутизации, показанная в Tracy Bar, является полезным инструментом, который отображает список маршрутов, а также параметры, которые маршрутизатор получил из URL.

Зеленая полоса с символом ✓ представляет маршрут, который соответствует текущему URL, синие полосы с символами ≈ указывают на маршруты, которые также соответствовали бы URL, если бы зеленый цвет не обогнал их. Далее мы видим текущего ведущего и действия.

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

При отладке маршрутизатора рекомендуется открыть Developer Tools в браузере (Ctrl+Shift+I или Cmd+Option+I) и отключить кэш в панели Network, чтобы перенаправления не сохранялись в нем.

Производительность

Количество маршрутов влияет на скорость маршрутизатора. Их количество, конечно, не должно превышать нескольких десятков. Если ваш сайт имеет слишком сложную структуру URL, вы можете написать Пользовательский маршрутизатор.

Если маршрутизатор не имеет зависимостей, например, от базы данных, и его фабрика не имеет аргументов, мы можем сериализовать его скомпилированную форму непосредственно в DI-контейнер и тем самым сделать приложение немного быстрее.

routing:
	cache: true

Пользовательский маршрутизатор

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

use Nette\Http\IRequest as HttpRequest;
use Nette\Http\UrlScript;

class MyRouter implements Nette\Routing\Router
{
	public function match(HttpRequest $httpRequest): ?array
	{
		// ...
	}

	public function constructUrl(array $params, UrlScript $refUrl): ?string
	{
		// ...
	}
}

Метод match обрабатывает текущий $httpRequest, из которого может быть извлечен не только URL, но и заголовки и т.д., в массив, содержащий имя ведущего и его параметры. Если он не может обработать запрос, то возвращает null. При обработке запроса мы должны вернуть как минимум ведущего и действие. Имя ведущего является полным и включает любые модули:

[
	'presenter' => 'Front:Home',
	'action' => 'default',
]

Метод constructUrl, с другой стороны, генерирует абсолютный URL из массива параметров. Он может использовать информацию из параметра $refUrl, который является текущим URL.

Чтобы добавить пользовательский маршрутизатор в коллекцию маршрутов, используйте add():

$router = new Nette\Application\Routers\RouteList;
$router->add(new MyRouter);
$router->addRoute(/* ... */);
// ...

Раздельное использование

Под раздельным использованием подразумевается использование возможностей маршрутизатора в приложении, которое не использует приложение Nette и презентеры. К нему применимо почти всё, что мы показали в этой главе, со следующими отличиями:

для коллекций маршрутов мы используем класс Nette\Routing\RouteList.
как класс простого маршрутизатора Nette\Routing\SimpleRouter.
поскольку нет пары Presenter:action, мы используем Расширенная нотация.

Итак, мы снова добавим метод, который будет создавать, например, маршрутизатор:

namespace App\Core;

use Nette\Routing\RouteList;

class RouterFactory
{
	public static function createRouter(): RouteList
	{
		$router = new RouteList;
		$router->addRoute('rss.xml', [
			'controller' => 'RssFeedController',
		]);
		$router->addRoute('article/<id \d+>', [
			'controller' => 'ArticleController',
		]);
		// ...
		return $router;
	}
}

Если вы используете DI-контейнер, как мы рекомендуем, добавьте метод в конфигурацию ещё раз, а затем получите маршрутизатор вместе с HTTP-запросом из контейнера:

$router = $container->getByType(Nette\Routing\Router::class);
$httpRequest = $container->getByType(Nette\Http\IRequest::class);

Или мы будем создавать объекты напрямую:

$router = App\Core\RouterFactory::createRouter();
$httpRequest = (new Nette\Http\RequestFactory)->fromGlobals();

Теперь нужно дать маршрутизатору поработать:

$params = $router->match($httpRequest);
if ($params === null) {
	// не найден совпадающий маршрут, отправим ошибку 404
	exit;
}

// обрабатываем полученные параметры
$controller = $params['controller'];
// ...

И наоборот, мы будем использовать маршрутизатор для создания ссылки:

$params = ['controller' => 'ArticleController', 'id' => 123];
$url = $router->constructUrl($params, $httpRequest->getUrl());