activecollab / databasemigrations
Database schema migrations
Installs: 13 753
Dependents: 1
Suggesters: 0
Security: 0
Stars: 0
Watchers: 2
Forks: 1
Open Issues: 1
Requires
- php: >=8.0
- activecollab/databaseconnection: ^5.0
- activecollab/filesystem: ^0.10
- doctrine/inflector: ^2.0
- psr/log: ^1.0
Requires (Dev)
- ext-mysqli: *
- friendsofphp/php-cs-fixer: ^2.0
- monolog/monolog: ^1.0
- phpunit/phpunit: ^9.0
- symfony/console: ^4.0
Suggests
- symfony/console: Quickly implement commands that work with migrations via CLI
README
Migrations
To write a migration, create a class that is discoverable by Finder that you are using, and extend Migration
class:
<?php namespace Acme\App\Migrations; use ActiveCollab\DatabaseMigrations\Migration\Migration; class AddUserRolesTable extends Migration { /** * {@inheritdoc} */ public function up() { } }
If you don't like how Migration
class is structured, you can write your migrations any way you want, as long as you implement MigrationInterface
:
<?php namespace Acme\App\Migrations; use ActiveCollab\DatabaseMigrations\Migration\MigrationInterface; class AddUserRolesTable implements MigrationInterface { … }
Migrations that extend Migration
class get two important properties injected via constructor:
connection
- aActiveCollab\DatabaseConnection\ConnectionInterface
instance with valid connection to the database, andlog
- a PSR-3LoggerInterface
instance.
<?php namespace Acme\App\Migrations; use ActiveCollab\DatabaseMigrations\Migration\Migration; class AddUserRolesTable extends Migration { /** * {@inheritdoc} */ public function up() { if (!in_array('user_roles', $this->connection->getTableNames()) { $this->logger->debug('{table} not found in the database', ['table' => 'user_roles']); $thos->connection->execute('CREATE TABLE STATEMENT'); $this->logger->debug('{table} created', ['table' => 'user_roles']); } } }
Finders
Migration classes are "discovered" using objects that implement FinderInterface
interface. All that we expect from finders is that they return an array where key is migration class name, and value is path where we can expect to find the class definition. This makes migration library independent on directory and file structure that you decide to use to organize your migrations.
This library currently implements only one Finder - Migrations in Changesets.
Migrations in a Changeset Finder
What we found to work really well for Active Collab project are migrations that are grouped in changesets. A changeset is a directory that has one or more related migrations. Valid format of the changeset directory name is YYYY-MM-DD-what-this-is-all-about
. Here's a couple of valid changeset names:
2016-01-02-add-invoicing-module
2016-03-12-remove-is-trashed-project-field
2016-12-09-fix-users-table-indexes
Timestamp part of the changeset name is used for sorting, and details part is used to make it clear what the changeset is all about.
Command Line
Database Migrations package includes a couple of traits that make implementation of commands that work with migrations easy. These commands are:
- List all migrations and their status (All)
- Run all non-executed migrations (Up)
- Create a new migration file (Create)
In order to use these traits, you need to include them in a regular Symfony Console class, and provide implementation of getMigrations()
method. This method needs to return a valid, configured MigrationsInterface
instance.
Create helper has extra requirements and extension points that lets you configure how migration stubs are created. Please check protected and abstract methods under Override
comment in /src/Command/Create.php
file for details.
To Do
- Add basic field, index and foreign key management helper methods to the base
Migration
implementation