woocommerce/packages/php/blueprint/zh-cn/README.md

Blueprint

这个 PHP Composer 包便于导出和导入与 WordPress Blueprint 兼容的 JSON 格式。它提供了一个坚实的框架，用于与 WordPress 站点无缝集成，并支持可扩展性，使插件能够自定义导出和导入功能。通过 JSON 文件轻松管理站点配置、选项和设置。

用法

Blueprint 允许您将 WordPress 站点配置汇出为 JSON 文件，并将其导入到另一个站点。这可以通过 WP-CLI 或直接在 PHP 中完成，以实现高级自动化或集成。

导出蓝图

您可以使用 ExportSchema 类导出站点配置：

use Automattic\WooCommerce\Blueprint\ExportSchema;

// 可选地传入自定义导出器，或留空以使用内置导出器。
$export_schema = new ExportSchema();

// 导出所有步骤：
$schema = $export_schema->export();

// 仅导出特定步骤：
// $schema = $export_schema->export(['installPlugin', 'activateTheme']);

// 保存到文件：
file_put_contents('blueprint.json', json_encode($schema, JSON_PRETTY_PRINT));

导入蓝图

您可以使用 ImportSchema 类导入先前汇出的 JSON 文件：

use Automattic\WooCommerce\Blueprint\ImportSchema;

// 加载 JSON 文件：
$import_schema = ImportSchema::create_from_file('blueprint.json');

// 运行导入：
$results = $import_schema->import();

// $results 是一个数组，包含每个步骤的 StepProcessorResult 对象。

导入单个步骤（高级）

要从 JSON 定义导入单个步骤，请使用 ImportStep 类：

use Automattic\WooCommerce\Blueprint\ImportStep;

$step_definition = json_decode(
  '{"step":"setSiteOptions","options":{"option1":"value1"}}'
);
$import_step = new ImportStep($step_definition);
$result = $import_step->import();

数据格式

一个 Blueprint JSON 文件包含配置 WordPress 或 WooCommerce 站点所需的所有信息。该格式完全兼容 WordPress Blueprint 数据格式。

以下是一个 Blueprint JSON 文件的示例：

{
  "landingPage": "/wp-admin/admin.php?page=wc-admin",
  "steps": [
    {
      "step": "setSiteOptions",
      "options": {
        "woocommerce_store_address": "123 Main St",
        "woocommerce_store_address_2": "Suite 100",
        "woocommerce_store_city": "Sample City",
        "woocommerce_default_country": "US:CA",
        "woocommerce_store_postcode": "90001",
        "woocommerce_all_except_countries": [],
        "woocommerce_specific_allowed_countries": [],
        "woocommerce_specific_ship_to_countries": [],
        "woocommerce_calc_taxes": "yes"
      }
    }
  ]
}

您可以根据需要包含任意数量的步骤，每个步骤代表 WooCommerce 或 WordPress 配置的不同部分。这是导出时获得的格式，也是导入 Blueprint 时需要提供的格式。

内置步骤

步骤是一个独立自包含的操作，可导出至或从 Blueprint JSON 文件导入。步骤是 Blueprint 导出/导入流程的基础构建单元。

Blueprint 为常见的站点操作提供了多个内置步骤：

步骤	描述
installPlugin	安装 WordPress 插件
activatePlugin	激活 WordPress 插件
installTheme	安装 WordPress 主题
activateTheme	激活 WordPress 主题
setSiteOptions	设置 WordPress 站点选项
runSql	运行自定义 SQL 查询

如：SetSiteOptions 步骤

PHP（创建步骤）：

use Automattic\WooCommerce\Blueprint\Steps\SetSiteOptions;

$step = new SetSiteOptions([
    'option1' => 'value1',
    'option2' => 'value2',
]);

JSON（汇出格式）：

{
  "step": "setSiteOptions",
  "options": {
    "option1": "value1",
    "option2": "value2"
  }
}

扩展 Blueprint

您可以通过添加自定义汇出器、导入器或步骤来扩展 Blueprint。这允许您支持新的数据类型或自定义站点逻辑。例如，您可以添加一个自定义汇出器来汇出您的插件配置。

钩子

钩子	描述
wooblueprint_exporters	向汇出流程添加自定义汇出器
wooblueprint_importers	向汇入流程添加自定义汇入器

示例：添加自定义导出器

Important

通过 wooblueprint_exporters 过滤器添加的自定义导出器目前在 WooCommerce Blueprint 管理员界面 (/wp-admin/admin.php?page=wc-settings&tab=advanced&section=blueprint) 中不受支持。它们只能通过 PHP 或 WP-CLI 使用。我们将在未来解决这个问题。

1. 创建一个继承 Automattic\WooCommerce\Blueprint\Exporters\StepExporter 的新类。

<?php

use Automattic\WooCommerce\Blueprint\Exporters\StepExporter;
use Automattic\WooCommerce\Blueprint\Steps\Step;

class MyCustomExporter extends StepExporter {
    public function export( array $data ): Step {
       
    }
    
