Миграции

Схему своих таблиц меняют миграции Phinx: миграция — это PHP-класс, описывающий изменение. Никаких xPDO-карт пересобирать не нужно.

Писать их руками необязательно: то же самое умеет вкладка «Миграция» в конструкторе — она создаёт файл и модель за вас. Эта вкладка платная; писать файлы руками не ограничено ничем. Эта страница про случай, когда изменение проще описать кодом, — или когда у вас бесплатное издание.

Где они лежат

Файлы	core/App/Database/migrations
Конфиг	core/App/phinx.php
Журнал применённого	pb_app_migrations

Это слой сайта — ваш. Обновление компонента его не трогает.

У этого две стороны

Резолвер ничего не перезаписывает внутри core/App/, поэтому исправление, выпущенное для одного из этих файлов, само не приедет — включая core/App/phinx.php. Если в changelog написано, что файл оттуда поправлен, на уже стоящей установке правку нужно внести руками.

Миграции самого компонента — отдельный набор с отдельным журналом (pb_migrations), и прогоняет их установщик пакета, а не вы. Если у набора есть файлы, которых нет в журнале, на каждой странице менеджера появляется баннер — он следит за PageBlocks, pbShop, репозиторием и вашими миграциями core/App. Установка больше не сообщает об успехе, когда её миграции провалились, но верить стоит баннеру.

Сперва план

status показывает, что ожидает применения, migrate применяет. Читайте план первым и проговаривайте ожидаемый результат: миграция откатывается восстановлением дампа.

# план
php core/components/pageblocks/vendor/bin/phinx status -c core/App/phinx.php

# запись
php core/components/pageblocks/vendor/bin/phinx migrate -c core/App/phinx.php

Никогда не запускайте PHP от root на сервере

PHP сайта работает от пользователя сайта. Миграция, запущенная root'ом, оставляет root-owned файлы кэша, которые сайт потом не может перезаписать, — и менеджер начинает отдавать застывший лексикон. Используйте sudo -u <пользователь_сайта>.

Как написать

<?php

declare(strict_types=1);

use Phinx\Migration\AbstractMigration;

final class CreatePbExampleTable extends AbstractMigration
{
    public function change(): void
    {
        $this->table('pb_example', ['id' => true, 'primary_key' => ['id']])
            ->addColumn('name', 'string', ['limit' => 100, 'null' => false, 'default' => ''])
            ->addColumn('data', 'json', ['null' => false, 'default' => '{}'])
            ->addColumn('menuindex', 'integer', ['signed' => false, 'null' => false, 'default' => 0])
            ->addColumn('published_at', 'datetime', ['null' => true, 'default' => null])
            ->addTimestamps()
            ->addColumn('deleted_at', 'datetime', ['null' => true, 'default' => null])
            ->addIndex(['name'], ['name' => 'idx_name'])
            ->create();
    }
}

Префикс таблицы подставляет Phinx — пишите pb_example, а не modx_pb_example.

Два правила про номер версии

Версию несёт имя файла — 20261011120000_CreatePbExampleTable.php, — и phinx опознаёт миграцию по этой версии, а не по имени и не по содержимому. Отсюда два правила, и нарушение любого из них молчаливое:

• Всегда берите следующий свободный номер. Переиспользованный номер, который уже есть в журнале какой-то установки, заставит phinx пропустить ваш файл — и при этом отчитаться, что применять нечего. Переиспользованная версия — единственное, чего не исправит down().
• Применённую миграцию не правят. Журнал запомнил версию, поэтому правку никто не перезапустит: на той установке схема останется старой навсегда. Пишите новую миграцию.

Таблице, которая будет хранить данные конструктора, нужен тот же хвост, что у встроенных: data, menuindex, published_at, временные метки и deleted_at. Именно он заставляет работать публикацию, сортировку и корзину без лишнего кода.