Configuration

When you initialize your project using the Init Command, Phinxcreates a default file called phinx.yml in the root of your project directory.This file uses the YAML data serialization format.

If a —configuration command line option is given, Phinx will load thespecified file. Otherwise, it will attempt to find phinx.php, phinx.json orphinx.yml and load the first file found. See the Commandschapter for more information.

Warning

Remember to store the configuration file outside of a publicly accessibledirectory on your webserver. This file contains your database credentialsand may be accidentally served as plain text.

Note that while JSON and YAML files are parsed, the PHP file is included.This means that:

  • It must return an array of configuration items.
  • The variable scope is local, i.e. you would need to explicitly declareany global variables your initialization file reads or modifies.
  • Its standard output is suppressed.
  • Unlike with JSON and YAML, it is possible to omit environment connection detailsand instead specify connection which must contain an initialized PDO instance.This is useful when you want your migrations to interact with your applicationand/or share the same connection. However remember to also pass the database nameas Phinx cannot infer this from the PDO connection.
  1. <?php
  2. require 'app/init.php';
  3.  
  4. global $app;
  5. $pdo = $app->getDatabase()->getPdo();
  6.  
  7. return ['environments' =>
  8.          [
  9.            'default_database' => 'development',
  10.            'development' => [
  11.              'name' => 'devdb',
  12.              'connection' => $pdo,
  13.            ]
  14.          ]
  15.        ];

Migration Paths

The first option specifies the path to your migration directory. Phinx uses%%PHINX_CONFIG_DIR%%/db/migrations by default.

Note

%%PHINX_CONFIG_DIR%% is a special token and is automatically replacedwith the root directory where your phinx.yml file is stored.

In order to overwrite the default %%PHINX_CONFIG_DIR%%/db/migrations, youneed to add the following to the yaml configuration.

  1. paths:
  2.     migrations: /your/full/path

You can also provide multiple migration paths by using an array in your configuration:

  1. paths:
  2.     migrations:
  3.         - application/module1/migrations
  4.         - application/module2/migrations

You can also use the %%PHINX_CONFIG_DIR%% token in your path.

  1. paths:
  2.     migrations: '%%PHINX_CONFIG_DIR%%/your/relative/path'

Migrations are captured with glob, so you can define a pattern for multipledirectories.

  1. paths:
  2.     migrations: '%%PHINX_CONFIG_DIR%%/module/*/{data,scripts}/migrations'

Custom Migration Base

By default all migrations will extend from Phinx’s AbstractMigration class.This can be set to a custom class that extends from AbstractMigration bysetting migration_base_class in your config:

  1. migration_base_class: MyMagicalMigration

Seed Paths

The second option specifies the path to your seed directory. Phinx uses%%PHINX_CONFIG_DIR%%/db/seeds by default.

Note

%%PHINX_CONFIG_DIR%% is a special token and is automatically replacedwith the root directory where your phinx.yml file is stored.

In order to overwrite the default %%PHINX_CONFIG_DIR%%/db/seeds, youneed to add the following to the yaml configuration.

  1. paths:
  2.     seeds: /your/full/path

You can also provide multiple seed paths by using an array in your configuration:

  1. paths:
  2.     seeds:
  3.         - /your/full/path1
  4.         - /your/full/path2

You can also use the %%PHINX_CONFIG_DIR%% token in your path.

  1. paths:
  2.     seeds: '%%PHINX_CONFIG_DIR%%/your/relative/path'

Environments

One of the key features of Phinx is support for multiple database environments.You can use Phinx to create migrations on your development environment, thenrun the same migrations on your production environment. Environments arespecified under the environments nested collection. For example:

  1. environments:
  2.     default_migration_table: phinxlog
  3.     default_database: development
  4.     production:
  5.         adapter: mysql
  6.         host: localhost
  7.         name: production_db
  8.         user: root
  9.         pass: ''
  10.         port: 3306
  11.         charset: utf8
  12.         collation: utf8_unicode_ci

would define a new environment called production.

