docs.modx.pro
mxMigrations
mxMigrations
Расширяемый раннер и генератор миграций для MODX Revolution 2 и 3 — журнал, контрольные суммы, защита порядка и готовые шаблоны.
  • MODX 2
  • MODX 3
  • PHP 7.4
  • PHP 8.1
  1. Компоненты
  2. mxMigrations

mxMigrations ​

Расширяемый раннер и генератор миграций для MODX Revolution 2 и 3. Пакет применяет PHP-миграции в предсказуемом порядке, записывает результат в журнал и останавливает прогон, если уже применённый файл изменился или новая миграция оказалась в прошлом.

У пакета нет страницы в менеджере: миграции запускаются из консоли во время деплоя или вручную разработчиком. После установки достаточно указать, где лежат MODX и каталог миграций. Таблицу с историей запусков пакет создаст сам при первой команде.

Возможности ​

  • Доставка изменений вместе с кодом. Структура таблиц, настройки и элементы MODX меняются файлами под контролем версий, а не ручными действиями после деплоя.
  • Повторяемый деплой. Раннер выполняет только отсутствующие миграции; уже применённые сверяет по SHA-256.
  • Контроль порядка. Файлы сортируются по имени. Новая миграция с меткой раньше уже применённых блокирует рабочий прогон.
  • Защита параллельного запуска. MySQL GET_LOCK не даёт двум процессам одновременно менять одну базу — даже если они запущены с разных серверов.
  • Готовые шаблоны миграций. Пакет умеет создать заготовку для добавления колонки или индекса, создания таблиц и удаления старых объектов MODX.
  • Собственные шаблоны. Проект может добавить свои варианты для повторяющихся задач, а созданная миграция останется самостоятельным файлом.
  • Несколько xPDO-моделей. Генератор связывает изменение таблицы с нужной XML-схемой, а отдельная команда пересобирает модель после успешной миграции.

Требования ​

Пакет выходит двумя линиями. Общее ядро, команды, конфиг и формат журнала у них одинаковые; различаются загрузка MODX, тип класса $modx и шаблон создания таблиц из модели. Мажорная версия пакета означает платформу.

MODX 2MODX 3
Версия пакета1.x2.x
MODX Revolution2.6–2.83.0+
PHP7.4+8.1+
Класс MODXmodXMODX\Revolution\modX
Модель xPDOстарый пакет и классыPSR-4 namespace и FQCN

Обе линии работают с MySQL или MariaDB и запускаются только через PHP CLI.

Shared-хостинг ​

mxMigrations можно использовать на shared-хостинге, если тариф предоставляет:

  • PHP CLI подходящей версии — через SSH, терминал панели или cron;
  • доступ CLI к установленному MODX и его конфигурации;
  • права пользователя MySQL на создание таблицы истории и на операции самих миграций: например ALTER, CREATE, DROP, INSERT или UPDATE;
  • поддержку MySQL GET_LOCK, которой пакет защищает базу от параллельных запусков.

Веб-страницы для запуска нет. Если хостинг не разрешает PHP CLI, использовать пакет штатным способом не получится.

Современные миграции выполняются внутри процесса mxMigrations и не требуют proc_open. Эта функция нужна только для старых автономных PHP-файлов, которые сами загружают MODX. На хостинге с отключённым proc_open новые миграции будут работать, а legacy-файлы — нет.

Для new --apply пользователь CLI должен иметь право записи в каталог миграций. Это ограничение можно обойти без потери возможностей запуска: генерировать файлы локально и загружать их на хостинг вместе с кодом.

Установка ​

Установите transport-пакет через Пакеты → Установить пакет в менеджере MODX:

После установки исполняемый файл находится по адресу:

text
core/components/mxmigrations/bin/mxmigrations.php

Установка сама по себе не меняет сайт: пакет только добавляет CLI и его библиотеки. Таблица истории появится автоматически после создания конфига и первой команды status. Подключение описано в разделе Быстрый старт.

Как устроен запуск ​

text
PHP-конфиг проекта
       ↓
каталог миграций → план: pending / applied / drifted / missing / outOfOrder
       ↓
MySQL-блокировка → последовательное выполнение → журнал проекта

Обычный безопасный цикл деплоя:

  1. status --strict проверяет состояние и возвращает ненулевой код, если есть неприменённые миграции или нарушения.
  2. up --dry-run показывает очередь без выполнения и без записи в журнал.
  3. up захватывает блокировку и применяет файлы по одному.
  4. Следующий status --strict подтверждает чистое состояние.

Раннер не откатывает миграции

В MySQL многие DDL-операции не транзакционны, а удалённые данные автоматически не восстановить. Для обратного изменения создавайте новую миграцию и делайте резервную копию перед опасными операциями.

Что читать дальше ​