338 lines
No EOL
10 KiB
Markdown
338 lines
No EOL
10 KiB
Markdown
<!-- markdownlint-disable MD029 -->
|
||
|
||
# Blueprint
|
||
|
||
这个 PHP Composer 包便于导出和导入与 WordPress Blueprint 兼容的 JSON 格式。它提供了一个坚实的框架，用于与 WordPress 站点无缝集成，并支持可扩展性，使插件能够自定义导出和导入功能。通过 JSON 文件轻松管理站点配置、选项和设置。
|
||
|
||
## 用法
|
||
|
||
Blueprint 允许您将 WordPress 站点配置汇出为 JSON 文件，并将其导入到另一个站点。这可以通过 WP-CLI 或直接在 PHP 中完成，以实现高级自动化或集成。
|
||
|
||
### 导出蓝图
|
||
|
||
您可以使用 `ExportSchema` 类导出站点配置：
|
||
|
||
```php
|
||
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 文件：
|
||
|
||
```php
|
||
use Automattic\WooCommerce\Blueprint\ImportSchema;
|
||
|
||
// 加载 JSON 文件：
|
||
$import_schema = ImportSchema::create_from_file('blueprint.json');
|
||
|
||
// 运行导入：
|
||
$results = $import_schema->import();
|
||
|
||
// $results 是一个数组，包含每个步骤的 StepProcessorResult 对象。
|
||
```
|
||
|
||
### 导入单个步骤（高级）
|
||
|
||
要从 JSON 定义导入单个步骤，请使用 `ImportStep` 类：
|
||
|
||
```php
|
||
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 数据格式](https://wordpress.github.io/wordpress-playground/blueprints/data-format/)。
|
||
|
||
以下是一个 Blueprint JSON 文件的示例：
|
||
|
||
```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（创建步骤）：*
|
||
|
||
```php
|
||
use Automattic\WooCommerce\Blueprint\Steps\SetSiteOptions;
|
||
|
||
$step = new SetSiteOptions([
|
||
'option1' => 'value1',
|
||
'option2' => 'value2',
|
||
]);
|
||
```
|
||
|
||
*JSON（汇出格式）：*
|
||
|
||
```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§ion=blueprint`) 中**不受支持**。它们只能通过 PHP 或 WP-CLI 使用。我们将在未来解决这个问题。
|
||
|
||
1. 创建一个继承 `Automattic\WooCommerce\Blueprint\Exporters\StepExporter` 的新类。
|
||
|
||
```php
|
||
<?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` 实例并返回它。
|
||
|
||
```php
|
||
|
||
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 包注册该导出器。
|
||
|
||
```php
|
||
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 中。
|
||
|
||
输出：
|
||
|
||
```json
|
||
{
|
||
"steps": [
|
||
{
|
||
"name": "setSiteOptions",
|
||
"options": {
|
||
"option1": "value1",
|
||
"option2": "value2"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 示例：为自定义导出器设置别名
|
||
|
||
如果您为同一步骤类型设置了多个导出器，请实现 `HasAlias` 界面，为每个导出器分配一个唯一的别名。这有助于在导出界面或 API 中区分它们。
|
||
|
||
```php
|
||
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';
|
||
}
|
||
}
|
||
```
|
||
|
||
现在您可以使用别名来导出该步骤：
|
||
|
||
```bash
|
||
wp wc blueprint export wc-blueprint.json --steps=profilerOptions
|
||
```
|
||
|
||
## 示例：添加自定义导入器
|
||
|
||
在大多数情况下，默认的导入器已经足够。但是，如果您需要导入默认导入器不支持的数据，则可能需要创建自定义导入器。请注意，这可能会导致生成的蓝图文件与标准的 WordPress Blueprint 格式不兼容。
|
||
|
||
1. 要添加自定义导入器，首先需要定义一个新的步骤。请扩展抽象的 `Step` 类。步骤代表可以导出/导入的操作。
|
||
|
||
```php
|
||
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` 界面。导入器在导入过程中处理步骤数据。
|
||
|
||
```php
|
||
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` 过滤器注册您的导入器：
|
||
|
||
```php
|
||
add_filter('wooblueprint_importers', function(array $importers) {
|
||
$importers[] = new MyCustomImporter();
|
||
return $importers;
|
||
});
|
||
```
|
||
|
||
## 需要更多信息？
|
||
|
||
- 查看 `src/` 目录以获取内建的汇出器、汇入器和步骤。
|
||
- 查看界面：`StepExporter`、`StepProcessor` 和 `Step` 以获取更多详情。
|
||
- 内建步骤可以在 `src/Steps/` 中找到。
|
||
- 对于高级用法，请查看源代码和测试以获取实际例子。 |
