
- MODX 2
- MODX 3
- PHP 7.4
- PHP 8.1


Новая конвенция:
YYYYMMDD_HHMM__slug.phpНапример:
20260810_1530__add_order_status.phpПорядок выполнения — лексикографическая сортировка полного имени, уточнённая зависимостями @depends. Генератор ставит текущее время в часовом поясе label_timezone (по умолчанию Europe/Moscow) и не сдвигает метку в будущее. Если файл с таким именем уже есть, new сообщает об ошибке.
@depends Строка-комментарий в начале файла задаёт миграцию, которая должна выполниться раньше:
<?php
// @depends 20261119_1000__add_statusСтрок может быть несколько. Новые миграции выполняются в топологическом порядке, при равенстве — по имени. Если зависимости нет ни в каталоге, ни в журнале, или зависимости образуют цикл, up, up --dry-run и status --strict печатают строку [ERR] с именами обеих миграций и возвращают код 2 — до того, как что-либо изменено.
Неприменённый файл, чьё содержимое совпадает (checksum) с записью журнала без файла, считается переименованием: up не выполняет его повторно и переносит запись на новое имя. Если содержимое изменилось, добавьте в файл строку // @renamed-from <старое_имя>. Ограничения: несколько неприменённых файлов с одним checksum — ошибка (различайте одинаковые миграции комментарием); старый файл, оставшийся на диске, показывается как лишний.
Команда journal:clean показывает записи без файлов (сухой прогон), а journal:clean --apply удаляет их из журнала. Файлы она не трогает.
Не добавляйте секунды в метку
Формат YYYYMMDD_HHMMSS несовместим с существующими минутными метками при строковой сортировке. Для создания файлов используйте команду new.
Сканер читает только обычные .php-файлы в корне migrations_path. Скрытые файлы, подкаталоги, migrate.php, README.md и файлы других типов игнорируются.
Обычный файл возвращает callable, который принимает поднятый экземпляр MODX. Для MODX 2:
<?php
return function (modX $modx): void {
$prefix = (string)$modx->getOption('table_prefix', null, 'modx_');
$table = $prefix . 'site_orders';
// Сначала проверить текущее состояние, затем привести его к целевому.
echo 'Готово.' . PHP_EOL;
};Для MODX 3 меняется тип аргумента:
<?php
return function (\MODX\Revolution\modX $modx): void {
$prefix = (string)$modx->getOption('table_prefix', null, 'modx_');
// Работа миграции.
};MODX уже загружен раннером. Не запускайте bootstrap ядра повторно и не объявляйте MODX_API_MODE внутри нового файла.
Всё, что миграция печатает, сохраняется в колонке output журнала. Исключение помечает файл как failed; его сообщение вместе с накопленным выводом также попадает в журнал.
Failed-миграция запускается повторно при следующем up, даже если успела частично изменить базу. Поэтому тело должно различать три ситуации:
status, но таблицы или самой колонки нет. Молча пропускать такую ситуацию нельзя: раннер отметит файл применённым, хотя база не достигла нужного состояния.Пример добавления колонки для MODX 2:
return function (modX $modx): void {
$prefix = (string)$modx->getOption('table_prefix', null, 'modx_');
$table = $prefix . 'site_orders';
$column = 'status';
$statement = $modx->query(
'SELECT COUNT(*) FROM information_schema.COLUMNS'
. ' WHERE TABLE_SCHEMA = DATABASE()'
. ' AND TABLE_NAME = ' . $modx->quote($table)
. ' AND COLUMN_NAME = ' . $modx->quote($column)
);
if ($statement !== false && (int)$statement->fetchColumn() > 0) {
echo 'Колонка уже существует.' . PHP_EOL;
return;
}
$sql = 'ALTER TABLE ' . $modx->escape($table)
. ' ADD COLUMN ' . $modx->escape($column)
. " VARCHAR(20) NOT NULL DEFAULT 'new'";
if ($modx->exec($sql) === false) {
throw new RuntimeException('Не выполнился запрос: ' . $sql);
}
};В линии MODX 3 тело то же, но сигнатура начинается с return function (\MODX\Revolution\modX $modx): void.
| Группа | Что означает | Что делать |
|---|---|---|
pending | Записи нет либо предыдущая попытка имеет статус failed. | Проверить dry-run и выполнить up. |
applied | Файл записан как applied или baseline, checksum совпадает. | Ничего. |
drifted | Применённый файл изменился. | Вернуть исходный файл или осознанно принять checksum. |
missing | Запись осталась, файл удалён или переименован. | Вернуть файл с прежним именем. |
outOfOrder | Новый датированный файл оказался раньше уже применённых. | При order = allow выполнится с предупреждением; при strict — задать @depends или включить allow. |
renamed | Неприменённый файл совпал по checksum с записью без файла. | Ничего: up перенесёт запись, повторно файл не выполнится. |
Переименованный файл с тем же содержимым распознаётся как renamed, а не как пара missing и pending.
Таблица создаётся автоматически перед чтением плана. Одна строка содержит:
applied, baseline или failed;Перед SHA-256 раннер удаляет UTF-8 BOM и приводит CRLF/CR к LF. Одна лишь смена окончаний строк между Windows и Linux не создаёт ложный drift.
Запись уникальна по имени файла. Повторная попытка failed-миграции обновляет ту же строку.
up и baseline используют MySQL GET_LOCK(..., 0): если другой процесс уже держит блокировку, команда немедленно отказывает. После завершения выполняется RELEASE_LOCK; при аварийном завершении MySQL освободит lock вместе с соединением.
План пересчитывается после получения блокировки, поэтому процесс, который ждал параллельный запуск, не применит те же файлы повторно.
Если PHP-файл содержит MODX_API_MODE, раннер считает его старой автономной миграцией и запускает отдельным PHP-процессом. Это работает в обеих линиях: legacy-файл сам выполняет bootstrap своей версии MODX. Код возврата должен быть 0; stdout и stderr сохраняются в журнале.
Эта совместимость нужна для существующей истории. Новые миграции должны возвращать callable и использовать уже загруженный $modx.
.sql-файлы;missing из журнала;--ignore-checksum.