wp-php-toolkit/blueprints

Blueprints component for WordPress.

v0.8.0 2026-05-18 15:07 UTC

Requires

• php: >=7.2
• wp-php-toolkit/bytestream: ^0.8
• wp-php-toolkit/filesystem: ^0.8
• wp-php-toolkit/http-client: ^0.8
• wp-php-toolkit/xml: ^0.8
• wp-php-toolkit/zip: ^0.8

GPL-2.0-or-later

• Adam Zielinski
• WordPress Team

• wordpress
• php-toolkit

README

slug	blueprints
title	Blueprints
install	wp-php-toolkit/blueprints
see_also	filesystem | Filesystem | Prepare files and fixtures before applying site setup steps. httpclient | HttpClient | Download packages or source data as part of provisioning workflows. cli | CLI | Wrap repeatable blueprint operations in a small command.

Declarative WordPress site provisioning. Write a Blueprint JSON document for plugins, options, content, and setup steps; let the runner execute it.

Why this exists

A WordPress environment is more than a database dump. It can require a specific core version, plugins, themes, site options, uploaded files, content, and setup steps. Rebuilding that by hand makes demos, tests, bug reports, workshops, and CI fixtures drift over time.

The Blueprints component treats site setup as data. A blueprint JSON document describes the desired steps, and the runner applies them to either a new WordPress install or an existing one. The validator exists because user-authored JSON needs clear, path-specific errors rather than generic schema failures.

RunnerConfiguration separates the web root from the WordPress core directory, since real hosts often put them in different places. Both paths are explicit on the runner, never inferred.

Blueprints can create a new WordPress install (download core, set up the database, apply steps) or apply to an existing site. Creating a fresh install needs filesystem access this in-browser runtime doesn't have, so the runnable snippets focus on APPLY_TO_EXISTING_SITE.

Configure a runner for an existing site

RunnerConfiguration is a fluent builder. A real run also needs a blueprint reference; this snippet shows the site-target fields in isolation.

<?php
require '/php-toolkit/vendor/autoload.php';

use WordPress\Blueprints\Runner;
use WordPress\Blueprints\RunnerConfiguration;

$config = ( new RunnerConfiguration() )
	->set_execution_mode( Runner::EXECUTION_MODE_APPLY_TO_EXISTING_SITE )
	->set_target_site_root( '/wordpress' )
	->set_target_site_url( 'http://playground.test/' );

echo "mode: " . $config->get_execution_mode() . "\n";
echo "root: " . $config->get_target_site_root() . "\n";
echo "url:  " . $config->get_target_site_url() . "\n";

mode: apply-to-existing-site
root: /wordpress
url:  http://playground.test/

Generate blueprint JSON from PHP

CI jobs and tests stay clearer when PHP builds the blueprint from data instead of hand-writing JSON. Keep the structure plain: version, top-level collections such as plugins, and any imperative steps under the schema's step lists.

<?php
require '/php-toolkit/vendor/autoload.php';

$site_name = 'Demo Site';
$plugins   = array( 'gutenberg', 'classic-editor' );

$blueprint = array(
	'version' => 2,
	'plugins' => array(),
	'additionalStepsAfterExecution' => array(
		array(
			'step'    => 'setSiteOptions',
			'options' => array(
				'blogname'            => $site_name,
				'permalink_structure' => '/%postname%/',
				'show_on_front'       => 'page',
			),
		),
	),
);

foreach ( $plugins as $slug ) {
	$blueprint['plugins'][] = array(
		'source' => $slug,
		'active' => true,
	);
}

echo json_encode( $blueprint, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES ) . "\n";

{
    "version": 2,
    "plugins": [
        {
            "source": "gutenberg",
            "active": true
        },
        {
            "source": "classic-editor",
            "active": true
        }
    ],
    "additionalStepsAfterExecution": [
        {
            "step": "setSiteOptions",
            "options": {
                "blogname": "Demo Site",
                "permalink_structure": "/%postname%/",
                "show_on_front": "page"
            }
        }
    ]
}

Validate before running

The schema validator returns a human-readable ValidationError instead of a generic "does not match schema" failure. Use it before handing user-authored JSON to a runner.

<?php
require '/php-toolkit/vendor/autoload.php';

use WordPress\Blueprints\Validator\HumanFriendlySchemaValidator;

$schema = array(
	'type'       => 'object',
	'required'   => array( 'version', 'steps' ),
	'properties' => array(
		'version' => array( 'type' => 'integer' ),
		'steps'   => array(
			'type'  => 'array',
			'items' => array(
				'type'       => 'object',
				'required'   => array( 'step' ),
				'properties' => array(
					'step' => array( 'type' => 'string' ),
				),
			),
		),
	),
);

$blueprint = array(
	'version' => 2,
	'steps'   => array(
		array( 'source' => 'https://downloads.wordpress.org/plugin/gutenberg.zip' ),
	),
);

$error = ( new HumanFriendlySchemaValidator( $schema ) )->validate( $blueprint );
if ( null === $error ) {
	echo "valid\n";
} else {
	echo $error->get_pretty_path() . ": " . $error->message . "\n";
}

Blueprint root["steps"][0]: Missing required field: step.

The Blueprint JSON shape

A Blueprint v2 document starts with a version field, then uses top-level declarations such as plugins, themes, content, and the schema's step lists. Imperative steps use a "step" discriminator plus step-specific fields.

{
  "version": 2,
  "plugins": [
    { "source": "gutenberg", "active": true }
  ],
  "additionalStepsAfterExecution": [
    { "step": "setSiteOptions",
      "options": {
        "blogname": "Demo Site",
        "permalink_structure": "/%postname%/"
      } },
    { "step": "installPlugin",
      "source": "https://downloads.wordpress.org/plugin/classic-editor.zip" },
    { "step": "activatePlugin",
      "pluginPath": "classic-editor/classic-editor.php" }
  ]
}