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 👍

[BusinessBloomer]

Not directly related, but I created an issue on Woo GH as WP playground gets stuck on Woo activation: #58718

[Joliamendi]

Hi woocommerce team,

This is a fantastic feature and I'm glad it's available now. But it would be great if the ability to export orders, users, and user reviews were also added to this feature. I hope there is a plan for that.

Thank you for the wonderful work.

[chihsuan]

Thank you for your feedback! @Joliamendi We've received similar requests from other users as well. 👍 We're actively considering adding support for exporting orders, users, and reviews in a future update.

[kennydude]

I do like this feature, however to me this feels more like something that should be a more WordPress core function over a WooCommerce function? Working on making the import/export experience for orders, products etc would be likely more a WooCommerce feeling scope to cover.

[chihsuan]

Thank you for your feedback! @kennydude

You’re right—Blueprints would be a great fit for WordPress Core, and we agree that broader configuration portability benefits the whole ecosystem. Since Core support isn’t available yet, we built the WooCommerce Blueprint feature using the same format as the proposed Core Blueprint. This lets us move faster, gather real-world feedback, and ensure our work can be reused in Core when it’s ready.

We’re also collaborating closely with the Playground team to keep everything aligned. Expanding import/export for orders, products, and other store data is definitely on our roadmap, and your input helps us prioritize what’s most valuable for WooCommerce users.
Thanks again for sharing your perspective!

[j-falk]

When I found out blueprints would be included in WC 9.9 I got very happy since I've played around with Playground and blueprints in there before. Long term I am hoping that blueprints, in a wider WordPress context, fully can replace existing setup bash scripts eg in automated/manual testing and development scenarios.

I think that including blueprints in WooCommerce is a great way to get more people introduced to the thinking around blueprints and hopefully also WordPress playground, testing it properly before most of it maybe can be included in WordPress core, while at the same time provide value in a WooCommerce context right away.

In a way a blueprint export also can be useful in a support and troubleshooting context, since a system report eg includes a lot of information about a site, but eg not all WooCommerce settings. Therefore when helping out in a support ticket context, with a system report and a blueprint export you get an even better overview of a site and it's setup.

Anyhow, I'll summarize my feedback that I got now when I started using the blueprint functionality below, it's both high and low thoughts and let me know if you think I should post some of the feedback somewhere else or break it out in separate issues in any way.

Step descriptions

I would like to be able to add some kind of optional meta descriptions to a step, so I could explain what that step is intended to do. I think that would help with the readability of a blueprint and could be useful eg with how the export functionality works today, because as different settings are exported as separate blueprint steps, then it would be nice to see on the export eg that these are exported payment settings etc. I also think that this text maybe could be visible eg when running an import, eg in the UI or in the command line.

Eg

    {
      "step": "setSiteOptions",
      "description": "WC Payment settings",
      "options": {
        "woocommerce_cod_settings": {
          "enabled": "yes",
          "title": "Cash on delivery",
          "description": "Pay with cash upon delivery.",
          "instructions": "Pay with cash upon delivery.",
          "enable_for_methods": [],
          "enable_for_virtual": "yes"
        }
      }
    },

WP CLI import through url's

Being able to import and export blueprints through wp cli is great. However I would like to be able to import a blueprint also through a url, similar to how the command "wp plugin install" lets you use a url instead of a path.

Tax and shipping exported as a runSql step does not make it portable

If I export tax and shipping right now, they are exported as runSql steps. See example below,

    {
      "step": "runSql",
      "sql": {
        "resource": "literal",
        "name": "schema.sql",
        "contents": "replace into `iwpc297_woocommerce_tax_rates` (`tax_rate_id`, `tax_rate_country`, `tax_rate_state`, `tax_rate`, `tax_rate_name`, `tax_rate_priority`, `tax_rate_compound`, `tax_rate_shipping`, `tax_rate_order`, `tax_rate_class`) VALUES ('1', 'SE', '', '25.0000', 'VAT 25%', '1', '0', '1', '0', '');"
      }
    },
    {
      "step": "runSql",
      "sql": {
        "resource": "literal",
        "name": "schema.sql",
        "contents": "replace into `iwpc297_woocommerce_tax_rates` (`tax_rate_id`, `tax_rate_country`, `tax_rate_state`, `tax_rate`, `tax_rate_name`, `tax_rate_priority`, `tax_rate_compound`, `tax_rate_shipping`, `tax_rate_order`, `tax_rate_class`) VALUES ('2', 'SE', '', '12.0000', 'VAT 12%', '1', '0', '1', '0', 'reduced-rate');"
      }
    },
    {
      "step": "runSql",
      "sql": {
        "resource": "literal",
        "name": "schema.sql",
        "contents": "replace into `iwpc297_woocommerce_tax_rates` (`tax_rate_id`, `tax_rate_country`, `tax_rate_state`, `tax_rate`, `tax_rate_name`, `tax_rate_priority`, `tax_rate_compound`, `tax_rate_shipping`, `tax_rate_order`, `tax_rate_class`) VALUES ('3', 'SE', '', '0.0000', 'VAT 0%', '1', '0', '1', '0', 'zero-rate');"
      }
    },

