https://github.com/griffin-php/griffin
Griffin is a Graph-Oriented Migration Framework for PHP
https://github.com/griffin-php/griffin
database dependencies framework graph graph-theory migration migrations php
Last synced: 2 months ago
JSON representation
Griffin is a Graph-Oriented Migration Framework for PHP
- Host: GitHub
- URL: https://github.com/griffin-php/griffin
- Owner: griffin-php
- License: mit
- Created: 2021-04-12T21:32:14.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2021-05-13T11:37:36.000Z (almost 5 years ago)
- Last Synced: 2025-05-10T03:51:17.910Z (11 months ago)
- Topics: database, dependencies, framework, graph, graph-theory, migration, migrations, php
- Language: PHP
- Homepage:
- Size: 218 KB
- Stars: 14
- Watchers: 2
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# griffin
Griffin is a Graph-Oriented Migration Framework for PHP
[](https://github.com/griffin-php/griffin/actions/workflows/test.yml?query=branch%3Amain)
[](https://packagist.org/packages/griffin/griffin)
[](https://codecov.io/gh/griffin-php/griffin)
[](https://packagist.org/packages/griffin/griffin)
## TL;DR
Griffin is a generic migration framework that uses graph theory to provision
anything. It plans execution based on migration dependencies and runs them in
the correct order.
```php
use FooBar\Database\Driver;
use Griffin\Migration\Container;
use Griffin\Migration\Migration;
use Griffin\Planner\Planner;
use Griffin\Runner\Runner;
$driver = new Driver(); // Pseudo Database Driver
$orders = (new Migration())
->withName('orders')
->withAssert(fn() => $driver->table->has('orders'))
->withUp(fn() => $driver->table->create('orders'))
->withDown(fn() => $driver->table->drop('orders'));
$items = (new Migration())
->withName('items')
->withDependencies(['orders'])
->withAssert(fn() => $driver->table->has('items'))
->withUp(fn() => $driver->table->create('items'))
->withDown(fn() => $driver->table->drop('items'));
$container = (new Container())
->addMigration($orders)
->addMigration($items);
$planner = new Planner($container);
$runner = new Runner($planner);
$runner->up(); // create everything
$runner->down(); // destroy everything
$runner->up('items'); // create orders and items
$runner->down('orders'); // destroy orders and items
// create orders and items
// regardless the order of elements informed
$runner->up('items', 'orders');
// Dry Run
$runner->setDryRun();
$runner->up(); // do nothing
$runner->down(); // do nothing
$runner->unsetDryRun();
```
You might want to check
[more examples](https://github.com/griffin-php/griffin-examples) to learn how to
define migrations using Griffin.
## Installation
This package uses [Composer](https://packagist.org/packages/griffin/griffin) as
default repository. You can install it adding the name of package in `require`
section of `composer.json`, pointing to the latest stable version.
```json
{
"require": {
"griffin/griffin": "^1.0"
}
}
```
### CLI
This package includes the Griffin framework. If you want a CLI to run your
migrations, please check
[Griffin CLI](https://github.com/griffin-php/griffin-cli).
## Introduction
Migrations are tools to change system current state, adding (or removing)
features based on previous state. Generally, they are used to create database
structures from scratch, provisioning tables or columns using a step-by-step
approach. There are standalone tools to run migrations, like Phinx. Also, there
are other ones embedded into frameworks, like Laravel or Doctrine.
If we inspect them, they use a linear approach, where next state must *migrate*
from current state. Migrations can be rolled back, so if we want to revert some
changes, we must *rollback* from current state to previous state. Each migration
knows how to create and destroy itself.
For example, we have three migrations `A`, `B` and `C` created sequentially. If
our current state is `A` and we must migrate to `C`, we must execute migrations
`B` and `C`, in that order, respectively. If we want to rollback from `C` to
`A`, we must execute them backwards, `B` and `A`. But if you want to execute
migrations `A` and `C`, because they are dependent, and ignore `B` for some
reason, you can't. Even, if you want to rollback `C` and `A` ignoring `B`, you
are locked.
Bringing to the world of database migrations, you can create migration `Orders`
that creates table into schema. Right after that, other developer creates a
migration called `Messages` without any dependency from `Orders`. Next, you
create a migration named `Items` with a foreign key to `Orders`. Everything
works fine and you deploy them to *stage* environment on friday.
```
./migrations/001_Orders.php
./migrations/002_Messages.php
./migrations/003_Items.php
```
On monday you find a problem with your migrations and you want to rollback. But
you don't want to remove `Messages` table because other developer is showing the
newest features to Product Owner.
And here comes Griffin.
## Description
Griffin is a migration framework based on directed graphs, where each migration
can be migrated and rolled back independently. Also, you can define dependencies
for each migration and Griffin is responsible to plan the execution priority.
Based on provisioning tools like Puppet and Terraform, Griffin can plan
execution and run it using graph theory, where each migration works like a
vertice and dependencies define directed paths. Griffin searches for circular
dependencies on planning and can automatically rollback changes if errors were
found.
Griffin is a generic migration framework and it is not database focused. You are
free to use Griffin to provisioning what needed, like directory structures,
packages, crawlers and even database schemas.
## Usage
Each migration must be defined using `Griffin\Migration\MigrationInterface`.
Migrations must return its name with `getName` method and dependencies with
`getDependencies`. Each migration must check if resource is created using
`assert` method, returning a boolean as result. Also, they are responsible to
create the resource using `up` method and to destroy using `down`. Griffin uses
these methods to plan and run migrations.
```php
namespace FooBar\Database\Migration;
use FooBar\Database\Driver;
use Griffin\Migration\MigrationInterface;
class Items implements MigrationInterface
{
public function __construct(
private Driver $driver,
) {}
public function getName(): string
{
return self::class;
}
/**
* @return string[]
*/
public function getDependencies(): array
{
return [
Order::class,
Product::class,
];
}
public function assert(): bool
{
return $this->driver->table->has('items');
}
public function up(): void
{
$this->driver->table->create('items');
}
public function down(): void
{
$this->driver->table->drop('items');
}
}
```
You can create objects from class `Griffin\Migration\Migration`, that implements
`Griffin\Migration\MigrationInterface` and behaviors can be defined using
immutable methods.
```php
use FooBar\Database\Driver;
use Griffin\Migration\Migration;
$driver = new Driver();
$migration = (new Migration())
->withName('items')
->withDependencies(['orders', 'products'])
->withAssert(fn() => $driver->table->has('items'))
->withUp(fn() => $driver->table->create('items'))
->withDown(fn() => $driver->table->drop('items'));
```
### Planning
Griffin plans your migrations execution before running them using
`Griffin\Planner\Planner`. Every migration must be added to
`Griffin\Migration\Container` instances and attached to planner on construction.
```php
use FooBar\Database\Migration;
use Griffin\Migration\Exception as MigrationException;
use Griffin\Planner\Exception as PlannerException;
use Griffin\Planner\Planner;
$planner = new Planner();
$planner->getContainer()
->addMigration(new Migration\Orders())
->addMigration(new Migration\Items())
->addMigration(new Migration\Products());
/** @var Griffin\Migration\Container $migrations **/
try {
// plan up execution for every migration
$migrations = $planner->up();
// plan up execution for Orders and Items
$migrations = $planner->up(Migration\Items::class)
// plan down execution
$migrations = $planner->down();
} catch (PlannerException $e) {
// PlannerException::DEPENDENCY_CIRCULAR (Circular Dependency Found)
// PlannerException::DEPENDENCY_INVALID (Invalid Dependency Data Type)
} catch (MigrationException $e) {
// MigrationException::NAME_UNKNOWN (Unknown Migration Name)
// MigrationException::NAME_DUPLICATED (Duplicated Migration Name)
// MigrationException::CALLABLE_UNKNOWN (Unknown Callable Function)
}
```
You can add migrations to container in any order, because dependencies are
checked on planning stage. Migration names are unique and must not be
duplicated. Using objects from `Griffin\Migration\Migration` immutable class can
throw errors if callables were not defined.
This stage also searches for circular dependencies, where `A` depends of `B` and
`B` depends of `A`. This type of requirement is not allowed and will rise an
exception describing the problem.
### Running
After planning, Griffin runs migrations using `Griffin\Runner\Runner` class.
Internally, Griffin plans migrations execution first and after that it will
execute running on second stage.
```php
use FooBar\Database\Migration;
use Griffin\Migration\Exception as MigrationException;
use Griffin\Planner\Exception as PlannerException;
use Griffin\Runner\Exception as RunnerException;
use Griffin\Runner\Runner;
$runner = new Runner();
$runner->getPlanner()->getContainer()
->addMigration(new Migration\Orders())
->addMigration(new Migration\Items())
->addMigration(new Migration\Products());
try {
// run up for everything
$runner->up();
// run up for Orders and Items
$runner->up(Migration\Items::class)
// run complete down
$runner->down();
} catch (RunnerException $e) {
// RunnerException::ROLLBACK_CIRCULAR (Circular Rollback Found)
} catch (PlannerException $e) {
// PlannerException::DEPENDENCY_CIRCULAR (Circular Dependency Found)
// PlannerException::DEPENDENCY_INVALID (Invalid Dependency Data Type)
} catch (MigrationException $e) {
// MigrationException::NAME_UNKNOWN (Unknown Migration Name)
// MigrationException::NAME_DUPLICATED (Duplicated Migration Name)
// MigrationException::CALLABLE_UNKNOWN (Unknown Callable Function)
}
```
For every planned migration `Griffin\Runner\Runner` will execute migration `up`
method if `assert` returns `false`. During a migration execution, errors can be
raised and Griffin will try to automatically rollback executed migrations. If
during rollback from this migration Griffin finds another error, an exeception
will be throw.
If you want to rollback migrations manually, Griffin will use migration `assert`
method to check if resource was created and if this method returns `true`,
migration method `down` will be called. As before, if Griffin finds an error it
will try to recreate resources.
### Event Dispatcher
Lastly, Griffin use PSR-14 Event Dispatcher to trigger events after and before
migrations up and down. You can use it to create a logger, as example, using
`league/event` package or any PSR-14 implementation.
```php
use FooBar\Database\Migration;
use Griffin\Event;
use Griffin\Migration\Container;
use Griffin\Planner\Planner;
use Griffin\Runner\Runner;
use League\Event\EventDispatcher;
$container = new Container();
$planner = new Planner($container);
$runner = new Runner($planner);
$logger = fn($event)
=> printf("%s::%s\n", get_class($event), get_class($event->getMigration()));
$dispatcher = new EventDispatcher(); // PSR-14
$dispatcher->subscribeTo(Event\Migration\UpBefore::class, $logger);
$dispatcher->subscribeTo(Event\Migration\UpAfter::class, $logger);
$dispatcher->subscribeTo(Event\Migration\DownBefore::class, $logger);
$dispatcher->subscribeTo(Event\Migration\DownAfter::class, $logger);
$runner
->setEventDispatcher($dispatcher)
->addMigration(new Migration\Orders());
$runner->up();
$runner->down();
// Griffin\Event\Migration\UpBefore::Database\Migration\Table\Item
// Griffin\Event\Migration\UpAfter::Database\Migration\Table\Item
// Griffin\Event\Migration\DownBefore::Database\Migration\Table\Item
// Griffin\Event\Migration\DownAfter::Database\Migration\Table\Item
```
## Development
You can use Docker Compose to build an image and run a container to develop and
test this package.
```bash
docker-compose build
docker-compose run --rm php composer install
docker-compose run --rm php composer test
```
## References
* Wikipedia: [Graph Theory](https://en.wikipedia.org/wiki/Graph_theory)
* Wikipedia: [Path on Graph Theory](https://en.wikipedia.org/wiki/Path_%28graph_theory%29)
* Wikipedia: [Schema Migration](https://en.wikipedia.org/wiki/Schema_migration)
## License
This package is opensource and available under MIT license described in
[LICENSE](https://github.com/griffin-php/griffin/blob/main/LICENSE).
Icons made by [Freepik](https://www.freepik.com) from
[Flaticon](https://www.flaticon.com).