页面内容

配置

配置¶

当您使用初始化命令初始化您的项目时，Phinx 会在您的项目目录的根目录中创建一个默认文件。默认情况下，此文件使用 YAML 数据序列化格式，但您可以使用 --format 命令行选项来指定 yaml、yml、json 或 php。

如果提供了 --configuration 命令行选项，Phinx 将加载指定的文件。否则，它将尝试找到 phinx.php、phinx.json、phinx.yml 或 phinx.yaml 并加载找到的第一个文件。有关更多信息，请参见命令章节。

警告

请记住将配置文件存储在 Web 服务器上无法公开访问的目录之外。此文件包含您的数据库凭据，可能会意外地以纯文本形式提供。

请注意，虽然 JSON 和 YAML 文件是解析的，但 PHP 文件是包含的。这意味着

它必须返回一个配置项数组。
变量范围是本地的，即您需要显式声明您的初始化文件读取或修改的任何全局变量。
它的标准输出被抑制。
与 JSON 和 YAML 不同，可以省略环境连接详细信息，而是指定 connection，它必须包含一个已初始化的 PDO 实例。当您希望迁移与您的应用程序交互和/或共享相同的连接时，这很有用。但是，请记住还要传递数据库名称，因为 Phinx 无法从 PDO 连接中推断出它。

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

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

迁移路径¶

第一个选项指定迁移目录的路径。Phinx 默认使用 %%PHINX_CONFIG_DIR%%/db/migrations。

注意

%%PHINX_CONFIG_DIR%% 是一个特殊标记，会自动替换为您存储 phinx 配置文件的根目录。

为了覆盖默认的 %%PHINX_CONFIG_DIR%%/db/migrations，您需要将以下内容添加到配置中。

paths:
    migrations: /your/full/path

您还可以通过在配置中使用数组来提供多个迁移路径

paths:
    migrations:
        - application/module1/migrations
        - application/module2/migrations

您还可以将 %%PHINX_CONFIG_DIR%% 标记用在路径中。

paths:
    migrations: '%%PHINX_CONFIG_DIR%%/your/relative/path'

迁移使用 glob 捕获，因此您可以为多个目录定义模式。

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

自定义迁移基础¶

默认情况下，所有迁移都将扩展自 Phinx 的 AbstractMigration 类。这可以通过在配置中设置 migration_base_class 来设置为扩展自 AbstractMigration 的自定义类

migration_base_class: MyMagicalMigration

种子路径¶

第二个选项指定您的种子目录的路径。Phinx 默认使用 %%PHINX_CONFIG_DIR%%/db/seeds。

注意

%%PHINX_CONFIG_DIR%% 是一个特殊标记，会自动替换为您存储配置文件的根目录。

为了覆盖默认的 %%PHINX_CONFIG_DIR%%/db/seeds，您需要将以下内容添加到 yaml 配置中。

paths:
    seeds: /your/full/path

您还可以通过在配置中使用数组来提供多个种子路径

paths:
    seeds:
        - /your/full/path1
        - /your/full/path2

您还可以将 %%PHINX_CONFIG_DIR%% 标记用在路径中。

paths:
    seeds: '%%PHINX_CONFIG_DIR%%/your/relative/path'

自定义种子基础¶

默认情况下，所有种子器都将扩展自 Phinx 的 AbstractSeed 类。这可以通过在配置中设置 seed_base_class 来设置为扩展自 AbstractSeed 的自定义类

seed_base_class: MyMagicalSeeder

自定义迁移模板¶

自定义迁移模板可以通过在配置文件中定义模板文件路径来使用

templates:
    file: src/templates/customMigrationTemplate.php

自定义种子模板¶

自定义种子模板可以通过在配置文件中定义模板文件路径来使用

templates:
    seedFile: src/templates/customSeederTemplate.php

环境¶

Phinx 的关键功能之一是支持多个数据库环境。您可以使用 Phinx 在开发环境中创建迁移，然后在生产环境中运行相同的迁移。环境是在 environments 嵌套集合下指定的。例如

environments:
    default_migration_table: phinxlog
    default_environment: development
    production:
        adapter: mysql
        host: localhost
        name: production_db
        user: root
        pass: ''
        port: 3306
        charset: utf8mb4
        collation: utf8mb4_unicode_ci

将定义一个名为 production 的新环境。

在多个开发人员在同一个项目上工作并且每个人都有不同的环境（例如 <environment type>-<developer name>-<machine name> 等约定）的情况下，或者当您需要为不同目的（分支、测试等）创建单独的环境时，使用环境变量 PHINX_ENVIRONMENT 来覆盖 yaml 文件中的默认环境

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

迁移表¶

为了跟踪环境的迁移状态，phinx 创建了一个表来存储此信息。您可以通过配置 default_migration_table 来自定义此表在何处创建，以用作所有环境的默认值

environment:
    default_migration_table: phinxlog

如果省略此字段，它将默认为 phinxlog。对于支持它的数据库（例如 Postgres），模式名称可以使用句点分隔符 (.) 作为前缀。例如，phinx.log 将在 phinx 模式中创建表 log，而不是在 public (默认) 模式中创建 phinxlog。

