Конфигурация проекта

mxMigrations читает обычный PHP-файл, который возвращает массив. В нём нужно указать имя проекта и каталог миграций. Остальные параметры имеют безопасные значения по умолчанию.

Минимальный конфиг

<?php

return [
    'id' => 'site',
    'modx_root' => dirname(__DIR__, 2),
    'migrations_path' => dirname(__DIR__) . '/migrations',
];

Относительные пути считаются от каталога, где лежит конфиг. Абсолютные пути используются без изменения.

Параметры

Ключ	Обязателен	Значение по умолчанию	Назначение
id	да	—	Идентификатор сайта. По нему пакет называет таблицу истории и блокировку.
modx_root	нет	каталог конфига	Корень установки MODX.
migrations_path	да	—	Каталог PHP-миграций проекта.
models	нет	пустой список	XML-схемы и каталоги моделей, которыми управляет проект.
autoload	нет	пустой список	PHP-файлы, которые подключаются до загрузки собственных шаблонов. Обычно Composer autoload.php.
recipe_providers	нет	пустой список	PHP-классы, которые добавляют собственные шаблоны миграций; обычно не требуется.

id может содержать латинские буквы, цифры и подчёркивание, но должен начинаться с буквы.

Несколько моделей

Один сайт может использовать собственную модель и модели установленных пакетов:

'models' => [
    'site' => [
        'schema_path' => dirname(__DIR__) . '/components/site/model/schema/site.mysql.schema.xml',
        'model_path' => dirname(__DIR__) . '/components/site/model/site',
    ],
    'minishop2' => [
        'schema_path' => dirname(__DIR__) . '/components/minishop2/model/schema/minishop2.mysql.schema.xml',
        'model_path' => dirname(__DIR__) . '/components/minishop2/model/minishop2',
        'overlay' => true,
    ],
],

Для MODX 3 типовые каталоги моделей заканчиваются на src/Model, а схемы лежат в schema/. Namespace пакет читает из атрибута package XML-схемы.

overlay => true ставят для стороннего пакета. mxMigrations не правит его XML, а хранит изменения в migrations/.mxmigrations/model-changes.php. При сборке они накладываются на текущую схему пакета, поэтому обновление miniSite не уничтожает описание добавленных проектом полей. Подробный процесс — в разделе XML-схемы и модели.

Корень MODX

Обе линии включают MODX_API_MODE, загружают сервис ошибок и передают поднятый экземпляр MODX в миграцию через аргумент $modx.

• MODX 2: CLI подключает <modx_root>/index.php.
• MODX 3: CLI подключает <modx_root>/config.core.php, ищет Composer autoload в корне сайта либо core/, создаёт MODX\Revolution\modX и инициализирует контекст mgr.

Если конфиг находится в core/config/mxmigrations.php, выражение dirname(__DIR__, 2) поднимается к корню сайта:

'modx_root' => dirname(__DIR__, 2),

При ошибке пути команда сообщит, что не найден index.php для MODX 2 либо config.core.php для MODX 3.

Таблица истории

Пакет создаёт таблицу автоматически при первом status, up или baseline. По умолчанию имя строится из системного table_prefix MODX и id. Например, id => 'site' при префиксе modx_ создаст modx_site_migrations.

Блокировка

Пакет автоматически строит имя MySQL-блокировки из имени базы и id сайта. Настраивать его отдельно не нужно. Если миграции уже запущены другим процессом, второй запуск сразу остановится и не будет менять базу параллельно.

Собственные шаблоны

Для обычной работы и готовых шаблонов пакета параметры autoload и recipe_providers не нужны.

Они используются, только если разработчик написал собственный шаблон отдельным PHP-классом:

• autoload перечисляет PHP-файлы, которые нужно подключить через require_once перед созданием провайдеров;
• recipe_providers перечисляет классы, которые передают эти шаблоны mxMigrations.

С Composer достаточно подключить его автозагрузчик:

'autoload' => [__DIR__ . '/../vendor/autoload.php'],
'recipe_providers' => [Site\Migrations\RecipeProvider::class],

Без Composer можно подключить обычный PHP-файл:

// config/migrations-autoload.php
require_once __DIR__ . '/../src/Migrations/SeedWarehouseRecipe.php';
require_once __DIR__ . '/../src/Migrations/RecipeProvider.php';

'autoload' => [__DIR__ . '/migrations-autoload.php'],
'recipe_providers' => [Site\Migrations\RecipeProvider::class],

Если файл или класс не найден, команда остановится до работы с миграциями. Полный пример — в разделе Собственные шаблоны.

Где хранить конфиг

Конфиг должен быть частью исходного кода проекта и не содержать секретов. В нём нет учётных данных базы: MODX берёт их из своего штатного config.inc.php.

Абсолютные пути, различающиеся между средами, лучше вычислять от __DIR__ или передавать через окружение внутри самого PHP-конфига.