Download the PHP package lulco/phoenix without Composer

Phoenix

Framework agnostic database migrations for PHP.

Features

• Validation all settings in migration before executing first query
• Multiple migration directories
• Support for views
• Migrate up and down
• Print executed queries (in debug mode -vvv)
• Dry run - executing up or down migrations without real executing queries. Command just prints queries which will be executed in non-dry mode
• Add an autoincrement primary column to an existing table
• Dump command for creating migration from existing database
• Diff command for creating diff migration from two existing databases
• Test command for testing new migration executing migrate, rollback, migrate
• Status command that shows list of executed migrations and list of migrations to execute
• json output format for all commands
• Namespaces in migration classes
• Own migration templates
• Easy integration to any PHP application
• PHPStorm suggestions (works even better with deep-assoc-completion plugin)
• Change collation for all existing tables and columns
• Turn foreign keys check on / off in migration
• Simple autowiring in migrations

Supported adapters

• MySql
• PostgreSQL

Installation

Composer

This library requires PHP 7.4 or later. It works also on PHP 8.0, PHP 8.1 and PHP 8.2. The fastest and recommended way to install Phoenix is to add it to your project using Composer (https://getcomposer.org/).

Usage

Create configuration file

Create file phoenix.php in the root directory of your project. For example:

Read more about configuration here.

REMEMBER: migrations do some structure changes to the database, therefore the database user used for these migrations has to be able to do these changes.

Commands

To run commands, use command runner vendor/bin/phoenix or vendor/lulco/phoenix/bin/phoenix.

Available commands:

• init - initialize phoenix
• create - create migration
• migrate - run migrations
• rollback - rollback migrations
• dump - create migration from existing database
• diff - create migration as diff of two existing database structures
• status - list of migrations already executed and list of migrations to execute
• test - test next migration by executing migrate, rollback, migrate for it
• cleanup - rollback all migrations and delete log table

You can run each command with --help option to get more information about it or read more here

Init command

Command php vendor/bin/phoenix init initializes phoenix and creates database table where executed migrations will be stored in. This command is executed automatically with first run of other commands, so you don't have to run it manually.

Create first migration

Create command php vendor/bin/phoenix create <migration> [<dir>]

This will create PHP class FirstDir\MyFirstMigration in file named {timestamp}_my_first_migration.php where {timestamp} represents actual timestamp in format YmdHis e.g. 20160919082117. This file will be created in migration directory second which is configured as __DIR__ . '/../second_dir' (see configuration example above).

create command creates a skeleton of migration file, which looks like this:

Now you need to implement both methods: up(), which is used when command migrate is executed and down(), which is used when command rollback is executed. In general: if you create table in up() method, you have to drop this table in down() method and vice versa.

Let say you need to execute this query:

You need to implement up() method in your migration class as below:

Or you can use raw sql:

Implementation of correspondent down() method which drops table first_table looks like below:

Now you can run migrate command to execute your first migration.

Migrate command

Migrate command php vendor/bin/phoenix migrate executes all available migrations. In this case you will see output like this:

If you run this command again, there will be no migrations to execute, so the output looks like this:

If you want to rollback changes (e.g. you found out that you forgot add some column or index), you can run rollback command, update migration and then run migrate command again. Keep in mind that the best practice is to run rollback command before updating migration code.

Rollback command

Rollback command php vendor/bin/phoenix rollback rollbacks last executed migration. In this case you will see output like this:

If you run this command again, there will be no migrations to rollback, so the output looks like this:

Dump command

Command php vendor/bin/phoenix dump dumps actual database structure into migration file. If you don't use Phoenix yet and you have some tables in your database, this command helps you to start using Phoenix easier. It also helps you when you want to change mysql to postgres or vice versa

Diff command

Command php vendor/bin/phoenix diff creates migration as diff of two existing database structures. This command can be used when upgrading some system to newer version and you know the structure of both old and new version.

Status command

Run php vendor/bin/phoenix status and show list of migrations already executed and list of migrations to execute. Output is like this:

Cleanup command

Cleanup command php vendor/bin/phoenix cleanup rollbacks all executed migrations and delete log table. After executing this command, the application is in state as before executing init command.

Test command

Test command php vendor/bin/phoenix test executes first next migration, then run rollback and migrate first migration again. This command is shortcut for executing commands:

Output looks like this:

Read more about commands here