Seeking Feedback: Woo Blueprint

[moon0326]

We’ve recently completed a hack project where we developed a tool for exporting and importing WooCommerce settings, which we’re calling Woo Blueprint for now. Before we decide whether to officially integrate it as a feature, we’d love to get feedback from the community.

Current Capabilities:

• Export/Import: General settings, shipping settings, tax settings, payment gateway settings, plugins, and themes.

• Future Updates: We plan to add support for exporting/importing pages, posts, products, and theme settings.

Current Status:

• Early Stage: The tool is still in its initial phase and might have some bugs.

• UI Improvements: Significant enhancements to the user interface are planned. Please checkout concept videos. The current UI is purely for the demo/testing purposes.

Demo

Export: This pre-configured site includes shipping zones, tax rates, and payment gateway settings.

export.mov

Import: We import the export file into a freshly installed WordPress and WooCommerce site.

Seeking.Feedback.Woo.Blueprint.Team.Ghidorah.1.mp4

Try it out

We’d greatly appreciate any feedback, suggestions, or bug reports. Your input will help us decide if this tool should be officially included. The woocommerce.zip contains the feature. Just upload woocommerce.zip into a suitable test environment or create a Jurassic Ninja site.

1. Complete/skip the core profiler.
2. Configure the site as you like.
3. Navigate to WooCommerce -> Settings -> Advanced -> Blueprint
4. Click on the Export button and save the prompted JSON file on your computer.
5. Create a new site or choose an existing one for testing purposes. Please note that importing a Blueprint will overwrite existing options.
6. On the core profile page, click on the Builder setup button.
7. Upload the exported JSON file from your computer and click on the Import button. The exported settings should be imported into your testing site and you'll be redirected to WooCommerce -> Home
8. Confirm the changes.

Create a Jurassic Ninja site

A Jurassic Ninja site is a temporary test site designed to automatically expire after 24 hours.

1. Visit https://jurassic.ninja/
2. Click on See more options
3. Select WooCommerce and WooCommerce Beta Tester
4. Select blueprint under WooCommerce Beta Tester options.
5. Enter your email and click on Launch single site

Extensibility

Woo Blueprint has two hooks that allow other WooCommerce plugins to extend its functionality and add export/import capabilities for their own settings. More detailed official documentation is planned, but here’s a sneak peek.

Export example: First, we'll define a MyPluginOptionsStep class that handles data structure and validation rules. Then, we'll create ExportMyPluginOptions class that queries and exports the data.

<?php

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

class MyPluginOptionsStep extends Step
{
    /**
     * @var array $options
     */
    private array $options;

    /**
     * @param array $options
     */
    public function __construct(array $options)
    {
        $this->options = $options;
    }

	public static function get_step_label() 
	{
		return "My Plugin Options";
	}

	public static function get_step_description()
	{
		return "Export my plugin options";
	}

    /**
     * Prepare the JSON array for the step.
     *
     * @return array The JSON array.
     */
    public function prepare_json_array(): array
    {
        return [
            "step" => static::get_step_name(),
            "options" => $this->options,
        ];
    }

    /**
     * Get the name of the step.
     *
     * @return string
     */
    public static function get_step_name(): string
    {
        return "myPluginOptions";
    }

    /**
     * Get the schema for the step.
     *
     * @param int $version Optional version number of the schema.
     * @return array The schema array.
     */
    public static function get_schema($version = 1): array
    {
        return [
            "type" => "object",
            "properties" => [
                "step" => [
                    "type" => "string",
                    "enum" => [static::get_step_name()],
                ],
                "options" => [
                    "type" => "object",
                    "additionalProperties" => new \stdClass(),
                ],
            ],
            "required" => ["step", "options"],
        ];
    }
}


class ExportMyPluginOptions implements StepExporter
{
    public function export()
    {
        return new MyPluginOptionsStep([
            "myPluginOption1" => get_option(
                "my_plugin_option_1",
                "default_value_1"
            ),
            "myPluginOption2" => get_option(
                "my_plugin_option_2",
                "default_value_2"
            ),
        ]);
    }