However, since the site that I might want to import this too could have a totally different table prefix, then this would not work at all right? Obviously it would be nicest to eg have some kind of custom WC importer step where you could define tax and shipping options in a json format similar as with settings. But if that is too complicated maybe a better approach would be to try to use a runPHP step instead of runSql? Or if you would allow wp-cli steps, then it could be done through that instead?

Support for more blueprint importers

It would be great if it was possible to run blueprint steps on import like wp-cli, importWxr and updateUserMeta.

Possible to define wp-cli commands as an array instead of separate steps

If you would allow wp-cli steps I would love if it was possible to define multiple commands as an array instead of having them as separate steps. Because if you have many wp cli commands that you want to run, then it becomes very many steps or if you try to combine it to one big command, then it is not readable. So instead of having,

    {
      "step": "wp-cli",
      "command": "wp wc shop_coupon create --code=\"fixed-10\" --amount=\"10\" --discount_type=\"fixed_cart\" --user=\"admin\""
    },
    {
      "step": "wp-cli",
      "command": "wp wc shop_coupon create --code=\"percent-10\" --amount=\"10\" --discount_type=\"percent\" --user=\"admin\""
    },
    {
      "step": "wp-cli",
      "command": "wp wc shop_coupon create --code=\"percent-100\" --amount=\"100\" --discount_type=\"percent\" --free_shipping=true --user=\"admin\""
    },
    {
      "step": "wp-cli",
      "command": "wp wc shop_coupon create --code=\"totalfreeshipping\" --amount=\"0\" --discount_type=\"fixed_cart\" --free_shipping=true --user=\"admin\""
    },

you would instead be able to define it as a step like this

    {
      "step": "wp-cli",
      "description": "Create WC coupons",
      "commands": [
        "wp wc shop_coupon create --code=\"fixed-10\" --amount=\"10\" --discount_type=\"fixed_cart\" --user=\"admin\"",
        "wp wc shop_coupon create --code=\"percent-10\" --amount=\"10\" --discount_type=\"percent\" --user=\"admin\"",
        "wp wc shop_coupon create --code=\"percent-100\" --amount=\"100\" --discount_type=\"percent\" --free_shipping=true --user=\"admin\"",
        "wp wc shop_coupon create --code=\"totalfreeshipping\" --amount=\"0\" --discount_type=\"fixed_cart\" --free_shipping=true --user=\"admin\""
      ]
    },

[chihsuan]

Thank you so much for your detailed and thoughtful feedback! @j-falk We really appreciate you taking the time to share both your experience and suggestions.

• Blueprints in WooCommerce & Core: We’re glad you’re excited about Blueprints in WC 9.9! As you mentioned, our goal is to introduce more people to Blueprints and Playground, gather real-world feedback, and provide immediate value in WooCommerce.
• Step Descriptions: Great suggestion! Adding optional meta descriptions to steps would definitely improve readability and usability, especially for complex Blueprints.
• WP CLI Import via URL: That’s a smart idea. Supporting URL-based imports (like wp plugin install) would make automation and scripting even easier. We’ll look into what’s possible here. That would require more security measures, though.
• Tax & Shipping as runSql Steps: You’re absolutely right—using raw SQL with hardcoded table prefixes isn’t portable now. We agree that a more structured, JSON-based approach (or a custom importer step) would be ideal. We’ll also explore alternatives using the AST MySQL parser to achieve this or rely on Blueprints v2 runner (if it has this capability).
• Support for More Importers: Yeah, we should definitely look into supporting more importers/steps. We'll likely migrate the current woo blueprint importer to the new Core v2 runner so we can leverage its features.
• Batching WP-CLI Commands: Allowing multiple WP-CLI commands in a single step (as an array) is a great idea for readability and maintainability. We’ll take this into account as we improve the step format.

Thanks again for helping us make Blueprints better for everyone!

cc @adamziel there are several valuable suggestions here regarding the blueprint functionality.