Commands¶

The Create Command¶

The Create command is used to create a new migration file. It requires one argument: the name of the migration. The migration name should be specified in CamelCase format.

$ phinx create MyNewMigration

Open the new migration file in your text editor to add your database transformations. Phinx creates migration files using the path specified in your phinx.yml file. Please see the Configuration chapter for more information.

You are able to override the template file used by Phinx by supplying an alternative template filename.

$ phinx create MyNewMigration --template="<file>"

You can also supply a template generating class. This class must implement the interface Phinx\Migration\CreationInterface.

$ phinx create MyNewMigration --class="<class>"

In addition to providing the template for the migration, the class can also define a callback that will be called once the migration file has been generated from the template.

You cannot use --template and --class together.

The Migrate Command¶

The Migrate command runs all of the available migrations, optionally up to a specific version.

$ phinx migrate -e development

To migrate to a specific version then use the --target parameter or -t for short.

$ phinx migrate -e development -t 20110103081132

Use --dry-run to print the queries to standard output without executing them

$ phinx migrate --dry-run

The Rollback Command¶

The Rollback command is used to undo previous migrations executed by Phinx. It is the opposite of the Migrate command.

You can rollback to the previous migration by using the rollback command with no arguments.

$ phinx rollback -e development

To rollback all migrations to a specific version then use the --target parameter or -t for short.

$ phinx rollback -e development -t 20120103083322

Specifying 0 as the target version will revert all migrations.

$ phinx rollback -e development -t 0

To rollback all migrations to a specific date then use the --date parameter or -d for short.

$ phinx rollback -e development -d 2012
$ phinx rollback -e development -d 201201
$ phinx rollback -e development -d 20120103
$ phinx rollback -e development -d 2012010312
$ phinx rollback -e development -d 201201031205
$ phinx rollback -e development -d 20120103120530

If a breakpoint is set, blocking further rollbacks, you can override the breakpoint using the --force parameter or -f for short.

$ phinx rollback -e development -t 0 -f

Use --dry-run to print the queries to standard output without executing them

$ phinx rollback --dry-run

The Status Command¶

The Status command prints a list of all migrations, along with their current status. You can use this command to determine which migrations have been run.

$ phinx status -e development

This command exits with code 0 if the database is up-to-date (ie. all migrations are up) or one of the following codes otherwise:

• 1: There is at least one migration left to be executed.

• 2: There was a migration run and recorded in the database, but the migration file is now missing.

The Breakpoint Command¶

The Breakpoint command is used to set breakpoints, allowing you to limit rollbacks. You can toggle the breakpoint of the most recent migration by not supplying any parameters.

$ phinx breakpoint -e development

To toggle a breakpoint on a specific version then use the --target parameter or -t for short.

$ phinx breakpoint -e development -t 20120103083322

You can remove all the breakpoints by using the --remove-all parameter or -r for short.

$ phinx breakpoint -e development -r

Breakpoints are visible when you run the status command.

The Seed Create Command¶

The Seed Create command can be used to create new database seed classes. It requires one argument, the name of the class. The class name should be specified in CamelCase format.

$ phinx seed:create MyNewSeeder

Open the new seed file in your text editor to add your database seed commands. Phinx creates seed files using the path specified in your phinx.yml file. Please see the Configuration chapter for more information.

The Seed Run Command¶

The Seed Run command runs all of the available seed classes or optionally just one.

$ phinx seed:run -e development

To run only one seed class use the --seed parameter or -s for short.

$ phinx seed:run -e development -s MyNewSeeder

Configuration File Parameter¶

When running Phinx from the command line, you may specify a configuration file using the --configuration or -c parameter. In addition to YAML, the configuration file may be the computed output of a PHP file as a PHP array:

<?php
    return [
        "paths" => [
            "migrations" => "application/migrations"
        ],
        "environments" => [
            "default_migration_table" => "phinxlog",
            "default_database" => "dev",
            "dev" => [
                "adapter" => "mysql",
                "host" => $_ENV['DB_HOST'],
                "name" => $_ENV['DB_NAME'],
                "user" => $_ENV['DB_USER'],
                "pass" => $_ENV['DB_PASS'],
                "port" => $_ENV['DB_PORT'],
            ]
        ]
    ];

Phinx auto-detects which language parser to use for files with *.yml and *.php extensions. The appropriate parser may also be specified via the --parser and -p parameters. Anything other than "php" is treated as YAML.

When using a PHP array, you can provide a connection key with an existing PDO instance. It is also important to pass the database name too, as Phinx requires this for certain methods such as hasTable():

<?php
    return [
        "paths" => [
            "migrations" => "application/migrations"
        ],
        "environments" => [
            "default_migration_table" => "phinxlog",
            "default_database" => "dev",
            "dev" => [
                "name" => "dev_db",
                "connection" => $pdo_instance
            ]
        ]
    ];

Running Phinx in a Web App¶

Phinx can also be run inside of a web application by using the Phinx\Wrapper\TextWrapper class. An example of this is provided in app/web.php, which can be run as a standalone server:

$ php -S localhost:8000 vendor/robmorgan/phinx/app/web.php

This will create local web server at http://localhost:8000 which will show current migration status by default. To run migrations up, use http://localhost:8000/migrate and to rollback use http://localhost:8000/rollback.

The included web app is only an example and should not be used in production!

Using Phinx with PHPUnit¶

Phinx can be used within your unit tests to prepare or seed the database. You can use it programatically :

public function setUp ()
{
  $app = new PhinxApplication();
  $app->setAutoExit(false);
  $app->run(new StringInput('migrate'), new NullOutput());
}

If you use a memory database, you’ll need to give Phinx a specific PDO instance. You can interact with Phinx directly using the Manager class :

use PDO;
use Phinx\Config\Config;
use Phinx\Migration\Manager;
use PHPUnit\Framework\TestCase;
use Symfony\Component\Console\Input\StringInput;
use Symfony\Component\Console\Output\NullOutput;

class DatabaseTestCase extends TestCase {

    public function setUp ()
    {
        $pdo = new PDO('sqlite::memory:', null, null, [
            PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION
        ]);
        $configArray = require('phinx.php');
        $configArray['environments']['test'] = [
            'adapter'    => 'sqlite',
            'connection' => $pdo
        ];
        $config = new Config($configArray);
        $manager = new Manager($config, new StringInput(' '), new NullOutput());
        $manager->migrate('test');
        $manager->seed('test');
        // You can change default fetch mode after the seeding
        $this->pdo->setAttribute(PDO::ATTR_DEFAULT_FETCH_MODE, PDO::FETCH_OBJ);
        $this->pdo = $pdo;
    }

}