    /**
     * Get the name of the step.
     *
     * @return string
     */
    public function get_step_name()
    {
        return MyPluginOptionsStep::get_step_name();
    }
}


add_action('plugins_loaded', function () {
	add_filter( "wooblueprint_exporters", function (array $exporters) {
		$exporters[] = new ExportMyPluginOptions();
		return $exporters;
	});
}, PHP_INT_MAX );

Output:

{
    "steps": [
        {
            "name": "myPluginOptions",
            "options": {
                "myPluginOption1": "default_value_1",
                "myPluginOption2": "default_value_2"
            }
        }
    ]
}

Import example:

<?php

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

class ImportMyPluginOptions implements StepProcessor
{
    /**
     * The result of the step processing.
     *
     * @var StepProcessorResult $result The result of the step processing.
     */
    private StepProcessorResult $result;

    /**
     * Process the import of WooCommerce tax rates.
     *
     * @param object $schema The schema object containing import details.
     * @return StepProcessorResult
     */
    public function process($schema): StepProcessorResult
    {
        $this->result = StepProcessorResult::success(
            MyPluginOptionsStep::get_step_name()
        );

        foreach ($schema->options as $key => $value) {
            update_option($key, $value);
            $this->result->add_info(
                sprintf("Updated option %s with value %s", $key, $value)
            );
        }

        return $this->result;
    }

    /**
     * Get the class name for the step.
     *
     * @return string
     */
    public function get_step_class(): string
    {
        return MyPluginOptionsStep::class;
    }
}

add_action('plugins_loaded', function () {
	add_filter( "wooblueprint_importers", function (array $importers) {
		$importers[] = new ImportMyPluginOptions();
		return $importers;
	});
}, PHP_INT_MAX );

You can also download blueprint-example.zip demo plugin for testing purposes.

CLI Support

Woo Blueprint comes with import and export CLI commands.

Import

NAME

  wp wc blueprint import

SYNOPSIS

  wp wc blueprint import <schema-path> [--show-messages=<show-messages>]

OPTIONS

  <schema-path>

  [--show-messages=<show-messages>]
  ---
  options:
  - all
  - error
  - info
  - debug
  ---

Export

NAME

  wp wc blueprint export

SYNOPSIS

  wp wc blueprint export <save-to> [--steps=<steps>] [--format=<format>]

OPTIONS

  <save-to>

  [--steps=<steps>]

  [--format=<format>]
  ---
  default: json
  options:
  - json
  - zip
  ---

Feedback

We would love to hear what you think about the blueprint import / export. Please leave your comments below and complete the survey to shape the future direction of the feature..

[theRealRizeo]

I like the concept, its good. Why not have it show in the WordPress tools for import/export and maybe have it as an addon to reduce increasing size of the plugin?

[moon0326]

Thank you @theRealRizeo for the feedback.

Why not have it show in the WordPress tools for import/export and maybe have it as an addon

That's a great suggestion. We'll consider making this feature available as a WP import plugin.

Regarding the size, the Woo team has been working on reducing the plugin size. In fact, the upcoming WooCommerce 9.3 update will have almost a 25% reduction in size (from 20MB to 14.9MB). We'll provide more details once we ship WooCommerce 9.3.

[Rahmon]

Hi @moon0326

I like the idea 👌

I tested the export and import in a multisite environment and the feature worked as expected. However, I couldn't test the extensibility. If I am not wrong, the export example provided contains some typos.

1. "First, we'll define a MyPluginStep MyPluginOptionsStep class that handles data structure and validation rules"
2. class MyPluginOptionsStep extends Step. Should this class extend StepProcessor or StepProcessorResult?
3. When adding the callback function to the filter wooblueprint_exporters, should the $exporters variable receive ExportMyPluginOptions instead of MyCustomExporter?

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

Other than that, it would be nice if the custom exporters options could be checked/unchecked:

[moon0326]

Hi @Rahmon,

Thank you so much for testing it out and providing a suggestion.

I've updated the post to fix the example code snippets. I've also uploaded a sample plugin for easier testing.