您也可以为每个环境指定 migration_table。任何没有指定 migration_table 的环境将回退到使用在顶层定义的 default_migration_table。以下是如何使用它的一个示例

environment:
    default_migration_table: phinxlog
    development:
        migration_table: phinxlog_dev
        # rest of the development settings
    production:
        # rest of the production settings

在上面的示例中，development 将查找 phinxlog_dev 表的迁移状态，而 production 将使用 phinxlog。

表前缀和后缀¶

您可以定义表前缀和表后缀

environments:
    development:
        ....
        table_prefix: dev_
        table_suffix: _v1
    testing:
        ....
        table_prefix: test_
        table_suffix: _v2

套接字连接¶

当使用 MySQL 适配器时，还可以使用套接字而不是网络连接。套接字路径使用 unix_socket 配置

environments:
    default_migration_table: phinxlog
    default_environment: development
    production:
        adapter: mysql
        name: production_db
        user: root
        pass: ''
        unix_socket: /var/run/mysql/mysql.sock
        charset: utf8

外部变量¶

Phinx 将自动获取以 PHINX_ 为前缀的任何环境变量，并在配置文件中将其作为标记提供。该标记将与变量完全相同的名称，但您必须通过在两侧包装两个 %% 符号来访问它。例如：'%%PHINX_DBUSER%%'。如果您希望将秘密数据库凭据直接存储在服务器上而不是在版本控制系统中，这特别有用。此功能可以通过以下示例轻松演示

environments:
    default_migration_table: phinxlog
    default_environment: development
    production:
        adapter: mysql
        host: '%%PHINX_DBHOST%%'
        name: '%%PHINX_DBNAME%%'
        user: '%%PHINX_DBUSER%%'
        pass: '%%PHINX_DBPASS%%'
        port: 3306
        charset: utf8

数据源名称¶

Phinx 支持使用数据源名称 (DSN) 来指定连接选项，如果您使用单个环境变量来保存数据库凭据，这将非常有用。PDO 针对不同的底层驱动程序有不同的 DSN 格式，因此 Phinx 使用其他项目 (Doctrine、Rails、AMQP、PaaS 等) 使用的数据库无关的 DSN 格式。

<adapter>://[<user>[:<pass>]@]<host>[:<port>]/<name>[?<additionalOptions>]

DSN 至少需要 adapter、host 和 name。
您不能在没有用户名的情况下指定密码。
port 必须是正整数。
additionalOptions 采用查询字符串的形式，并将传递给适配器中的选项数组。

environments:
    default_migration_table: phinxlog
    default_environment: development
    production:
        # Example data source name
        dsn: mysql://root@localhost:3306/mydb?charset=utf8

解析 DSN 后，其值将与已存在的连接选项合并。在 DSN 中指定的任何值都不会覆盖直接指定为连接选项的任何值。

environments:
    default_migration_table: phinxlog
    default_environment: development
    development:
        dsn: '%%DATABASE_URL%%'
    production:
        dsn: '%%DATABASE_URL%%'
        name: production_database

如果提供的 DSN 无效，则完全忽略它。

支持的适配器¶

Phinx 目前原生支持以下数据库适配器

MySQL: 指定 mysql 适配器。
PostgreSQL: 指定 pgsql 适配器。
SQLite: 指定 sqlite 适配器。
SQL Server: 指定 sqlsrv 适配器。

以下设置可用于适配器

adapter: 要使用的适配器的名称，例如 pgsql。
host: 数据库服务器的主机名（或 IP 地址）。
port: 数据库服务器的 TCP 端口号。
user: 数据库的用户名。
pass: 数据库的密码。
name: 此环境的数据库名称。对于 SQLite，建议使用绝对路径，不带文件扩展名。
suffix: 用于 SQLite 数据库文件的扩展名。默认为 .sqlite3。
schema: 对于 PostgreSQL，允许指定用于数据库的模式。默认为 public。

对于每个适配器，您可以在配置对象中设置常量名称的小写版本，以配置底层 PDO 对象的行为。这适用于 PDO 选项（例如，\PDO::ATTR_CASE 将是 attr_case）和特定于适配器的选项（例如，对于 MySQL，您可以将 \PDO::MYSQL_ATTR_IGNORE_SPACE 设置为 mysql_attr_ignore_space）。请参考 PDO 文档以获取允许的属性及其值。

例如，要设置上述示例选项

$config = [
    "environments" => [
        "development" => [
            "adapter" => "mysql",
            # other adapter settings
            "attr_case" => \PDO::ATTR_CASE,
            "mysql_attr_ignore_space" => 1,
        ],
    ],
];

默认情况下，Phinx 设置的唯一属性是 \PDO::ATTR_ERRMODE 为 PDO::ERRMODE_EXCEPTION。不建议覆盖此设置。

MySQL¶

