README

此包利用 Phinx 库将传统迁移引入 WordPress，以便在插件和主题中使用。

用法

安装

composer require 0x6d617474/wp-migrations

将集成到您的插件/主题中

require_once sprintf('%s/vendor/autoload.php', $root);
$migrator = new Migrator($root, $instance, $hook);
$migrator->setNamespace('Custom\\Namespace\\Migrations');

$root 是您的包根目录的绝对路径。它应该是您的 composer.json 文件所在的位置。

$instance 是您的插件/主题对象的一个实例。您可以通过 $this->getPackage() 方法在迁移中访问它。如果您没有使用对象来包含您的插件/主题，只需传递一个 null 值。

$hook 定义了迁移将运行的 WordPress 钩子。推荐值是 plugins_loaded 用于插件和 after_setup_theme 用于主题。将此值设置为 false 以禁用自动迁移。

为您的迁移定义一个命名空间有助于防止与其他使用迁移的包发生冲突，可以是您项目中有意义的任何名称。默认情况下，命名空间将是 <$instance namespace>\Migrations。

创建迁移

可以通过复制包含的模板手动创建迁移，或使用 WP-CLI 命令自动创建。模板文件位于 vendor/0x6d617474/wp-migrations/src/migration_template.txt。文件应放置在您的包根部的 migrations 目录中，并命名为：YYYYMMDDHHIISS_Your_Migration_Name。日期戳必须对包中的每个迁移都是唯一的。

包含的 WP-CLI 命令 wp migrations create <slug> <name> 将为您创建一个新的迁移，其中 <slug> 是包的缩写。

运行迁移

可以通过为迁移器定义 $hook 值自动运行迁移（见上文）。您还可以通过在 $migrator 对象上调用 migrate 方法在您的代码中手动运行迁移。

您还可以通过 wp migrations migrate <slug|--all> [--target=target] WP-CLI 命令运行单个包的迁移，或通过库运行所有包的迁移。可选的 target 参数指定一个要中断的目标，否则将运行所有未应用迁移。

运行回滚

可以通过在 $migrator 对象上调用 rollback 方法手动在您的代码中运行回滚。

您还可以通过 wp migrations rollback <slug|--all> [--target=target] [--date=date] WP-CLI 命令运行单个包的回滚，或通过库运行所有包的回滚。可选的 target 参数指定要回滚到的目标，否则将回滚到最后一个迁移。同样，可选的 date 参数指定要回滚到的目标日期。

检查状态

您可以使用 wp migrations status <slug|--all> 命令查看任何或所有包的迁移状态。

查看已应用迁移

您可以使用 wp migrations show <slug> 命令查看任何包的已应用迁移。

注意事项

处理失败

未能完成的迁移将抛出异常。默认情况下，这些异常不会被捕获，并将停止执行。原因是通常失败的迁移是一个严重的问题，应该立即处理（优雅恢复通常不是选项）。

如果您想处理由失败的迁移引起的异常，可以禁用自动迁移，并在 try/catch 块中手动运行迁移。

多站点 WordPress

迁移在多站环境中完全功能，并且每个站点的每个包都独立应用迁移。

如果您想对网络进行一次性的迁移，建议定义一个使用 sitemeta 锁来检查是否需要执行工作的迁移。

public function up()
{
    $lock = '_migration_lock_Blah';
    if (get_site_option($lock, false) === false) {
        // Do the migration
        update_site_option($lock, true)
    }
}

public function down()
{
    $lock = '_migration_lock_Blah';
    if (get_site_option($lock, false) === true) {
        // Do the rollback
        update_site_option($lock, false)
    }
}

Composer 隔离

此包与 Composer 隔离包兼容。如果您在创建迁移后应用隔离，可能需要更新迁移中的 use 语句。

由于 WP-CLI 注册命令的方式，第一个注册 migrations 命令的包将使用其 Command 类由所有包使用。这可能会在包的主要版本升级期间导致不兼容性，但我们对此无能为力。

这仅影响 WP-CLI 命令。在 WP-CLI 之外运行时完全隔离，如同常规操作。