    public function get_step_name() {
        return 'setSiteOptions';
    }

}

2. export 方法应返回一个 Step 对象。
3. 在此示例中，我们使用内置的 SetSiteOptions 步骤。
4. 创建一个新的 SetSiteOptions 实例并返回它。

use Automattic\WooCommerce\Blueprint\Exporters\StepExporter;
use Automattic\WooCommerce\Blueprint\Steps\Step;

class MyCustomExporter extends StepExporter {
    public function export(): Step {
        $data = [
            'option1' => get_option( 'option1', 'value1' ),
            'option2' => get_option( 'option2', 'value2' ),
       ];
       return new SetSiteOptions( $data );
    }
    
    public function get_step_name() {
        return SetSiteOptions::get_step_name();
    }
}

5. 最后，通过 wooblueprint_exporters 过滤器向 Blueprint 包注册该导出器。

use Automattic\WooCommerce\Blueprint\Exporters\StepExporter;
use Automattic\WooCommerce\Blueprint\Steps\Step;

class MyCustomExporter extends StepExporter {
    public function export(): Step {
        $data = [
            'option1' => get_option( 'option1', 'value1' ),
            'option2' => get_option( 'option2', 'value2' ),
       ];
       return new SetSiteOptions( $data );
    }
    
    public function get_step_name() {
        return SetSiteOptions::get_step_name();
    }
}

add_filter( 'wooblueprint_exporters', function( array $exporters ) {
    $exporters[] = new MyCustomExporter();
    return $exporters;
} );

导出 Blueprint 时，将调用 MyCustomExporter 类，并且 SetSiteOptions 步骤将被添加到 Blueprint JSON 中。

输出：

{
    "steps": [
        {
            "name": "setSiteOptions",
            "options": {
                "option1": "value1",
                "option2": "value2"
            }
        }
    ]
}

示例：为自定义导出器设置别名

如果您为同一步骤类型设置了多个导出器，请实现 HasAlias 界面，为每个导出器分配一个唯一的别名。这有助于在导出界面或 API 中区分它们。

use Automattic\WooCommerce\Blueprint\Exporters\StepExporter;
use Automattic\WooCommerce\Blueprint\Exporters\HasAlias;
use Automattic\WooCommerce\Blueprint\Steps\SetSiteOptions;

class ProfilerOptionsExporter implements StepExporter, HasAlias {
    public function export() {
        // ...
    }
    public function get_step_name() {
        return SetSiteOptions::get_step_name();
    }
    public function check_step_capabilities(): bool {
        return current_user_can('manage_options');
    }
    public function get_alias() {
        return 'profilerOptions';
    }
}

现在您可以使用别名来导出该步骤：

wp wc blueprint export wc-blueprint.json --steps=profilerOptions

示例：添加自定义导入器

在大多数情况下，默认的导入器已经足够。但是，如果您需要导入默认导入器不支持的数据，则可能需要创建自定义导入器。请注意，这可能会导致生成的蓝图文件与标准的 WordPress Blueprint 格式不兼容。

1. 要添加自定义导入器，首先需要定义一个新的步骤。请扩展抽象的 Step 类。步骤代表可以导出/导入的操作。

use Automattic\WooCommerce\Blueprint\Steps\Step;

class MyCustomStep extends Step {
    private $my_data;
    public function __construct($my_data) {
        $this->my_data = $my_data;
    }
    public static function get_step_name(): string {
        return 'myCustomStep';
    }
    public static function get_schema(int $version = 1): array {
        return [
            'type' => 'object',
            'properties' => [
                'step' => [ 'type' => 'string', 'enum' => [static::get_step_name()] ],
                'myData' => [ 'type' => 'string' ],
            ],
            'required' => ['step', 'myData'],
        ];
    }
    public function prepare_json_array(): array {
        return [
            'step' => static::get_step_name(),
            'myData' => $this->my_data,
        ];
    }
}

2. 然后，您需要实现 StepProcessor 界面。导入器在导入过程中处理步骤数据。

use Automattic\WooCommerce\Blueprint\StepProcessor;
use Automattic\WooCommerce\Blueprint\StepProcessorResult;

class MyCustomImporter implements StepProcessor {
    public function process($schema): StepProcessorResult {
        // 在此处编写您的导入逻辑
        return StepProcessorResult::success(MyCustomStep::get_step_name());
    }
    public function get_step_class(): string {
        return MyCustomStep::class;
    }
    public function check_step_capabilities($schema): bool {
        return current_user_can('manage_options');
    }
}

3. 使用 wooblueprint_importers 过滤器注册您的导入器：

add_filter('wooblueprint_importers', function(array $importers) {
    $importers[] = new MyCustomImporter();
    return $importers;
});

需要更多信息？

• 查看 src/ 目录以获取内建的汇出器、汇入器和步骤。
• 查看界面：StepExporter、StepProcessor 和 Step 以获取更多详情。
• 内建步骤可以在 src/Steps/ 中找到。
• 对于高级用法，请查看源代码和测试以获取实际例子。