Skip to content

Migrations

The plugin has two distinct migration mechanisms that both run on every deployment:

Migrator Purpose
BaseMigrator Versioned schema changes (run once per version)
RecurringTasksMigrator Idempotent tasks that run on every deployment

Both are registered in BasePluginSetup and triggered by the barberklingen/migrations/completed action.

How the Migrator trait works

Barberklingen\BasePlugin\Migrations\Migrator (trait) drives the versioned flow:

  1. Reads the current DB version from wp_options (key: db_version_{name}).
  2. Loops through all Migration objects returned by get_migrations().
  3. Runs install() on each migration whose version is greater than the stored version.
  4. Updates the stored version after each successful migration.

The version is compared with version_compare(), so standard semver ordering applies.

// wp_options key for BaseMigrator: db_version_base-plugin
// wp_options key for a custom migrator named "my-shop": db_version_my-shop

Migration interface

interface Migration {
    public function install(): void;
    public function get_version(): string;
}

Recurring tasks return an empty string from get_version() because they bypass the version check entirely.

Creating a custom migrator

use Barberklingen\BasePlugin\Migrations\Migrator;

class MyPluginMigrator {
    use Migrator;

    protected function get_name(): string {
        return 'my-plugin'; // used as the wp_options key
    }

    public function get_migrations(): array {
        return [
            new V1_0_0(),
            new V2_0_0(),
        ];
    }
}

// Boot it — fires on barberklingen/migrations/completed at priority 20
add_action('plugins_loaded', fn() => MyPluginMigrator::get_instance());

Use a higher get_migrator_priority() return value if your migrations depend on BaseMigrator having already run (base runs at priority 10).

Sub-pages