Миграция (PRO)

Создать таблицу и получить к ней миграцию и модель — прямо из менеджера, не открывая редактор.

PageBlocks → Конструктор → Миграция.

Только для sudo

Вкладка пишет файлы в core/App/ и запускает миграции по живой базе, поэтому закрыта от всех, кроме администратора. Контент-менеджеру здесь делать нечего.

Что получается

Одна строка превращается в три вещи:

1. файл миграции Phinx в core/App/Database/migrations/;
2. после её выполнения — core/App/Models/Base<Модель>.php, собранный по настоящим колонкам таблицы;
3. core/App/Models/<Модель>.php — только если его ещё нет.

Разделение принципиальное: базовый класс перегенерируется при каждом прогоне, дочерний пишется один раз и больше не трогается. Ваши методы, связи и касты живут в дочернем.

Базовую модель править нельзя

Она молча перезапишется при следующей миграции по этой таблице.

Список

Колонка	Что показывает
Название	Человеческое имя, видно в списке
Таблица, Модель	К чему относится. Пустая модель — «только миграция»
Тип	Что делает миграция
Статус	Ожидает, Выполнена, Откатана или Ошибка
Выполнена	Когда применили

Создание

Настройка	Что делает
Название	Для списка. Обязательное
Имя таблицы	Без префикса, строчные и подчёркивание. Обязательное
Имя модели	Подставляется само из имени таблицы. Пусто — модель не генерируется
Тип	По умолчанию «создать таблицу»
Поля конструктора	Добавит data, menuindex, published_at и прочий хвост
Временные метки	created_at и updated_at
Мягкое удаление	deleted_at

Все три галочки по умолчанию включены: созданная здесь таблица сразу готова к публикации, сортировке, корзине и полям конструктора.

Десять типов: создать и удалить таблицу, добавить, изменить, удалить и переименовать колонку, добавить и удалить индекс, добавить и удалить внешний ключ.

Колонки описываются в дочернем гриде — тип, длина, точность, nullable, unsigned, значение по умолчанию, комментарий, after и индекс с его видом (index, unique, fulltext). Внешние ключи — отдельный грид, с on_delete и on_update.

Выполнение и откат

Выполнить пишет файл миграции, прогоняет Phinx по слою сайта и затем генерирует модель. Статус становится «Выполнена».

Откат разрешён только для выполненной миграции — на всё остальное ответ 405. Лог выполнения сохраняется и открывается кнопкой просмотра, в том числе у упавшей миграции: это первое место, куда смотреть, если не получилось.

Откат отменяет изменение, а не возвращает данные

Откат «удалить колонку» вернёт колонку, но не то, что в ней лежало. Перед разрушающей миграцией на боевом сайте делайте дамп — компонент его не делает.

Текущая форма таблицы берётся не из схемы базы, а пересчитывается по всем выполненным миграциям этой таблицы. Именно поэтому add_column знает, что у таблицы уже есть.

У удалённой таблицы файлы моделей остаются

drop_table намеренно не трогает core/App/Models/. Убрать таблицу — решение о схеме, а удалять вашу модель вместе со всем, что вы в ней написали, конструктор не должен.

Когда две миграции сталкиваются

Две строки «добавить колонку в pb_cargo» захотели бы одно имя класса. Имена разводятся по существующим файлам, поэтому вторая миграция по той же таблице не затирает первую.

Баннер неприменённых миграций

Файлы миграций могут лежать на диске, так и не дойдя до базы. В этом случае компонент выводит баннер на каждой своей странице в менеджере — чтобы недоделанная установка перестала выглядеть успешной.

Сравнивает класс Database/PendingMigrations: файлы миграций Phinx на диске против строк в журнальных таблицах Phinx. Проверяются четыре независимых набора.

Набор	Конфиг Phinx	Журнальная таблица	Важность
PageBlocks	core/components/pageblocks/src/phinx.php	pb_migrations	красный (ошибка)
pbShop	core/components/pbshop/src/phinx.php	pb_shop_migrations	красный (ошибка)
Repository	core/components/repository/src/phinx.php	repository_migrations	красный (ошибка)
Собственный core/App сайта	core/App/phinx.php	pb_app_migrations	жёлтый (сообщение)

Набор, у которого нет каталога миграций, пропускается молча — это всего лишь значит, что спутник не установлен.

Два состояния различаются: журнальной таблицы нет вовсе — миграции не запускали ни разу; и журнальная таблица есть, но часть миграций не применена.

Баннер перечисляет первые пять ожидающих версий, дальше +N на остаток, и называет точную команду, которую надо выполнить:

php core/components/pageblocks/vendor/bin/phinx migrate --configuration=<config> --environment=production

Почему собственные миграции сайта жёлтые, а не красные

Миграции пакетов должен был применить установщик пакета, поэтому ожидающая миграция означает, что установка не удалась, — это ошибка. Собственные миграции core/App запускают руками или из CI, поэтому ожидающая миграция здесь — нормальное рабочее состояние, а не неисправность.

Баннер — это настоящая гарантия, а не приятное дополнение

xPDO игнорирует возвращаемое значение резолвера пакета, поэтому установщик пакетов MODX может отчитаться об успешной установке даже тогда, когда миграции внутри неё упали. Узнать об этом можно только из баннера.

Куда это пишет

Только в слой сайта, никогда в компонент. Отсюда и безопасность: обновление компонента не перезапишет сгенерированное, а сгенерированное не уедет в чужую установку.

Написать миграцию руками — Миграции; что умеет сгенерированная модель — Модели.