wiki:PhinxHowTo

Since milestone 2.6 all updates of the database are handled with phinx migrations.

With Phinx migrations can be handled using an API or with SQL calls that are stored in migrations files that use a timestamp to determine if the migration has been ran already.

A migration can either consist of a up() and down() method or a change() method. While you can freely choose between API calls and SQL calls in up() and down() methods only API calls are allowed in change(). On the other hand with a change() method Phinx takes care of reverting a migration for you.

Any migrations script needs to include a comment why the migration is done and a link to a Trac ticket. In some cases a down migration might not be necessary or cumbersome. In these case a comment has to be added in the down() method to cover this.

Some example to make this clear:

<?php
/************************************
 * Class DropDbVersion
 *
 * Removes the spurious table dbversion which became obsolete thanks to phinx
 *
 * See ticket: #2219
 *
 */
class DropDbVersion extends AbstractMigration
{
    /**
     * Migrate Up.
     */
    public function up()
    {
        $this->dropTable('dbversion');
    }

    /**
     * Migrate Down.
     */
    public function down()
    {
        // No down migration needed in this case as table was never used.
    }
}
<?php
/*************************
 * Class MailFormatPreference
 * 
 * Adds a preference to allow members to choose their preferred mail format
 * 
 * See ticket: #1853
 */
class MailFormatPreference extends AbstractMigration
{
    /**
     * Migrate Up.
     */
    public function up()
    {
        $this->execute("INSERT INTO
        `preferences`
        (`id`, `position`, `codeName`, `codeDescription`, `Description`, `created`, `DefaultValue`, `PossibleValues`, `EvalString`, `Status`)
VALUES
(NULL, '51', 'PreferenceHtmlMails', 'PreferenceHtmlMailsDesc', 'This allows the member to choose the format of the
messages send by bewelcome.org. Defaults to HTML', CURRENT_TIMESTAMP, 'Yes', 'Yes;No', '', 'Normal');");

    }

    /**
     * Migrate Down.
     */
    public function down()
    {
        $this->execute("DELETE FROM `preferences` WHERE `codeName` = 'PreferenceHtmlMails'");
    }
}

And one example that uses the change() method:

<?php
/************************************************
 * Class AdjustSlowQueries
 *
 * Adjusts some indices to reduce the number of slow queries
 *
 * See ticket: #2216
 */
class AdjustSlowQueries extends AbstractMigration
{
    /**
     * Change.
     */
    public function change()
    {
        // add some indices
        $table = $this->table('forums_threads');
        $table->addIndex(array("ThreadVisibility"))
            ->addIndex(array("ThreadDeleted"))
            ->update();

        $table = $this->table('forums_posts');
        $table->addIndex(array("PostVisibility"))
            ->addIndex(array("PostDeleted"))
            ->addIndex(array("create_time"))
            ->update();

        $table = $this->table('messages');
        $table->addIndex(array("DeleteRequest"))
            ->addIndex(array("WhenFirstRead"))
            ->update();
    }

    /**
     * Migrate Up.
     */
    public function up()
    {
    }

    /**
     * Migrate Down.
     */
    public function down()
    {
    }
}
Last modified 3 years ago Last modified on Jul 27, 2014 10:54:39 PM