mxMigrations для MODX: база меняется — порядок остаётся

В MODX нет штатного механизма проектных миграций.
Изменения таблиц, системных настроек, элементов и xPDO-моделей часто выполняются вручную, разрозненными PHP- и SQL-скриптами или через UI других пакетов (MIGXdb). В результате непонятно, какие изменения уже запускались на конкретном сервере, в каком порядке их выполнять при деплое и соответствует ли xPDO-модель фактической структуре базы.

mxMigrations решает эту проблему единым журналом миграций.
Каждое изменение хранится в коде, получает контрольную сумму и одинаково применяется на dev, stage и production. Пакет доступен для MODX Revolution 2 и MODX Revolution 3.

Скриншотов не будет, потому что у пакета нет UI

Требования

Для линии 1.x — MODX Revolution 2.6–2.8 и PHP 7.4 или новее.
Для линии 2.x — MODX Revolution 3.0–3.2 и PHP 8.1 или новее.
Нужен доступ к PHP CLI: пакет предназначен для разработчиков и запускается из консоли или сценария деплоя.
Проект использует MySQL-совместимую базу данных.
Миграции и конфигурация проекта должны храниться вместе с исходным кодом.
Для перестроения xPDO-моделей PHP-процессу нужны права записи в настроенные каталоги модели.

Ограничения

У пакета нет интерфейса в менеджере MODX — все команды выполняются через CLI.
mxMigrations не создаёт автоматический откат для произвольной миграции. Если изменение требует возврата, разработчик оформляет обратное действие
отдельной миграцией.
Пакет контролирует порядок и состояние запуска, но не может определить бизнес-корректность написанного разработчиком PHP-кода.
Режим dry-run показывает план и проверяет возможность запуска, но не имитирует результат произвольного кода миграции.
Для MODX 2 и MODX 3 используются отдельные transport-пакеты и линии версий, поскольку платформы работают с разными классами и форматами моделей.
Текущие версии имеют статус beta.

Что умеет mxMigrations

Находит миграции проекта и применяет их в порядке имени файла.
Ведёт журнал со статусами applied, baseline и failed.
Сохраняет SHA-256 checksum каждого применённого файла.
Обнаруживает изменение уже выполненной миграции.
Останавливается, если новая миграция появилась раньше уже применённых изменений.
Защищает базу от одновременного запуска двух процессов через MySQL-блокировку.
Показывает ожидающие изменения без их выполнения.
Поддерживает подключение существующего проекта через baseline.
Генерирует миграции по встроенным и проектным шаблонам.
Синхронизирует изменения миграций с XML-схемами и xPDO-моделями.
Работает с несколькими моделями в одном проекте.
Сохраняет проектные изменения сторонней модели отдельно и повторно накладывает их после обновления пакета.
Подходит для локального запуска, cron, скриптов деплоя и CI/CD.

Готовые шаблоны миграций

Создание пустой миграции для собственной логики.
Добавление, изменение и удаление колонок.
Добавление и удаление индексов.
Создание таблиц из xPDO-модели.
Удаление таблиц.
Удаление системных настроек MODX.
Удаление элементов MODX.

Рецепт используется только во время генерации. Получившийся PHP-файл автономен и не зависит от будущих обновлений mxMigrations или
проектного генератора.

Сценарий 1. Добавить колонку

Разработчик выбирает рецепт, таблицу, имя колонки и SQL-тип.
Генератор создаёт готовый файл миграции.
Если связанная таблица найдена в настроенной XML-схеме, изменение добавляется и в схему.
Без параметра apply команда только покажет будущий файл и ничего не запишет.

php core/components/mxmigrations/bin/mxmigrations.php --config=core/config/mxmigrations.php new add_status --recipe=add-column
  --table=site_orders --column=status --type="VARCHAR(20) NOT NULL" --apply

Сценарий 2. Проверить миграции перед деплоем

Команда status показывает применённые, ожидающие, изменённые и неудачные миграции.
Параметр strict возвращает отдельный код ошибки, если состояние проекта требует вмешательства.
Такую проверку можно добавить в CI/CD и остановить деплой до изменения базы.

php core/components/mxmigrations/bin/mxmigrations.php --config=core/config/mxmigrations.php status --strict

Сценарий 3. Посмотреть план без изменения базы

Dry-run показывает, какие миграции будут запущены.
Журнал и структура базы при этом не изменяются.
После проверки тот же набор файлов применяется обычной командой up.

php core/components/mxmigrations/bin/mxmigrations.php --config=core/config/mxmigrations.php up --dry-run

php core/components/mxmigrations/bin/mxmigrations.php --config=core/config/mxmigrations.php up

Сценарий 4. Подключить существующий проект

На работающем сайте часть изменений базы уже может быть выполнена вручную.
Нужно написать под эти изменения миграции и выполнить команду baseline
Команда baseline отмечает существующие миграции как принятые без повторного выполнения их кода.
После этого все новые миграции запускаются и контролируются в обычном порядке.

php core/components/mxmigrations/bin/mxmigrations.php --config=core/config/mxmigrations.php baseline --by=developer

Сценарий 5. Перестроить xPDO-модель

Сначала разработчик создаёт и применяет миграцию.
Затем model:build показывает, какие файлы модели будут обновлены.
Фактическая запись выполняется только с параметром apply.
Если связанные миграции ещё не применены, mxMigrations откажется перестраивать модель.

php core/components/mxmigrations/bin/mxmigrations.php --config=core/config/mxmigrations.php model:build

php core/components/mxmigrations/bin/mxmigrations.php --config=core/config/mxmigrations.php model:build --apply

Сценарий 6. Расширить модель стороннего пакета

Для сторонней схемы включается режим overlay.
Проектные изменения сохраняются отдельно в каталоге миграций.
Исходный пакет можно обновлять без потери проектной дельты.
После обновления mxMigrations повторно накладывает сохранённые изменения на свежую схему и перестраивает модель.
Так можно сопровождать дополнительные поля и индексы в моделях miniShop2, miniShop3 и других компонентов.

Сценарий 7. Создать собственный шаблон миграции

Проект может зарегистрировать собственные генераторы через MigrationRecipeProviderInterface.
Так оформляются повторяющиеся операции: создание настроек, изменение элементов, заполнение справочников или перенос данных.
PHP-шаблон миграции можно вынести в отдельный файл и обработать через FileTemplate.
Сгенерированная миграция останется автономной и не потребует наличия рецепта при запуске на другом сервере.

Одинаковый процесс для MODX 2 и MODX 3

Линия 1.x работает с MODX Revolution 2 и классическими xPDO-моделями.
Линия 2.x работает с MODX Revolution 3, namespaces, PSR-4 и моделями xPDO 3.
Конфигурация, журнал, основные команды и архитектура рецептов в обеих линиях одинаковы.
Обе версии пакета доступны в одной карточке modstore.

Документация