README

WordPress 数据库迁移系统

需求

需要 PinkCrab Table Builder、Composer 和 WordPress。

使用 WPDB Table Builder 库。

测试环境

• PHP 7.2, 7.3, 7.4, 8.0 & 8.1
• Mysql 5.7, MariaDB 10.2, 10.3, 10.4, 10.5, 10.6 & 10.7
• WP5.9, WP6.0 & WP6.1

安装

$ composer require pinkcrab/wp-db-migrations

如果您在使用 PinkCrab Perique 框架，请使用 Perique Migrations 模块。

原因

创建一个围绕 WPDB_Table_Builder 的包装器，使其更容易创建用于 WP 插件或主题的迁移。允许创建和删除数据库表以及初始化数据的填充。

如何使用

您需要使用 Database_Migration 抽象类创建迁移。

阅读模式文档

<?php

use PinkCrab\Table_Builder\Schema;
use PinkCrab\DB_Migration\Database_Migration;

class Foo_Migration extends Database_Migration {

    // Define the tables name.
    protected $table_name = 'foo_table';

    // Define the tables schema
    public function schema( Schema $schema_config ): void {
        $schema_config->column('id')->unsigned_int(12)->auto_increment()
        $schema_config->index('id')->primary();

        $schema_config->column('column1')->text()->nullable();
        $schema_config->column('column2')->text()->nullable();
    }

    // Add all data to be seeded 
    public function seed( array $seeds ): array {
        $seeds[] = [
            'column1' => 'value1',
            'column2' => 'value2',
        ];

        $seeds[] = [
            'column1' => 'value1',
            'column2' => 'value2',
        ];
        
        return $seeds;
    }
}

创建迁移后，您可以使用迁移管理器来处理表的创建、填充和最终删除。

阅读构建器文档

<?php

global $wpdb; // You can access this however you please.

// See PinkCrab Table Builder for details about the Builder.
$builder = new Builder(...);

$manager = new Migration_Manager($builder, $wpdb, 'acme_migration_log_key');

// Add all migration to manager
$manager->add_migration(new Foo_Migration());

// Create tables
$manager->create_tables('some_table_to_skip');

// Insert all seed data
$manager->seed_tables('some_table_to_skip');

// Drop all tables
$manager->drop_tables('some_table_to_skip');

建议将创建表格、填充表格和删除表格包裹在 try/catch 中，因为它们可能会抛出异常。

了解更多关于迁移管理器的信息

工厂

您可以创建迁移管理器和迁移日志的实例。

Factory::manager_with_db_delta(?string $option_key = null, ?wpdb $wpdb = null)

可用于创建带有标准 wpdb 实例的管理器集。可以定义自定义日志选项键，并且如果您想使用多个数据库，可以使用自定义 wpdb 实例。

$manager = PinkCrab\DB_Migration\Factory::manager_with_db_delta('acme_migration_log_key', $custom_wpdb);

Factory::migration_log(?string $option_key = null)

创建迁移日志的实例，如果设置了自定义值，则可以可选地传递迁移管理器中使用的选项键。

$migration_log = PinkCrab\DB_Migration\Factory::migration_log('acme_migration_log_key');

迁移日志

迁移管理器有一个内部日志，该日志被序列化并存储为 WP 选项。这用于确保只有在模式更改时才更新表，并且每个表只能发生一次填充。如果您需要访问日志，您可以从迁移管理器实例中调用它 $manager->migration_log(); 或创建一个实例。

$log = new Migration_Log_Manager('custom_option_key');

了解更多关于迁移日志的信息

异常

在过程中，可能会抛出多个异常，这些都是 PinkCrab\DB_Migration\Migration_Exceptions

我们所有的异常都包含正在工作的模式实例，这可以通过 $exception->get_schema() 访问。如果触发了 WPDB 错误，则设置 WPDB 错误，这可以通过 $exception->get_wpdb_error() (seed_column_doesnt_exist, 不使用此) 访问

seed_column_doesnt_exist

当尝试从模式获取列数据，但列不存在时抛出。

消息: 在 {table name} 模式定义中找不到列 {column name}

错误代码: 1

failed_to_insert_seed

当尝试插入填充数据，但 wpdb 返回错误时抛出。

消息: 无法将种子插入到 {table name}，失败，错误 {wpdb error}

错误代码: 2

failed_to_drop_table

当 wpdb 在删除表时产生错误时抛出。

消息：无法删除 {表名}

错误代码：3

与插件一起使用

使用迁移服务的最佳方式是将它作为插件激活/卸载过程的一部分。这样可以确保在插件激活时创建并填充所有表格，在插件卸载时删除所有表格。

感谢迁移日志，只有当模式更改时才会重新处理表格，数据只能填充一次。所以如果您计划在插件的后续版本中添加种子数据，可以在准备好时添加。

在处理外键时，请确保首先创建所有基础表格，然后创建引用它们的表格。但在删除时，请确保反向操作。

表格都创建好了，然后以相同的顺序填充所有表格

查看我们的示例插件

变更日志

• 1.0.4 - 更新了依赖关系和测试管道
• 1.0.3 - 改进了异常处理
• 1.0.2 - 更新了文档，添加了从日志管理器清除所有日志的方法，并修复了 Migration_Manager::migation_log() 中的类型错误（该方法已被弃用，并替换为 Migration_Manager::migration_log()）
• 1.0.1 - 允许通过 Migration_Log_Manager->get_log_key() 方法访问迁移管理器日志键
• 1.0.0 - 现在支持WPDB Table Builder 1.0.0
• 0.3.1 - 添加了Dependabot配置
• 0.3.0 - 从WPDB Table Builder 0.2 迁移到 0.3
• 0.2.0 - 从 (OLD) PinkCrab 框架 v0.1.0 注册包中提取