MySQL 适配器有一个不幸的限制，即它在某些操作时会引发隐式提交，而不管事务状态如何。值得注意的是，此列表包括 CREATE TABLE、ALTER TABLE 和 DROP TABLE，它们是 Phinx 将运行的最常见的操作。这意味着，与其他适配器（在迁移失败时会尝试优雅地回滚事务）不同，如果 MySQL 迁移失败，它可能会使您的数据库处于部分迁移状态。

SQLite¶

声明 SQLite 数据库使用简化的结构

environments:
    development:
        adapter: sqlite
        name: ./data/derby
        suffix: ".db"    # Defaults to ".sqlite3"
    testing:
        adapter: sqlite
        memory: true     # Setting memory to *any* value overrides name

从 PHP 8.1 开始，SQlite 适配器支持 cache 和 mode 查询参数，通过使用 URI 方案，只要 open_basedir 未设置。

environments:
    testing:
        adapter: sqlite
        name: my_app
        mode: memory     # Determines if the new database is opened read-only, read-write, read-write and created if it does not exist, or that the database is a pure in-memory database that never interacts with disk, respectively.
        cache: shared    # Determines if the new database is opened using shared cache mode or with a private cache.

SQL Server¶

在使用 sqlsrv 适配器并连接到命名实例时，您应该省略 port 设置，因为 SQL Server 会自动协商端口。此外，省略 charset: utf8 或更改为 charset: 65001，它对应于 SQL Server 的 UTF8。

自定义适配器¶

您可以通过使用 AdapterFactory 注册 Phinx\Db\Adapter\AdapterInterface 的实现来提供自定义适配器

$name  = 'fizz';
$class = 'Acme\Adapter\FizzAdapter';

AdapterFactory::instance()->registerAdapter($name, $class);

可以在调用 $app->run() 之前任何时间注册适配器，该方法通常由 bin/phinx 调用。

模板¶

您可以通过多种方式覆盖 Phinx 如何生成与之一起使用的模板

file - 要使用的备用文件的路径。
class - 要使用的类的类，必须实现 Phinx\Migration\CreationInterface 接口。
style - 用于模板的样式，可以是 change 或 up_down，默认情况下，如果未设置，则为 change。

您应该只使用这些选项中的一个。这些选项可以通过将命令行选项传递给 Create Command <commands 来覆盖。配置文件中的示例用法为

templates:
    style: up_down

别名¶

模板创建类名可以被别名化，并与 --class 命令行选项一起用于 Create Command。

别名化类仍需实现 Phinx\Migration\CreationInterface 接口。

aliases:
    permission: \Namespace\Migrations\PermissionMigrationTemplateGenerator
    view: \Namespace\Migrations\ViewMigrationTemplateGenerator

版本顺序¶

在回滚或打印迁移状态时，Phinx 会根据 version_order 选项对已执行的迁移进行排序，该选项可以具有以下值

creation（默认）：迁移按其创建时间排序，创建时间也是其文件名的一部分。
execution：迁移按其执行时间（也称为开始时间）排序。

引导路径¶

您可以提供 bootstrap php 文件的路径，该文件将在运行任何 phinx 命令之前包含。请注意，设置外部变量以修改配置将不起作用，因为此时配置已解析。

paths:
    bootstrap: 'phinx-bootstrap.php'

在引导脚本中，以下变量将可用

/**
 * @var string $filename The file name as provided by the configuration
 * @var string $filePath The absolute, real path to the file
 * @var \Symfony\Component\Console\Input\InputInterface $input The executing command's input object
 * @var \Symfony\Component\Console\Output\OutputInterface $output The executing command's output object
 * @var \Phinx\Console\Command\AbstractCommand $context the executing command object
 */

功能标志¶

对于一些重大更改，Phinx 提供了一种选择退出新行为的方法。以下标志可用

unsigned_primary_keys：Phinx 应该将主键创建为无符号整数吗？（默认：true）
column_null_default：Phinx 应该默认将列创建为 null 吗？（默认：true）

由于 MySQL TIMESTAMP 字段不支持 2038-01-19 后的日期，因此您可以选择使用 DATETIME 字段类型为 addTimestamps() 函数创建的字段

add_timestamps_use_datetime：Phinx 应该将 created_at 和 updated_at 字段创建为 datetime 吗？（默认：false）

feature_flags:
    unsigned_primary_keys: false

这些值也可以通过修改 `Phinx\Config\FeatureFlags` 类的类字段来设置，将标志名称转换为 camelCase，例如

Phinx\Config\FeatureFlags::$unsignedPrimaryKeys = false;

B Phinx 0.16 食谱

语言

版本

改进此文档

页面内容

配置¶

迁移路径¶

自定义迁移基础¶

种子路径¶

自定义种子基础¶

自定义迁移模板¶

自定义种子模板¶

环境¶

迁移表¶

表前缀和后缀¶

套接字连接¶

外部变量¶

数据源名称¶

支持的适配器¶

MySQL¶

SQLite¶

SQL Server¶

自定义适配器¶

模板¶

别名¶

版本顺序¶

引导路径¶

功能标志¶