README

A Charcoal service provider my cool feature.

Table of Contents

• Installation
  • Dependencies
• Configuration
• Usage
  • Running the migration
  • Creating new Migrations
  • Injecting Migrations to the migrator
• Development
  • API Documentation
  • Development Dependencies
  • Coding Style
• Credits
• License

Installation

The preferred (and only supported) method is with Composer:

$ composer require locomotivemtl/charcoal-contrib-database-migrator

Dependencies

Required

• PHP 7.2+: PHP 7.3+ is recommended.

PSR

• PSR-7: Common interface for HTTP messages. Fulfilled by Slim.
• PSR-11: Common interface for dependency containers. Fulfilled by Pimple.

Configuration

In your project's config file, require the migrator module like so :

{
    "modules": {
        "charcoal/migrator/migrator": {}
    }
}

Optionally, you can also override some migrator configurations in the project's config file using the database.migrator key :

{
    "database": {
        "migrator": {
            "migrations": {
                "search_paths": [
                    "path/to/some/migrations",
                    "path/to/some/custom/migrations"
                ]
            }
        }
    }
}

Usage

Running the migration

Simply run this command in the console to lunch the migration process

$ vendor/bin/charcoal admin/database/migrate

The CLI UI will guide you step by step.

Creating new Migrations

A migration should always extend AbstractMigration

MigrationYYYYMMDDHHMMSS.stub can be used as a starting point when creating new migrations. Just copy and paste it the package in need of a new migration.

A migration should always be named MigrationYYYYMMDDHHMMSS.php to facilitate readability.

A migration file consist of a PHP class which follows these guidelines :

• Contains the timestamp of the commit this migration is fixing in the class name prefixed with migration
• Have an up and optionally down methods for the migration tool to process the migration when going up in version or down.
• Have a descripion method to briefly document the migration

you can implement the setDependencies method on a migration.

     /**
     * Inject dependencies from a DI Container.
     *
     * @param Container $container A Pimple DI service container.
     * @return void
     */
    protected function setDependencies(Container $container)
    {
        // This method is a stub.
        // Reimplement in children method to inject dependencies in your class from a Pimple container.
    }

You can also use the init() function to process data that is both needed in up and down methods.

Injecting Migrations to the migrator

As long as the migration follows the guidelines described above, it'll be automatically parsed by the migrator. No need to do anything more than that.

Development

To install the development environment:

$ composer install

To run the scripts (phplint, phpcs, and phpunit):

$ composer test

API Documentation

• The auto-generated phpDocumentor API documentation is available at:
  https://locomotivemtl.github.io/charcoal-contrib-database-migrator/docs/master/
• The auto-generated apigen API documentation is available at:
  https://codedoc.pub/locomotivemtl/charcoal-contrib-database-migrator/master/

Development Dependencies

• [php-coveralls/php-coveralls][phpcov]
• [phpunit/phpunit][phpunit]
• [squizlabs/php_codesniffer][phpcs]

Coding Style

The charcoal-contrib-database-migrator module follows the Charcoal coding-style:

• PSR-1
• PSR-2
• PSR-4, autoloading is therefore provided by Composer.
• phpDocumentor comments.
• phpcs.xml.dist and .editorconfig for coding standards.

Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf.

Credits

• Locomotive

License

Charcoal is licensed under the MIT license. See LICENSE for details.