Контроллеры в Yii 2: первые шаги для новичка

К концу этой инструкции у вас будет рабочий контроллер в проекте на Yii 2: вы откроете в браузере адрес вида /site/hello?name=Anna и получите страницу с приветствием. Займёт это минут 20–30, если фреймворк уже установлен. Всё показано на Yii 2.0.x (актуальная стабильная ветка на конец 2024 года) и шаблоне basic.

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

Прежде чем создавать контроллер, проверьте, что у вас есть:

• установленный Yii 2 в шаблоне basic — тот, где папки controllers, views, models лежат в корне проекта;
• PHP 7.4 или новее (Yii 2.0.x работает с PHP 5.4+, но брать древние версии смысла нет);
• работающий веб-сервер или встроенный сервер PHP — его можно запустить командой php yii serve из корня проекта, тогда сайт открывается на http://localhost:8080;
• доступ к папке проекта на запись — контроллер и вид вы будете создавать файлами.

Если php yii serve выдаёт ошибку про неизвестную команду — значит, вы не в корне проекта либо шаблон не basic. В advanced структура другая, и пути в этой инструкции не совпадут.

Что такое контроллер и экшен

Контроллер в Yii — это класс, который принимает запрос от браузера и решает, что вернуть в ответ. Внутри контроллера живут экшены (actions) — методы, каждый из которых отвечает за один адрес. Метод actionHello() обрабатывает запрос /site/hello, метод actionIndex() — /site/index или просто /site.

Связь имени с адресом строится по правилу: action + название с большой буквы превращается в путь строчными буквами. actionShowList() станет /site/show-list — верблюжий регистр разбивается дефисами.

Экшен (action) — публичный метод контроллера с префиксом action, к которому Yii умеет обращаться напрямую из URL. Это точка входа для конкретного запроса.

Шаг за шагом: первый контроллер

1. Создайте файл контроллера. В папке controllers откройте уже существующий SiteController.php — он идёт в шаблоне basic. Добавлять новый файл пока не нужно, начнём с готового.

2. Добавьте экшен. Внутри класса SiteController добавьте метод:

   // controllers/SiteController.php (Yii 2.0.x)
   public function actionHello($name = 'гость')
   {
       // render ищет вид hello.php в папке views/site
       return $this->render('hello', [
           'name' => $name,
       ]);
   }

   Параметр $name Yii автоматически подставит из GET-запроса: ?name=Anna попадёт в переменную. Значение по умолчанию 'гость' сработает, если параметр не передали.

3. Создайте вид. В папке views/site создайте файл hello.php:

   <?php
   // views/site/hello.php
   use yii\helpers\Html;
   
   /* @var $name string */
   ?>
   <h1>Привет, <?= Html::encode($name) ?></h1>

   Функция Html::encode() экранирует значение — без неё пользователь мог бы передать в name HTML или скрипт. Это защита от XSS, привыкайте оборачивать в неё любой вывод внешних данных.

4. Откройте адрес. Запустите php yii serve и зайдите на http://localhost:8080/index.php?r=site/hello&name=Anna. Если ЧПУ-адреса настроены, сработает и короткий /site/hello?name=Anna.

   Проверка: в браузере должна появиться строка «Привет, Anna». Без параметра — «Привет, гость».

Контроллер не должен знать, как данные хранятся, и не должен сам рисовать HTML. Его дело — принять запрос, попросить у модели данные и передать их в вид. Как только в экшене появляется SQL или большой кусок разметки — это сигнал вынести логику наружу.

Отдельный контроллер, а не всё в SiteController

Складывать все экшены в SiteController — плохая привычка. Под отдельную сущность создавайте свой контроллер. Правило именования жёсткое: файл и класс называются с суффиксом Controller, а само имя — в верблюжьем регистре.

Создайте controllers/ProductController.php:

<?php
// controllers/ProductController.php (Yii 2.0.x)
namespace app\controllers;

use yii\web\Controller;

class ProductController extends Controller
{
    public function actionView($id)
    {
        return $this->render('view', [
            'id' => (int) $id,
        ]);
    }
}

Как имя файла превращается в адрес — в таблице ниже.

Namespace app\controllers обязателен: по нему Yii находит класс. Если поставите не тот namespace, получите ошибку «Unable to find controller».

Как вернуть данные, а не страницу

Не каждый экшен рендерит HTML. Для API удобнее отдавать JSON. Yii умеет это сам, если вернуть массив и переключить формат ответа:

public function actionJson()
{
    // формат ответа задаётся через компонент response
    \Yii::$app->response->format = \yii\web\Response::FORMAT_JSON;
    return [
        'status' => 'ok',
        'items'  => [1, 2, 3],
    ];
}

Массив автоматически превратится в JSON, заголовок Content-Type выставится сам. Возвращать строку из render и массив из другого экшена — нормально, Yii разберётся по типу возвращаемого значения.

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

• «Unable to resolve the request: site/hello» — экшен не найден. Проверьте, что метод называется именно actionHello (с префиксом action) и он public. Приватный или защищённый метод Yii не вызовет.
• «The view file does not exist: .../views/site/hello.php» — экшен есть, а вида нет. Файл вида кладётся в views/ + имя контроллера строчными (site) + имя вида. Проверьте регистр букв в имени файла — на Linux он важен.
• «Class app\controllers\ProductController does not exist» — неверный namespace или имя файла не совпадает с именем класса. Файл ProductController.php, класс ProductController, namespace app\controllers — три вещи должны сойтись.
• Пустая белая страница — включите отладку: в web/index.php шаблона basic обычно стоят константы YII_DEBUG и YII_ENV. В режиме dev Yii покажет текст ошибки вместо белого экрана.
• Короткий адрес /site/hello даёт 404, а ?r=site/hello работает — не настроены человекопонятные URL. Это отдельная тема (компонент urlManager и prettyUrl), здесь мы её не разворачиваем; пока пользуйтесь адресом с ?r=.

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

Когда первый контроллер отвечает, следующий полезный шаг — научиться отдавать данные из базы. Для этого понадобится модель (ActiveRecord) и передача её в вид тем же способом, что и переменную $name. Дальше стоит разобраться с фильтрами доступа (behaviors() и AccessControl) — они решают, кто вправе открыть экшен, — и с человекопонятными URL через urlManager. Пока просто убедитесь, что каждый ваш экшен делает одно понятное действие и не тащит внутрь себя работу с базой напрямую.