In a situation when multiple developers work on the same project and each hasa different environment (e.g. a convention such as <environmenttype>-<developer name>-<machine name>), or when you need to have separateenvironments for separate purposes (branches, testing, etc) use environmentvariable PHINX_ENVIRONMENT to override the default environment in the yamlfile:

  1. export PHINX_ENVIRONMENT=dev-`whoami`-`hostname`

Table Prefix and Suffix

You can define a table prefix and table suffix:

  1. environments:
  2.     development:
  3.         ....
  4.         table_prefix: dev_
  5.         table_suffix: _v1
  6.     testing:
  7.         ....
  8.         table_prefix: test_
  9.         table_suffix: _v2

Socket Connections

When using the MySQL adapter, it is also possible to use sockets instead ofnetwork connections. The socket path is configured with unix_socket:

  1. environments:
  2.     default_migration_table: phinxlog
  3.     default_database: development
  4.     production:
  5.         adapter: mysql
  6.         name: production_db
  7.         user: root
  8.         pass: ''
  9.         unix_socket: /var/run/mysql/mysql.sock
  10.         charset: utf8

Use the following bash command in a Linux environment to retrieve the socket file path to use for unix_socket:

  1. # For PostGreSQL
  2. find / -name .s.PGSQL.5432 -ls 2>&1 | grep -v "Permission denied"
  3. # For MySQL
  4. find / -name mysql.sock -ls 2>&1 | grep -v "Permission denied"

Alternatively, mysql.sock file can also be retrieved from MySQL Shell

  1. SHOW VARIABLES LIKE 'socket';

External Variables

Phinx will automatically grab any environment variable prefixed with PHINX_and make it available as a token in the config file. The token will haveexactly the same name as the variable but you must access it by wrapping two%% symbols on either side. e.g: %%PHINX_DBUSER%%. This is especiallyuseful if you wish to store your secret database credentials directly on theserver and not in a version control system. This feature can be easilydemonstrated by the following example:

  1. environments:
  2.     default_migration_table: phinxlog
  3.     default_database: development
  4.     production:
  5.         adapter: mysql
  6.         host: '%%PHINX_DBHOST%%'
  7.         name: '%%PHINX_DBNAME%%'
  8.         user: '%%PHINX_DBUSER%%'
  9.         pass: '%%PHINX_DBPASS%%'
  10.         port: 3306
  11.         charset: utf8

Supported Adapters

Phinx currently supports the following database adapters natively:

SQLite

Declaring an SQLite database uses a simplified structure:

  1. environments:
  2.     development:
  3.         adapter: sqlite
  4.         name: ./data/derby
  5.     testing:
  6.         adapter: sqlite
  7.         memory: true     # Setting memory to *any* value overrides name

SQL Server

When using the sqlsrv adapter and connecting to a named instance you shouldomit the port setting as SQL Server will negotiate the port automatically.Additionally, omit the charset: utf8 or change to charset: 65001 whichcorresponds to UTF8 for SQL Server.

Custom Adapters

You can provide a custom adapter by registering an implementation of thePhinx\Db\Adapter\AdapterInterface with AdapterFactory:

  1. $name  = 'fizz';
  2. $class = 'Acme\Adapter\FizzAdapter';
  3.  
  4. AdapterFactory::instance()->registerAdapter($name, $class);

Adapters can be registered any time before $app->run() is called, which normallycalled by bin/phinx.

Aliases

Template creation class names can be aliased and used with the —class command line option for the Create Command.

The aliased classes will still be required to implement the Phinx\Migration\CreationInterface interface.

  1. aliases:
  2.     permission: \Namespace\Migrations\PermissionMigrationTemplateGenerator
  3.     view: \Namespace\Migrations\ViewMigrationTemplateGenerator

Version Order

When rolling back or printing the status of migrations, Phinx orders the executed migrations according to theversion_order option, which can have the following values:

  • creation (the default): migrations are ordered by their creation time, which is also part of their filename.
  • execution: migrations are ordered by their execution time, also known as start time.