Phinx Documentation

To remove a table, call drop() on the Table object. You must call save() to execute the operation. It is recommended to recreate the table in the down() method to allow for rollbacks.

<?php

use Phinx\Migration\AbstractMigration;

class MyNewMigration extends AbstractMigration
{
    public function up()
    {
        $this->table('users')->drop()->save();
    }

    public function down()
    {
        $users = $this->table('users');
        $users->addColumn('username', 'string', ['limit' => 20])
              ->addColumn('password', 'string', ['limit' => 40])
              ->addColumn('password_salt', 'string', ['limit' => 40])
              ->addColumn('email', 'string', ['limit' => 100])
              ->addColumn('first__name', 'string', ['limit' => 30])
              ->addColumn('last_name', 'string', ['limit' => 30])
              ->addColumn('created', 'datetime')
              ->addColumn('updated', 'datetime', ['null' => true])
              ->addIndex(['username', 'email'], ['unique' => true])
              ->save();
    }
}

Use the Select Query Builder to fetch data. You can specify fields, use aliases, and apply complex WHERE conditions using arrays or closures.

Selecting Fields

• Pass an array of column names: select(['id', 'title'])
• Use associative arrays for aliasing: select(['alias' => 'column_name'])
• Use a closure for dynamic selection.

Where Conditions

• Simple arrays: where(['id' => 1]) or where(['id >' => 1]). You can include operators like >, <, etc., in the key string.
• Logical operators: Use andWhere() for chaining or pass an 'OR' key in the array: where(['OR' => ['id >' => 1, 'title' => 'My title']]).
• Closures and Expressions: For complex logic, pass a closure that receives an expression object ($exp).

<?php
// Selecting with aliases
$builder->select(['pk' => 'id', 'aliased_title' => 'title', 'body']);

// Simple WHERE
$builder->where(['id >' => 1])->andWhere(['title' => 'My Title']);

// Complex WHERE with expression object
$builder->select('*')
    ->from('articles')
    ->where(function ($exp) {
        return $exp
            ->eq('author_id', 2)
            ->gt('view_count', 10);
    });

Phinx supports multiple configuration formats: yaml, yml, json, and php. When running Phinx commands, you can specify a custom file using the --configuration flag. If not specified, Phinx searches for phinx.php, phinx.json, phinx.yml, or phinx.yaml in the current directory.

Using a PHP configuration file: When using a .php file, the file is included rather than parsed. It must return an array of configuration items. This allows you to pass an existing PDO instance via the connection key, which is useful for sharing connections with your application. Note that you must still explicitly provide the name (database name) as Phinx cannot infer it from the PDO instance.

$app = require 'app/phinx.php';
$pdo = $app->getDatabase()->getPdo();

return [
    'environments' => [
        'default_environment' => 'development',
        'development' => [
            'name' => 'devdb',
            'connection' => $pdo
        ]
    ]
];

To create a table, use the table() method to initialize the object, chain addColumn() and addIndex() calls to define the schema, and finally call create() to commit the changes.

Phinx automatically creates an auto-incrementing primary key column named id.

Customizing Primary Keys

• Disable automatic ID: Pass ['id' => false] in the options array to the table() method. If you disable id, you must specify a primary_key (or array of columns) to avoid having no primary key.
• Change ID name: Pass ['id' => 'your_custom_name'] to the table() method.
• Composite Primary Key: Pass an array of column names to the primary_key option: ['primary_key' => ['col1', 'col2']].

<?php

use Phinx\Migration\AbstractMigration;

class MyNewMigration extends AbstractMigration
{
    public function change()
    {
        $users = $this->table('users');
        $users->addColumn('username', 'string', ['limit' => 20])
              ->addColumn('password', 'string', ['limit' => 40])
              ->addColumn('password_salt', 'string', ['limit' => 40])
              ->addColumn('email', 'string', ['limit' => 100])
              ->addColumn('first_name', 'string', ['limit' => 30])
              ->addColumn('last_name', 'string', ['limit' => 30])
              ->addColumn('created', 'datetime')
              ->addColumn('updated', 'datetime', ['null' => true])
              ->addIndex(['username', 'email'], ['unique' => true])
              ->create();
    }
}

The change() method is the default for writing reversible migrations. When using the Table API within change(), Phinx automatically determines how to undo actions like creating/renaming tables, adding columns/indexes, or adding foreign keys.

Important:

• When working with the Table class inside change(), you must use create() or update() instead of save() to ensure Phinx can track the operation for reversal.
• If an action cannot be automatically reversed, Phinx will throw an IrreversibleMigrationException during a rollback. To handle non-reversible logic (like inserting data) within change(), wrap it in a conditional check using $this->isMigratingUp().

<?php

use Phinx\
Migration\\AbstractMigration;

class CreateUserLoginsTable extends AbstractMigration
{
    public function change()
    {
        // create the table
        $table = $this->table('user_logins');
        $table->addColumn('user_id', 'integer')
              ->addColumn('created', 'datetime')
              ->create();

        if ($this->isMigratingUp()) {
            $table->insert([['user_id' => 1, 'created' => '2020-01-19 03:14:07']])
                  ->save();
        }
    }
}