Other than that, it would be nice if the custom exporters options could be checked/unchecked:

I've also updated woocommerce.zip to support adding a custom options on the setting page. The relevant code examples are in the blueprint-example.zip file.

To test the changes, follow these steps:

1. Upload and activate woocommerce.zip on a new site.
2. Complete the core profiler.
3. Upload and activate blueprint-example.zip
4. Navigate to WooCommerce -> Settings -> Advanced -> Blueprint
5. Confirm that My Plugin Options has been added.

Please let us know if you have any other suggestions / concerns.

Thank you!

[Rahmon]

It works as expected now. Thanks @moon0326 🙌

Other than that, regarding the option <save-to> in the export wp-cli command, it's necessary to add the filename e.g. wp wc blueprint export ./export.json. I thought only adding a path to a folder would be enough but it wasn't. I am not sure if this is expected if so, it's worth informing that in the documentation.

[moon0326]

@Rahmon Thank you for testing it again! Good to hear it worked without an error :)

Other than that, regarding the option in the export wp-cli command, it's necessary to add the filename

Thank you! I'll update the commands.

[adamziel]

I'm confused about the long-term vision and assumptions. Is this an extension of the PHP implementation of WordPress Playground Blueprints? Or is this a completely separate project? If it's separate – what's the rationale? There seem to be plenty of room to collaborate and build a single, solid library that could eventually become a part of WordPress core.

[moon0326]

@adamziel Good question. I think @adrianduffell or @verofasulo may have a better answer for the long-term vision. You can also checkout pfwcF5-Nq-p2 P2 post.

Personally, I feel that whatever we end up working on, we should always try to leverage what the core provides. I want this project to focus solely on supporting the export and import of Woo-specific settings. Any non-Woo-specific features, like InstallPlugin or similar steps, should be replaced once they are included in the core. This project should offer export/import functionality for WooCommerce core settings, along with an extension point for third-party WooCommerce plugins with a solid UI.

I believe Playground team is already working on export/import feature in the core. When the Playground/Studio team releases the export/import feature in the core, we can adapt to use it as long as we agree on the format (Blueprint).

[adamziel]

I want this project to focus solely on supporting the export and import of Woo-specific settings

@moon0326 sure! And importing/exporting is a great problem to solve. I'm just confused about the data format and I worry others will be confused, too. The word Blueprint is associated with Playground, but the plumbing here seems entirely separate. The JSON structure here is similar, but it wouldn't work as a Playground Blueprint and vice versa. Would you consider either:

• Using a different name and schema to distinguish the two formats, or
• Producing valid Playground Blueprints in this project?

[moon0326]

Producing valid Playground Blueprints in this project?

@adamziel Are we referring to custom steps such as SetWCPaymentGateways, SetWCShipping, and SetWCTaxRates? If so, those are definitely not supported by Blueprint . We could potentially use runPHP or runSQL steps instead. Are there any plans to support custom steps that can be passed down to plugins for handling in the future?

Using a different name and schema to distinguish the two formats, or

I'll talk to the team and see what options we have.

If full compatibility is important, I feel that we can use a different name and potentially have an option to export 100% Blueprint compatible schema.

[adamziel]

Check out the custom step library by @akirk: https://akirk.github.io/playground-step-library/

The idea transfers over to the PHP Blueprints and I want to make it a part of the core library. tl;dr The user writes nice, user-friendly steps and they get preprocessed and expanded as the lower-level steps supported by the core library. If this only needs to work with WooCommerce, you could still maintain all the logic within the plugin and expand the { "step": "myCustomWooStep" } as { "step": "runPHP", "options": { "code": "<?php $obj = new MyHandlerClass(); $obj->doTheWork(); " } }.

[Drivingralle]

I like the concept!
Keeping it as an add-on sounds good to me. In general I think it's easy to install plugins from the repo to keep some features out of the main plugin. Just add hints to it.

Would like to see a solution, that later can be moved over into core as the main maintainer and making it compatible with Playground and other core initiatives.

[moon0326]

Thank you @Drivingralle for the feedback 👍