PHPTime

Миграция с Yii 1.1 на Yii 2: как перенести действующий проект

В Yii 2 сохранились знакомые идеи Yii 1.1, но изменились загрузка классов, работа с моделями, формы и конфигурация. Разберём, как перенести действующее приложение по частям, сохранить данные и переключить трафик с возможностью отката.

Что изменилось между Yii 1.1 и Yii 2

Миграцию удобнее начать с отдельного приложения Yii 2. Разверните его рядом со старым и переносите сквозные сценарии: маршрут, контроллер, форму, запросы к БД и представление. Первый модуль должен дать команде рабочий образец переноса, который можно повторить для остальных частей проекта.

ОбластьYii 1.1Yii 2
Загрузка классовYii::import(), глобальные именаПространства имён, use, автозагрузка Composer и Yii
Доступ к приложениюYii::app()Yii::$app
ActiveRecordCActiveRecord, model(), CDbCriteriayii\db\ActiveRecord, find(), ActiveQuery
Связи моделейМассив из relations()Геттеры с hasOne() и hasMany()
Формы и таблицыCActiveForm, CGridViewActiveForm, GridView, провайдеры данных
Ресурсы страницыCClientScriptAssetBundle и зависимости между наборами ресурсов

На конец 2026 года для переноса можно рассматривать поддерживаемые ветки PHP 8.3, 8.4 и 8.5. Целевую версию выбирайте по совместимости конкретных версий Yii 2, расширений Composer и модулей PHP на сервере. Прогоняйте тесты на той же версии PHP, на которой будет работать приложение. После установки зависимостей из файла блокировки выполните composer check-platform-reqs в целевом окружении.

Пространства имён и строгая типизация

В базовом шаблоне Yii 2 класс app\models\Order обычно находится в models/Order.php относительно корня приложения. Разложите классы по пространствам имён и замените вызовы Yii::import() на объявления use. Для самостоятельных пакетов настройте PSR-4 в Composer. Проверьте совпадение регистра имён классов и файлов: ошибка может проявиться только при запуске на Linux.

Добавляйте declare(strict_types=1) в новые файлы и задавайте типы в собственных сервисах и методах. При переопределении методов Yii сверяйте сигнатуры с родительским классом. Строгий режим не проверяет содержимое массива из HTTP-запроса. Принимайте входные данные через форму, валидируйте их и только затем передавайте в типизированный сервис.

ActiveRecord: запросы, связи и сохранение

В Yii 2 типовой вызов Order::model()->findByPk($id) превращается в Order::findOne($id). Для сложных выборок используйте find() и методы ActiveQuery. При переносе defaultScope() решите, где должно применяться каждое условие. Например, фильтр по организации нужен во всех пользовательских выборках, а условие «только открытые заказы» можно оставить именованным методом запроса.

PHP
<?php

declare(strict_types=1);

namespace app\models;

use yii\db\ActiveQuery;
use yii\db\ActiveRecord;

final class Order extends ActiveRecord
{
    public static function tableName(): string
    {
        return '{{%orders}}';
    }

    public function getCustomer(): ActiveQuery
    {
        // Ключ таблицы клиентов связан с полем заказа.
        return $this->hasOne(Customer::class, ['id' => 'customer_id']);
    }
}

В примере Customer — перенесённая модель из того же пространства имён. Для списка заказов можно использовать Order::find()->where(['status' => 'paid'])->with('customer')->all(). with() подгружает клиентов для всей выборки и избавляет от отдельных запросов при обращении к $order->customer в цикле. Если нужно фильтровать или сортировать по полям клиента в основном запросе, используйте joinWith() и проверьте, как соединение влияет на число строк и пагинацию.

Переносите rules(), сценарии и обработчики сохранения отдельно от запросов. load() заполняет атрибуты, безопасные для текущего сценария, а save() по умолчанию запускает валидацию. Проверьте ветку, где save() возвращает false, и вывод ошибок модели. Для операций над несколькими связанными записями сохраните границы транзакции и убедитесь, что ошибка в одной записи откатывает остальные изменения.

Формы, виджеты и представления

В Yii 2 форма обычно начинается с ActiveForm::begin() и заканчивается ActiveForm::end(). Поля создаются через $form->field(). Ниже представление получает $model с атрибутом email. Контроллер должен обработать отправку через $model->load(\Yii::$app->request->post()) и проверить модель перед записью.

PHP
<?php
use yii\helpers\Html;
use yii\widgets\ActiveForm;

// Атрибут email должен быть доступен в текущем сценарии модели.
$form = ActiveForm::begin();
echo $form->field($model, 'email')->input('email');
echo Html::submitButton('Сохранить');
ActiveForm::end();

При переносе страницы со списком используйте GridView::widget() вместе с ActiveDataProvider. Если в старой таблице были фильтры, перенесите их в отдельную поисковую модель. Проверьте сортировку, номера страниц и параметры запроса: расхождения заметят пользователи, которые сохранили отфильтрованные страницы в закладках.

Подключение JS и CSS перенесите в AssetBundle. Явно укажите зависимости между наборами, чтобы скрипты загружались в нужном порядке. Проверьте, какие поля старого шаблона выводились как HTML. Произвольные текстовые значения выводите через Html::encode(), а разрешённую пользовательскую разметку очищайте перед выводом.

