README

Perique - 迁移

围绕各种 PinkCrab 库的包装器，它使得从使用 Perique 框架创建的插件中运行数据库迁移变得更加容易。

为什么？

已经存在一个由 PinkCrab 编写的 WPDB 迁移系统，可用于任何 WordPress 插件甚至主题。然而，由于 Perique 注册流程的性质以及 WordPress 如何处理插件事件（如激活、停用和卸载），将其整合到 Perique 中需要构建一个小的独立工作流程。

因此，为了使将数据库迁移添加到 Perique 更加无缝，我们创建了这个库来帮助。

依赖

如前所述，此库更像是一个以下包的桥梁。

• WPDB 迁移
• WPDB 表构建器
• Perique 插件生命周期

设置

$ composer require pinkcrab/perique-migrations

创建迁移

要创建数据库迁移，必须扩展 Migration 抽象类。

以下为完整的迁移模型参考 示例插件

class Acme_Migration extends Migration {
    
    /**
     * Returns the name of the table.
     *
     * @required
     * @return string Table name
     */
    protected function table_name(): string {
        return 'acme_migration_sample_table';
    }

    /**
     * Defines the schema for the migration.
     *
     * @param Schema $schema_config
     * @return void
     */
    public function schema( Schema $schema_config ): void {
        $schema_config->column( 'id' )
            ->unsigned_int( 11 )
            ->auto_increment();
    
        $schema_config->column( 'user_ref' )
            ->text( 11 );
    
        $schema_config->column( 'thingy_ref' )
            ->int( 11 );
    
        $schema_config->index( 'id' )
            ->primary();
    }

    /**
     * Defines the data to be seeded.
     *
     * @param array<string, mixed> $seeds
     * @return array<string, mixed>
     */
    public function seed( array $seeds ): array {
        return [
            [
                'user_ref'   => 'ghjuyitjkuiy'
                'thingy_ref' => 1325546
            ],
            [
                'user_ref'   => 'eouroipewrjhiowe'
                'thingy_ref' => 897456
            ]
        ];
    }
}

使用 Perique App 配置 生成表名。

class Use_Dependency_Migration extends Migration {
    protected $config;
    public function __construct( App_Config $config ) {
        $this->config = $config;
    }
    protected function table_name(): string {
        return $this->config->db_tables('from_app_config');
    }    
}

创建迁移服务

Perique 迁移模块需要将插件生命周期添加到 Perique App 中。这是为了确保迁移在正确的时间运行。

// @file plugin.php

// Boot the app as normal and create an instance of Plugin_State_Controller
$app = (new App_Factory())
    // setup the app as normal
    ->default_setup()

    // Ensure Plugin Life Cycle is added
    ->module(Perique_Plugin_Life_Cycle::class)
    
    // Add the Migrations module
    ->module(
        Perique_Migrations::class,
        function( Perique_Migrations $module ) {
            
            // Optional key
            $module->set_migration_log_key( 'acme_plugin_migrations' )
            
            // Add you migrations
            $module->add_migration(Acme_Migration::class)
            $module->add_migration(Some_Migration_With_Dependencies::class);
        }
    )   
    ->boot();

迁移模型

所有模型都必须从 ( abstract ) PinkCrab\Perique\Migration\Migration 类扩展

class DI_Migration extends Migration {

    /** Services used */
    protected Some_Service $some_service;
    protected App_Config $config;

    /** These would be injected automatically via Perique DI */
    public function __construct(Some_Service $some_service, App_Config $config){
        $this->some_service = $some_service;
        $this->config = $config;
    }

    /** Gets the table name from the App_Config (Perique Config) */
    protected function table_name(): string {
        return $this->config->db_tables('from_app_config');
    }  

    /**Defines the schema for the migration. */
    public function schema( Schema $schema_config ): void {
        $schema_config->column( 'id' )->unsigned_int( 11 )->auto_increment();
        $schema_config->index( 'id' )->primary();    
        $schema_config->column( 'user_ref' )->text( 11 );
        $schema_config->column( 'thingy_ref' )->int( 11 );
    }

    /**
     * Defines the data to be seeded. */
    public function seed( array $seeds ): array {
        return $this->some_service->seed_data();
    }

    /** Is this table dropped on deactivation (Defaults to false). */
    public function drop_on_deactivation(): bool {
        return false;
    }

    /** Drop table on uninstall. (Defaults to false). */
    public function drop_on_uninstall(): bool {
        return true;
    }

    /** Should this migration be seeded on activation. (Defaults to true). */
    public function seed_on_inital_activation(): bool {
        return true;
    }  
}

方法

__construct(...$deps)

@param mixed ...$deps 通过 DI 容器注入

您可以注入任何需要的依赖项，只要它们可以通过类型推断或具有 DI 规则中定义的规则。有关详细信息，请参阅DI 容器文档

table_name(): string

@return string
@required method

此方法应返回表的最终名称。这可以定义为字符串字面量或通过注入的依赖项（例如 'App_Config'）

/**
 * Returns the table name from the apps config.
 *
 * @return string
 */
protected function table_name(): string {
    return $this->config->db_tables('from_app_config');
}  

schema( Schema $schema_config ): void

@param PinkCrab\Table_Builder\Schema $schema
@return null @required method

此方法允许定义表的架构。有关详细信息，请参阅 WPDB 迁移 和 WPDB 表构建器 库

/**
 * Defines the schema for the migration.
 *
 * @param Schema $schema
 * @return void
 */
public function schema( Schema $schema ): void{
    $schema->column('id')->unsigned_int(12)->auto_increment();
    // Define rest of schema
}

seed( array $seeds ): array

@param array<int, array<string, mixed>> $seeds
@return array<int, array<string, mixed>>

返回用于填充表的数据。应返回与列（键）和值对匹配的数组或数组。

/**
 * Defines the schema for the migration.
 *
 * @param array<int, array<string, mixed>> $seeds  
 * @return array<int, array<string, mixed>>
 */
public function seed( array $seeds ): array {
    return [
        ['columnA' => 'value1', 'columnB' => 1.11],
        ['columnA' => 'value2', 'columnB' => 2.22],
    ];
}

drop_on_deactivation(): bool

@return bool

根据返回值，表可以在停用时删除。默认为 FALSE

/**
 * Is this table dropped on deactivation (Defaults to false)
 * @return bool
 */
public function drop_on_deactivation(): bool {
    return true;
}

drop_on_uninstall(): bool

@return bool

根据返回值，表格可以在卸载时被删除。默认为 FALSE

/**
 * Is this table dropped on uninstall (Defaults to false)
 * @return bool
 */
public function drop_on_uninstall(): bool {
    return true;
}

seed_on_inital_activation(): bool

@return bool

根据返回值，将使用定义的种子数据填充表格。默认为 TRUE

表格只填充一次，即使在后续更新中也是如此。

/**
 * Should this migration be seeded on activation. (Defaults to true)
 * @return bool
 */
public function seed_on_inital_activation(): bool {
    return true;
}

变更日志

• 2.0.0 - 支持 Perique V2.*
• 1.0.0 - 首次发布（支持 Perique V1.2-1.4）
• 0.1.1 - 更新依赖项和 GH Action 管道。
• 0.1.0 - 添加文档，创建示例项目。
• 0.1.0-rc2 - 现在使用 Perique 插件生命周期 0.2，并在作为库使用时通过 gitattributes 删除不必要的文件
• 0.1.0-rc1 初步 BETA 版本。