Маршруты в Yii2: короткий гайд по настройке URL

К концу этого гайда у вас будут работать красивые адреса вместо index.php?r=post/view&id=42: страница откроется по /post/42, а форма поиска — по /search. На настройку уйдёт минут двадцать-тридцать, если сервер уже отдаёт ваше приложение. Всё написано для Yii2 (2.0.x) и стандартного шаблона проекта (basic или advanced).

Что нужно иметь до начала

• Установленный и работающий проект на Yii2 — по адресу вроде /index.php открывается стартовая страница.
• PHP 7.4 или новее и веб-сервер Apache или Nginx с правами на правку конфигурации либо на размещение файла .htaccess в корне.
• Доступ к файлу конфигурации приложения: в шаблоне basic это config/web.php, в advanced — frontend/config/main.php (и/или backend/config/main.php).
• Понимание, где лежат ваши контроллеры (controllers/) и как называются их действия — методы вида actionView().

Если правки конфигурации веб-сервера вам недоступны (shared-хостинг без доступа к nginx.conf), для Apache хватит .htaccess — про это ниже.

Как маршрут превращается в действие

Маршрут в Yii2 — это строка вида controllerID/actionID. Например, post/view означает: контроллер PostController, действие actionView(). Компонент urlManager отвечает за две вещи: разбирает входящий адрес в маршрут с параметрами и, наоборот, собирает адрес из маршрута, когда вы вызываете Url::to() в шаблоне.

По умолчанию адреса выглядят как index.php?r=post/view&id=42. Чтобы включить человекочитаемый вид, настраивается urlManager.

Шаг 1. Включаем красивые URL

Откройте конфигурацию приложения и найдите (или добавьте) блок components. Впишите в него настройку компонента urlManager:

// config/web.php (Yii2 2.0.x), внутри массива 'components'
'urlManager' => [
    'enablePrettyUrl' => true,   // адреса без index.php?r=
    'showScriptName' => false,  // убрать index.php из адреса
    'rules' => [
        // правила добавим на следующем шаге
    ],
],

Проверка: после этого адрес /site/about (без index.php?r=) должен открыть страницу «О нас». Если вместо неё вы видите 404 от веб-сервера — сначала настройте перезапись адресов (шаг 2), сервер пока не знает, что все запросы нужно отдавать в index.php.

Шаг 2. Настраиваем веб-сервер

Пока showScriptName равно false, сервер должен направлять все несуществующие пути на входной скрипт.

Для Nginx в блок server добавьте:

location / {
    try_files $uri $uri/ /index.php?$args;
}

Для Apache положите в корень сайта файл .htaccess:

RewriteEngine on

# если запрошенного файла или каталога нет — отдаём в index.php
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . index.php

Для работы .htaccess у Apache должен быть включён mod_rewrite и разрешён AllowOverride для этого каталога.

Проверка: обновите /site/about — теперь страница откроется без index.php в адресе.

Шаг 3. Добавляем свои правила

Теперь опишем, как /post/42 должен приводить к действию actionView() с параметром id = 42. Правила задаются в ключе rules:

'urlManager' => [
    'enablePrettyUrl' => true,
    'showScriptName' => false,
    'rules' => [
        // /post/42  ->  post/view?id=42
        'post/<id:\d+>' => 'post/view',

        // /posts    ->  post/index
        'posts' => 'post/index',

        // /search   ->  site/search
        'search' => 'site/search',
    ],
],

Здесь <id:\d+> — именованный параметр: любой набор цифр из адреса попадёт в $id. Действие принимает его как аргумент метода:

// controllers/PostController.php
public function actionView($id)
{
    // $id уже равен 42 при заходе на /post/42
    return $this->render('view', ['id' => $id]);
}

Проверка: откройте /post/42 — должно сработать действие actionView со значением 42. Если открыли /post/abc, правило не сработает, потому что \d+ ждёт только цифры.

Шаг 4. Строим адреса из кода

Не пишите пути руками в шаблонах — тогда при смене правил ссылки не сломаются. Собирайте адрес из маршрута:

use yii\helpers\Url;

// вернёт /post/42
Url::to(['post/view', 'id' => 42]);

// вернёт /posts
Url::to(['post/index']);

urlManager находит подходящее правило и собирает адрес в том же виде, в каком его разбирает. Меняете правило — ссылки перестраиваются сами.

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

Порядок правил имеет значение

urlManager проверяет правила сверху вниз и берёт первое подходящее. Если общее правило стоит раньше частного, частное никогда не сработает. Сравните:

Числовое правило должно идти выше строкового, иначе /post/42 уйдёт в правило со slug. Универсальное правило ставьте последним.

Если не получилось

• 404 от веб-сервера (страница Nginx/Apache, а не Yii) — сервер не перенаправляет запросы в index.php. Вернитесь к шагу 2: проверьте try_files в Nginx или .htaccess с mod_rewrite в Apache.
• «Unable to resolve the request …» — 404 уже от Yii — приложение получило запрос, но не нашло подходящий маршрут или контроллер. Проверьте имя контроллера и действия и совпадение маршрута в правиле.
• Адреса открываются только с index.php — вы включили enablePrettyUrl, но не убрали index.php. Проверьте 'showScriptName' => false и что перезапись адресов на сервере действительно работает.
• Параметр не приходит в действие — имя параметра в правиле (<id:\d+>) должно совпадать с именем аргумента метода (actionView($id)). Разные имена — $id будет пустым.
• Ссылки Url::to() ведут не туда — скорее всего сработало более раннее общее правило. Проверьте порядок правил в rules.

Что настроить дальше

Когда базовая маршрутизация работает, посмотрите на две вещи. Первая — UrlNormalizer: он умеет автоматически убирать или добавлять хвостовой слэш и делать 301-редирект, чтобы /posts и /posts/ не считались разными адресами. Вторая — GroupUrlRule и модули, если у вас есть админка с общим префиксом вроде /admin/.... Точный синтаксис этих компонентов и полный список опций urlManager сверяйте в разделе руководства Yii2 про маршрутизацию — там описано и для 2.0.x.