Миграция с Yii 1.1 на Yii 2: как перенести действующий проект
В Yii 2 сохранились знакомые идеи Yii 1.1, но изменились загрузка классов, работа с моделями, формы и конфигурация. Разберём, как перенести действующее приложение по частям, сохранить данные и переключить трафик с возможностью отката.
Что изменилось между Yii 1.1 и Yii 2
Миграцию удобнее начать с отдельного приложения Yii 2. Разверните его рядом со старым и переносите сквозные сценарии: маршрут, контроллер, форму, запросы к БД и представление. Первый модуль должен дать команде рабочий образец переноса, который можно повторить для остальных частей проекта.
| Область | Yii 1.1 | Yii 2 |
|---|---|---|
| Загрузка классов | Yii::import(), глобальные имена | Пространства имён, use, автозагрузка Composer и Yii |
| Доступ к приложению | Yii::app() | Yii::$app |
| ActiveRecord | CActiveRecord, model(), CDbCriteria | yii\db\ActiveRecord, find(), ActiveQuery |
| Связи моделей | Массив из relations() | Геттеры с hasOne() и hasMany() |
| Формы и таблицы | CActiveForm, CGridView | ActiveForm, GridView, провайдеры данных |
| Ресурсы страницы | CClientScript | AssetBundle и зависимости между наборами ресурсов |
На конец 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
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
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-токены и правила доступа. Для аккаунтов сначала выясните, как старое приложение проверяло пароль. Если формат хеша меняется, можно проверять старый хеш при входе и обновлять его после успешной аутентификации. Делайте это после того, как старое приложение научится читать новый формат, либо отложите обновление до завершения периода отката.
Как переносить проект по этапам
- Зафиксируйте текущее поведение. Соберите используемые маршруты, роли, фоновые задания, интеграции и версии зависимостей. Зафиксируйте ожидаемые результаты входа, записи в БД, отправки формы и обработки ошибок.
- Поднимите Yii 2 на тестовой копии данных. Настройте окружение, журналы и безопасные заглушки для внешних отправок. Начните с модуля, который читает данные и имеет мало зависимостей. Сравните результаты с Yii 1.1 на одном наборе записей.
- Подготовьте совместимые изменения схемы. Пока обе версии используют одну БД, сначала добавляйте нужные поля и таблицы. Заполняйте новые поля отдельной операцией, которую можно безопасно повторить. Переименование и удаление отложите до завершения периода отката.
- Переносите запись вместе с побочными действиями. Проверьте валидацию, транзакции, права, письма и задачи в очереди. На время переключения закрепите обработку каждого фонового задания за одной версией приложения, чтобы избежать дублей.
- Переключайте трафик по готовым модулям. Проверьте маршрутизацию и доступ под разными ролями. После переключения следите за ошибками, авторизацией и очередями. Убедитесь, что 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, с которой оно работает, и запланируйте обновление расширения.