Download the PHP package enlivenapp/migrations without Composer

Migrations Library

I noticed folks downloading some of these packages. I'm super grateful, Thank You! I would like to let folks know until this notice disappears I'm doing a lot of breaking changes without worrying about them. Once versions are up around 0.5.x things should settle down.

Migrations is a single-package standalone PHP library for database migrations and seeds with minimal requirements. It tracks changes applied to your database and runs new ones in order. No framework required, just a database connection. MySQL and MariaDB supported currently. Optional CLI support is available through the flightphp/runway CLI.

Requirements

• PHP >= 8.1 with ext-pdo and ext-pdo_mysql
• MySQL or MariaDB
• composer/semver ^3.0

Recommended:

• flightphp/runway
• enlivenapp/flight-school

Data Saver

The data saver automatically attempts to protect every migration against partial failure. Non-destructive changes are repaired by running the opposite operation. For destructive changes, tables are temporarily copied before the operation. If the migration fails, everything is reverted to the pre-migration state.

Quick notes:

• to use command line functionality, you'll need to require flightphp/runway, otherwise you'll only have programatic access.
• versions differences are derived from a caller-provided migrations.versions map (which takes precedence) merged with composer/installed.json, compared against the seeds table in the database. Non-composer packages (core, local plugins) seed once using 0.0.0 as the version when nothing else resolves.

If you're familiar with Phinx/CakePHP you'll find the fluent chain very familiar. Codeingiter and Sympony users will find these fairly intuitive. Laravel... o_0 :D

PRs and contributions are welcome.

Supported Frameworks

• FlightPHP

Install

Full functionality:

Default Paths/Settings

By default Migrations look in:

and seeds expects a return array from:

Configuration

Migrations resolves its own database connection and does not continue looking after it finds one. You never pass it a PDO. The cascade is:

1. FlightPHP (only if loaded): Flight::get('db') is checked for a PDO. If found, Flight::get('migrations') is used as the config override and no file is read.
2. File: app/config/migrations.php — flat database credentials plus an optional migrations key of overrides. This is the only config file.
3. Nothing found → Migrations throws.

Every key except paths and seeds.paths merges recursively, so you only need to set what you want to change. Those two lists are governed by path_mode (below).

app/config/migrations.php:

path_mode — controls how the override paths / seeds.paths lists are combined with the defaults. It applies to both lists using one setting:

If the override does not include paths or seeds.paths, the defaults are kept.

Important Notes:

• If a database connection is not found, Migrations will throw an exception.

Additional configuration

Two optional keys let you seed and track code that isn't a composer package (for example, a host app's own migrations under app/Database/Migrations). Both live under the migrations key in your config.

versions — a map of moduleName => version. When a package has no entry in composer/installed.json (core and non-composer code aren't composer packages), this is the version used for seeding. If neither this map nor installed.json resolves a version, the package's install seed block runs once with 0.0.0 as the version.

module_names — maps a migration path pattern to a module name. By default a directory like app/Database/Migrations is derived as the basename Migrations. Use this to give it a real identity (e.g. pubvana/pubvana) so its seeds/migrations are tracked under that name.

Setting Up Migrations

Migrations resolves the database connection itself, so you never pass it a PDO.

Quick Migration file example

Run with runway Run it:

Or run everything:

See below for programatic usage

Reversible migrations

Instead of writing up() and down() separately, you can write change(). The library records what change() did and reverses it automatically on rollback.

Only forward operations are auto-reversible: create table, add columns, rename table, rename column. If your migration drops or modifies things, use up() and down().

CLI commands

--dry-run shows what would happen without applying any changes. The SQL for create, drop, and alter is captured without running, and seeds are skipped. Nothing is written to the database.

Seeds

Seeds are optional. If you have need of seeding the database use the process below:

Every row gets created_at and updated_at set to the current time on insert, so the target table needs those two columns.

Non-composer packages (core, local plugins): packages without a resolvable version in composer/installed.json (and no migrations.versions entry) run their install block once with 0.0.0 as the version, so the default data is inserted and the row is tracked. Seeds use INSERT IGNORE, so rows that already exist are silently skipped rather than erroring, so running seeds twice is safe.

Running Migrations Programatically

If your brain hurts after reading this like mine did writing it, please consider Flight School Plugin Manager it manages all of this automatically for FlightPHP plugins.

Documentation

• Writing Migrations
• Writing Seeds
• API Reference
• Troubleshooting

License

MIT. See LICENSE.