Yii2 против Yii3: что реально изменилось и стоит ли мигрировать

Yii2 вышел в 2014 году и до сих пор держит боевые проекты: последняя стабильная линия — 2.0.x, её поддержка официально продлена командой из-за того, что Yii3 задержался на годы. Yii3 к моменту написания находится в статусе, когда отдельные пакеты уже стабильны, а полноценного финального релиза фреймворка целиком пока нет — проверяйте актуальный статус в репозитории yiisoft/app. Разница между версиями — не косметика вроде переименованных методов. Это другой подход к сборке приложения. Ниже — что конкретно поменялось и во что обойдётся переезд.

Главное различие: монолит против набора пакетов

Yii2 — это один большой фреймворк. Вы ставите yiisoft/yii2, получаете роутер, ActiveRecord, валидацию, виджеты, помощники, консоль — всё сразу, связанное общими соглашениями и глобальным объектом Yii::$app.

Yii3 разбит на десятки независимых пакетов под неймспейсом Yiisoft\: yiisoft/router, yiisoft/db, yiisoft/validator, yiisoft/view и так далее. Каждый ставится отдельно и может использоваться вне фреймворка. Это меняет саму модель работы: вы собираете приложение из компонентов, а не наследуете готовый монолит.

Yii3 — это не «Yii2 плюс новые фичи». Это другой фреймворк с похожим именем и другими принципами сборки. Планируйте миграцию как переписывание слоёв, а не как обновление зависимости.

Прощай, Yii::$app

Ключевое, что придётся принять: в Yii3 нет глобального сервис-локатора Yii::$app. В Yii2 вы обращались к компонентам через статику отовсюду:

// Yii2 (2.0.x): доступ к компонентам через глобальный объект
$user = Yii::$app->user->identity;
$db = Yii::$app->db;
$request = Yii::$app->request;

В Yii3 зависимости приходят через конструктор, а сборкой занимается PSR-11 DI-контейнер (yiisoft/di). Компоненты запрашиваются явно:

// Yii3: зависимости через конструктор, контейнер собирает их сам
use Yiisoft\Db\Connection\ConnectionInterface;
use Psr\Http\Message\ServerRequestInterface;

final class OrderController
{
    public function __construct(
        private ConnectionInterface $db,
    ) {
    }

    public function view(ServerRequestInterface $request): ResponseInterface
    {
        // работаем с $this->db и $request, глобального Yii::$app нет
    }
}

Точные имена интерфейсов и способ конфигурации контейнера сверяйте с документацией конкретных пакетов — API отдельных компонентов Yii3 всё ещё уточняется от релиза к релизу.

Что поменялось по компонентам

Конкретные минимальные версии PHP смотрите в composer.json каждого пакета — они различаются, и это не одно число на весь фреймворк.

ActiveRecord и работа с БД

ActiveRecord в Yii3 сохранился как концепция, но живёт в отдельном пакете yiisoft/active-record поверх yiisoft/db. Ключевое отличие для мигрирующих: модель больше не тянет соединение из глобального Yii::$app->db — соединение передаётся явно. Это ломает привычный код, где вы вызывали Order::find() без каких-либо настроек. В Yii3 придётся продумать, откуда модель получает ConnectionInterface.

Шаблоны и виджеты

Рендеринг вынесен в yiisoft/view. Виджеты остались, но их набор и API изменились — часть виджетов Yii2 (например, встроенные обёртки над Bootstrap) вынесены в отдельные пакеты или не перенесены. Не рассчитывайте, что вьюхи Yii2 заработают копипастом.

PSR-совместимость — не формальность

Yii2 писался до того, как PSR-стандарты стали индустриальной нормой, и использует собственные абстракции HTTP, логирования, кеша. Yii3 строится на PSR:

• PSR-7 — HTTP-сообщения (Request/Response как неизменяемые объекты);
• PSR-15 — обработчики и middleware вместо фильтров Yii2;
• PSR-11 — контейнер зависимостей;
• PSR-3 — логирование;
• PSR-6/PSR-16 — кеш.

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

Когда что выбирать

Выбор зависит не от «новее — значит лучше», а от состояния вашего проекта.

• Действующий проект на Yii2 в проде. Оставайтесь на Yii2. Ветка 2.0.x получила продлённую поддержку, критичные обновления безопасности выходят. Переписывать рабочую систему ради версии, у которой ещё не стабилизировано ядро целиком, — риск без выгоды.
• Новый проект, команда знает Yii2. Взвесьте: Yii3 даёт современную архитектуру, но экосистема (готовые модули, примеры, ответы на вопросы) вокруг Yii2 всё ещё больше. Если сроки жмут — Yii2 безопаснее.
• Новый проект, важна PSR-совместимость и тестируемость. Yii3 или его отдельные пакеты. DI вместо статики резко упрощает юнит-тесты — компоненты подменяются моками через конструктор.
• Нужен только один компонент. Отдельные пакеты Yii3 (например, yiisoft/validator или yiisoft/db) можно взять в любой проект без всего фреймворка — в этом плюс декомпозиции.

Что ломается при миграции

Автоматического апгрейда с Yii2 на Yii3 нет и не будет — слишком разные основы. Основные точки боли:

• Весь код, завязанный на Yii::$app. Каждое обращение к глобальному объекту нужно переписать на инъекцию зависимостей. В большом проекте это тысячи мест.
• Фильтры и behaviors. Логика доступа, аутентификации, CSRF в Yii2 висела на фильтрах контроллеров. В Yii3 это PSR-15 middleware — другая модель выполнения.
• Конфигурация. Гигантские массивы config/web.php из Yii2 не переносятся напрямую: в Yii3 конфиг размазан по пакетам и определениям контейнера.
• Сторонние расширения. Модули для Yii2 (yii2-*) под Yii3 не работают. Проверьте, есть ли аналоги для критичных зависимостей, прежде чем планировать переход.

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

Если у вас Yii2 в проде — зафиксируйте текущую линию 2.0.x, следите за обновлениями безопасности и не спешите. Если присматриваетесь к Yii3 — не начинайте с попытки перенести весь монолит. Возьмите один пакет Yii3 (например, yiisoft/validator) в отдельную задачу нового проекта и почувствуйте модель работы с DI. Актуальный статус готовности фреймворка целиком смотрите в репозитории yiisoft/app и в разделе документации на официальном сайте — состояние пакетов меняется, и любая цифра версии в статье устаревает быстрее, чем сам текст.