foto-portfolio/migrations

Release migrations

One-time scripts that ship inside a release package and are run by the manage client right after it deploys the files — before app/after-update.php, and only once per installation. This is the place for a change that the code cannot make lazily: renaming a field every gallery file already has, deleting a file a release dropped, rewriting data/site.json into a new shape.

Not the same thing as the per-gallery data migration in app/migrate.php, which the operator runs from Admin → Data migration. That one is idempotent housekeeping the application does not depend on; these run automatically as part of the update and must therefore be safe.

Writing one

File name: YYYY-MM-DD-NN-short-description.php. They run in filename order, and the name without .php is the id recorded in data/manage/migrations.json. Renaming a file that already ran makes it run again.

<?php

return function (array $context): void {
    $file = $context['app_root'] . '/data/site.json';
    $data = json_decode((string)file_get_contents($file), true) ?: [];

    if (!array_key_exists('new_field', $data)) {   // idempotent: check first
        $data['new_field'] = null;
        file_put_contents($file, json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE));
    }
};

$context carries app_root, instance, from_version, to_version, backup_dir, run_id and migration_id. There is no pdo — this project has no database.

Rules that matter, because a failed migration stops the run and leaves the new files deployed:

• Idempotent. A migration that fails halfway is not recorded as applied and runs again from the start.
• Not destructive. Normalise and repair; never delete images or S3 objects.
• Use the same locking as the app where you touch gallery files: json_update() from app/storage.php if you bootstrap the application, so a concurrent upload cannot lose its write.

Running them by hand

php manage-client/bin/manage-client.php migrate --dry-run   # what is pending
php manage-client/bin/manage-client.php migrate             # catch up

Also available in the backoffice under Maintenance. Full reference: client-package/docs/07_POST_UPDATE_HOOKS.md.