Конфигурация, маршруты и вход в приложение

В Yii 2 веб-приложение и консоль используют разные точки входа и могут иметь разные конфигурации. Общие настройки БД и параметры приложения вынесите в общий файл. Проверьте компоненты db, cache, mailer, user и urlManager. У консольных команд проверьте подключение к той же БД и доступ к нужным переменным окружения. Секреты передавайте через окружение, чтобы они не попадали в репозиторий.

Направьте веб-сервер в публичный каталог web/. Закрепите правила urlManager по списку действующих адресов и проверьте генерацию ссылок из приложения. Для публичных страниц важны прежние адреса, коды ответов и параметры запроса. Для API и входящих вебхуков дополнительно проверьте HTTP-методы, формат ответа и способ аутентификации.

Если Yii 1.1 и Yii 2 работают параллельно, проверьте имена и область действия cookie, хранение сессий, CSRF-токены и правила доступа. Для аккаунтов сначала выясните, как старое приложение проверяло пароль. Если формат хеша меняется, можно проверять старый хеш при входе и обновлять его после успешной аутентификации. Делайте это после того, как старое приложение научится читать новый формат, либо отложите обновление до завершения периода отката.

Как переносить проект по этапам

  1. Зафиксируйте текущее поведение. Соберите используемые маршруты, роли, фоновые задания, интеграции и версии зависимостей. Зафиксируйте ожидаемые результаты входа, записи в БД, отправки формы и обработки ошибок.
  2. Поднимите Yii 2 на тестовой копии данных. Настройте окружение, журналы и безопасные заглушки для внешних отправок. Начните с модуля, который читает данные и имеет мало зависимостей. Сравните результаты с Yii 1.1 на одном наборе записей.
  3. Подготовьте совместимые изменения схемы. Пока обе версии используют одну БД, сначала добавляйте нужные поля и таблицы. Заполняйте новые поля отдельной операцией, которую можно безопасно повторить. Переименование и удаление отложите до завершения периода отката.
  4. Переносите запись вместе с побочными действиями. Проверьте валидацию, транзакции, права, письма и задачи в очереди. На время переключения закрепите обработку каждого фонового задания за одной версией приложения, чтобы избежать дублей.
  5. Переключайте трафик по готовым модулям. Проверьте маршрутизацию и доступ под разными ролями. После переключения следите за ошибками, авторизацией и очередями. Убедитесь, что Yii 1.1 сможет прочитать данные, записанные Yii 2, если маршруты придётся вернуть.

Чек-лист перед переключением на Yii 2

  • Версия PHP и расширения совпадают с боевым окружением, зависимости устанавливаются из composer.lock.
  • Страницы, формы, API и консольные команды прошли проверку на копии данных. В проверку включены ошибки валидации и доступ под разными ролями.
  • Основные адреса сохранены, ссылки генерируются правильно, правила доступа и CSRF-защита работают.
  • Схема БД совместима с обеими версиями приложения. Восстановление резервной копии проверено.
  • Проверены вход, повторный вход, выход и восстановление пароля. Обработчики очередей и расписаний назначены одной версии приложения.
  • Понятно, как вернуть маршруты и фоновые задания на Yii 1.1 и что произойдёт с данными, записанными после переключения.

Частые вопросы

Можно ли перенести Yii 1.1 на Yii 2 простым обновлением Composer?

Нет. Composer установит зависимости нового приложения, а модели, контроллеры, виджеты и конфигурацию нужно адаптировать под API Yii 2.

Нужно ли создавать новую базу данных для Yii 2?

Yii 2 может работать с прежней схемой. Укажите имена таблиц и при необходимости первичные ключи в моделях, затем проверьте связи и запросы. Для параллельной работы сохраняйте совместимость изменений схемы с Yii 1.1.

Можно ли сразу перейти на PHP 8.5?

Да, если выбранные версии Yii 2 и зависимостей совместимы с PHP 8.5, а приложение проходит тесты на этой версии. Если блокирует отдельное расширение, перенесите приложение на поддерживаемую ветку PHP, с которой оно работает, и запланируйте обновление расширения.

Справка по теме

Ещё в разделе «Yii»

Расширения Yii 2: где искать и как устанавливать через Composer

Где искать расширения Yii 2, как проверить совместимость с PHP 8.3–8.5 и выбрать пакет. Установка через Composer, настройка и примеры популярных расширений.

7 мин

Yii 2 сегодня: установка, PHP 8.x и выбор фреймворка

Как установить Yii 2 на PHP 8.3–8.5, выбрать шаблон Basic или Advanced, проверить зависимости и решить, когда перейти на Yii 3 или Laravel.

6 мин

Как настроить автодополнение scope-методов ActiveRecord в Yii2

Настройте автодополнение scope-методов Yii2 в PhpStorm: создайте класс ActiveQuery, типизируйте find() и используйте фильтры в связях hasOne и hasMany.

7 мин

Yii 1.1.14 и хеширование паролей в PHP: от CPasswordHelper к Yii 2

Что Yii 1.1.14 изменил в работе с паролями и кешем. Как проверять bcrypt-хеши, мигрировать на password_hash или Yii 2 и настроить отдельный кеш в Redis.

7 мин