Красивые URL в Yii 2: настройка маршрутизации с нуля

По умолчанию Yii 2 отдаёт адреса вида /index.php?r=post/view&id=42. К концу этого руководства вы получите /post/42, уберёте index.php из ссылок и научитесь описывать собственные правила маршрутизации. Работа идёт с Yii 2.0.x и веб-сервером Apache или Nginx. Займёт около 20 минут.

Что нужно до начала

Проверьте, что у вас есть перед настройкой. Если чего-то не хватает, красивые URL либо не включатся, либо будут отдавать 404 на каждой странице.

• Работающий проект на Yii 2.0.x (basic или advanced template) — приложение открывается через index.php?r=site/index.
• Веб-сервер Apache с включённым модулем mod_rewrite или Nginx с доступом к конфигу сайта.
• Доступ к файлу конфигурации приложения: в basic-шаблоне это config/web.php, в advanced — frontend/config/main.php.
• Права на редактирование .htaccess (для Apache) или конфига виртуального хоста (для Nginx).

Шаг 1. Включить urlManager

Компонент urlManager отвечает за разбор входящих адресов и генерацию ссылок. Найдите в конфиге секцию components и добавьте туда настройку. Класс компонента менять не нужно — он подключается по умолчанию, мы только меняем параметры.

// config/web.php, внутри массива 'components'
'urlManager' => [
    'enablePrettyUrl' => true,   // включаем красивые адреса
    'showScriptName' => false,   // убираем index.php из ссылок
    'enableStrictParsing' => false, // разрешаем стандартный роутинг помимо правил
    'rules' => [
        // правила добавим на следующем шаге
    ],
],

Проверка: после сохранения откройте главную по адресу /site/index без index.php?r=. Если страница открылась — компонент работает. Если получили 404, переходите к шагу 2: сервер ещё не настроен на перенаправление запросов.

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

Yii умеет строить красивые ссылки, но сам сервер должен передавать все несуществующие пути на index.php. Без этого /post/42 сервер попытается найти как реальный файл и вернёт 404.

Apache

Создайте или отредактируйте файл .htaccess в корне веб-директории (там же, где index.php):

RewriteEngine on

# если запрошенный файл или папка существуют — отдаём как есть
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d

# всё остальное перенаправляем на index.php
RewriteRule . index.php

Убедитесь, что в конфиге Apache для этой директории стоит AllowOverride All, иначе .htaccess игнорируется.

Nginx

В блок server добавьте location для корня. Точный синтаксис директив FastCGI зависит от вашей сборки PHP-FPM, сверяйтесь с официальной документацией Yii по развёртыванию.

location / {
    # пробуем файл, потом папку, иначе — index.php
    try_files $uri $uri/ /index.php?$args;
}

Проверка: перезапустите сервер и снова откройте /site/index. Страница должна открыться без ошибки. Теперь ссылки, сгенерированные через Url::to(), будут без index.php.

Шаг 3. Написать правила маршрутизации

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

'rules' => [
    // /post/42 -> PostController::actionView(['id' => 42])
    'post/<id:\d+>' => 'post/view',

    // /posts -> PostController::actionIndex()
    'posts' => 'post/index',

    // /о-компании -> SiteController::actionAbout()
    'о-компании' => 'site/about',
],

Запись <id:\d+> означает: подставить в правило параметр id, состоящий только из цифр. Регулярное выражение после двоеточия ограничивает, что попадёт в параметр. Без него <id> примет любой текст, и адрес станет неоднозначным.

Обратная генерация ссылок

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

use yii\helpers\Url;

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

// абсолютный адрес: https://example.com/posts
echo Url::to(['post/index'], true);

Проверка: откройте /post/1 — должно вызваться действие view и прийти $id === '1'. Проверьте в действии контроллера, что параметр действительно приходит.

Шаг 4. Группировка и модули

Когда контроллеров становится много, повторять префиксы неудобно. Yii позволяет описать группу правил через groupUrlRule — но для базового случая достаточно просто добавлять префикс в шаблон:

'rules' => [
    // все правила API под префиксом /api
    'api/user/<id:\d+>' => 'api/user/view',
    'api/users' => 'api/user/index',
],

Не заводите правило под каждый экшен вручную, если их десятки. Одно правило '<controller:\w+>/<action:\w+>' покроет стандартный роутинг, а точечные правила оставьте для адресов, которые должны отличаться от имени действия.

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

Пять ошибок, которые встречаются чаще остальных.

• 404 на всех страницах кроме главной. Сервер не перенаправляет запросы на index.php. Проверьте .htaccess и AllowOverride All для Apache или try_files для Nginx.
• index.php всё ещё в ссылках. Забыли 'showScriptName' => false либо правите не тот конфиг (в advanced-шаблоне frontend и backend имеют разные конфиги).
• «Unable to resolve the request» на красивом адресе. Включён enableStrictParsing = true, но правило для этого адреса не описано. Либо добавьте правило, либо верните строгий парсинг в false.
• Параметр приходит как строка, а вы ждёте число. Из URL параметры всегда приходят строками. '1' == 1 в PHP истинно, но при строгом сравнении приводите тип сами: (int)$id.
• Правило не срабатывает, хотя адрес совпадает. Более общее правило стоит выше и перехватывает запрос. Переставьте специфичные правила вверх списка.

Что дальше

Красивые URL включены — дальше стоит настроить обработку 404 через errorHandler, чтобы несуществующие адреса отдавали вашу страницу, а не белый экран. Для многоязычных сайтов посмотрите правило с префиксом языка (<language:\w+>/...) и класс UrlNormalizer — он умеет убирать или добавлять слэш в конце адреса и делать 301-редирект, чтобы у одной страницы не было двух адресов. Инвалидация кеша роутинга при enableCaching — отдельная тема, здесь мы её не трогали.