Контроллеры и действия в Yii 2: с чего начать

За полчаса вы создадите контроллер в приложении на Yii 2, привяжете к нему адрес вроде /site/hello, передадите в него параметр из URL и вернёте на экран строку и HTML-страницу. Всё это — на стандартном шаблоне yii2-app-basic, без правки конфигов сверх необходимого. Понадобится установленный Yii 2 (актуальна ветка 2.0.x), PHP 7.4 или новее и запущенный веб-сервер или встроенный сервер PHP.

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

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

• Установленное приложение на шаблоне basic (папки controllers, views, config на месте). Ставится через Composer: composer create-project yiisoft/yii2-app-basic.
• PHP 7.4+ и доступ к командной строке — проверьте командой php -v.
• Запущенный сервер. Для проб хватит встроенного: из корня проекта выполните php yii serve, приложение поднимется на http://localhost:8080.
• Права на запись в папку controllers — туда вы будете класть новые файлы.

Открывается стартовая страница по адресу http://localhost:8080 — значит, окружение готово, и можно двигаться дальше.

Как Yii находит контроллер по адресу

В Yii 2 адрес разбирается на три части: модуль / контроллер / действие. В базовом приложении модулей нет, поэтому остаётся контроллер/действие. Запрос /site/hello означает: класс SiteController, метод actionHello.

Правило, которое экономит часы отладки: имя класса пишется в CamelCase и заканчивается на Controller, а в URL идёт в нижнем регистре с дефисами. Метод действия начинается с actionИмя, в URL превращается в имя. actionHelloWorld станет /site/hello-world.

Отсюда сразу три вещи, которые надо запомнить:

• Файл контроллера кладётся в папку controllers и называется как класс: SiteController.php.
• Пространство имён внутри файла — app\controllers. Если ошибиться в нём, вы получите ошибку «класс не найден», хотя файл лежит на месте.
• Действие по умолчанию — index. Адрес /site без указания действия вызовет actionIndex.

Шаг 1. Создайте контроллер

В папке controllers создайте файл HelloController.php с таким содержимым:

<?php

namespace app\controllers;

use yii\web\Controller;

class HelloController extends Controller
{
    // Действие по умолчанию: откроется по адресу /hello
    public function actionIndex()
    {
        return 'Привет из HelloController';
    }
}

Проверка: откройте http://localhost:8080/index.php?r=hello/index (или /hello, если включены человекопонятные URL — об этом ниже). На экране должна появиться строка «Привет из HelloController». Если появилась — контроллер найден и вызван.

Обратите внимание: действие вернуло обычную строку, и Yii отдал её как есть. Это работает для быстрой проверки, но нормальный ответ — это рендер представления, к которому мы придём на шаге 3.

Шаг 2. Примите параметр из URL

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

    // Откроется по адресу /hello/greet?name=Иван
    public function actionGreet($name = 'гость')
    {
        return 'Здравствуйте, ' . htmlspecialchars($name);
    }

Проверка: адрес http://localhost:8080/index.php?r=hello/greet&name=Иван выведет «Здравствуйте, Иван». Без параметра name сработает значение по умолчанию — «гость».

Здесь два момента, на которых спотыкаются новички. Первый: имя аргумента метода должно совпадать с именем параметра в URL — $name ловит ?name=. Второй: если у аргумента нет значения по умолчанию и параметр в запросе отсутствует, Yii вернёт ошибку 400 «Missing required parameters». Поэтому htmlspecialchars здесь не для красоты — данные из URL нельзя выводить в HTML напрямую.

Шаг 3. Верните представление вместо строки

Возвращать строки — это для проб. Реальное действие рендерит представление — файл в папке views. Создайте папку views/hello и в ней файл page.php:

<?php
/* @var $this yii\web\View */
/* @var $name string */
?>
<h1>Здравствуйте, <?= yii\helpers\Html::encode($name) ?></h1>
<p>Это представление hello/page.php</p>

Теперь добавьте действие, которое рендерит этот файл и передаёт в него данные:

    public function actionPage($name = 'гость')
    {
        // Первый аргумент — имя файла в views/hello без .php
        // Второй — массив данных, ключи станут переменными во вьюхе
        return $this->render('page', [
            'name' => $name,
        ]);
    }

Проверка: адрес /index.php?r=hello/page&name=Мир отдаст полноценную HTML-страницу с шапкой и подвалом шаблона — потому что render, в отличие от renderPartial, оборачивает представление в общий макет views/layouts/main.php.

Ключевая разница, которую стоит усвоить сразу:

• render() — представление плюс общий макет (шапка, меню, подвал). Для страниц.
• renderPartial() — только само представление, без макета. Для кусков, AJAX-ответов, писем.

Три способа вернуть ответ — что когда

Действие может вернуть не только HTML. Yii смотрит на тип возвращаемого значения и формат ответа.

Частая ошибка новичка — писать echo внутри действия вместо return. Работать вроде будет, но вы потеряете контроль над макетом, заголовками и форматом ответа. В Yii действие всегда возвращает результат, а не печатает его.

Про человекопонятные URL

Все адреса выше содержат index.php?r=. Это работает из коробки. Чтобы получить чистые адреса вроде /hello/page, нужно включить компонент urlManager в config/web.php и настроить веб-сервер. В шаблоне basic соответствующий блок закомментирован — найдите в конфиге секцию components и раскомментируйте urlManager с 'enablePrettyUrl' => true. Точный синтаксис и настройку Apache/Nginx смотрите в руководстве по маршрутизации — конфигурация сервера зависит от вашего окружения, и подставлять её вслепую не стоит.

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

Пять ошибок, которые вы почти наверняка увидите, и что с ними делать.

• «Unable to find app\controllers\HelloController» — имя класса не совпадает с именем файла, либо неверное namespace. Файл HelloController.php, класс HelloController, namespace app\controllers.
• «Unable to resolve the request: hello/greet» — метод назван неправильно. Нужен actionGreet (с большой буквы после action), а URL — hello/greet.
• «Missing required parameters: name» — параметр в URL отсутствует, а у аргумента нет значения по умолчанию. Добавьте = 'гость' или передайте параметр.
• Белый экран без текста ошибки — в config/web.php отключён режим отладки. В файле web/index.php для локальной разработки должны быть заданы YII_DEBUG = true и YII_ENV = 'dev' — тогда Yii покажет подробную страницу ошибки.
• «The view file does not exist: .../views/hello/page.php» — файл представления лежит не в той папке. Yii ищет его в views/имя-контроллера/. Для HelloController это views/hello/.

Что делать дальше

Когда первый контроллер работает, следующий разумный шаг — разобраться с beforeAction() и фильтрами доступа: как ограничить действие только авторизованным пользователям через AccessControl. Отдельная большая тема — привязка данных из формы к модели через load() и validate(); здесь мы её не трогали. Настройку человекопонятных URL и правил маршрутизации оставьте на момент, когда базовые действия уже отвечают — иначе будете отлаживать сразу две вещи.