Blueprints v2 Specification

The previous, TypeScript-powered, Blueprint schema only makes sense in the browser, not in a portable PHP library. Let's design one that does.

The existing Blueprints should keep working as much as possible. The library could detect an outdated syntax and rewrite it to the new one behind the scenes.

Converging with wp-env

wp-env has its own config format.

Let's converge wp-env and Blueprints. This could mean either:

• Transitioning both to the v2 schema format
• Replacing wp-env with Blueprints using Docker as a backend as both solve the same problem

cc @youknowriad @noahtallen

Runtime setup options

The following Blueprint options are for setting up the PHP.wasm runtime. They make sense in Playground and Docker where we need to set up the runtime, but not in native PHP where the runtime is already provided:

{
	"preferredVersions": {
		"php": "7.4"
	},
	"phpExtensionBundles": [
		"kitchen-sink"
	],
	"features": {
		"networking": true
	}
}

An alternative syntax would make that apparent and allow for environment-specific overrides. Here's one idea:

{
	"php": {
		"version": "7.4",
		"extensions": [ "libcurl", "libxml" ],
		"playground": {
			"networking": "fetch()"
		},
		"docker": {
			"networking": false
		}
	}
}

The Native PHP driver could log a message saying that PHP setup instructions are unsupported and were ignored. Optionally, it could verify if the requested PHP version and extensions match.

Open questions

How should PHP.ini setup be defined and how should it work? Should we do an mu-plugin with ini_set()?

Client setup

The following Blueprint options only make sense in the browser where we control the client:

{
	"landingPage": "/wp-admin/",
	"steps": [
		{
			"step": "login",
			"username": "admin",
			"password": "password"
		}
	]
}

What should they do when building a site using the native PHP CLI. Perhaps they could start a server, open a web browser, and open /wp-admin/ in a logged in state? Controlling the browser isn't trivial, so presumably there would be a special, one-time, magic login link with a ?redirect= query arg or so. If so, we could express it as follows:

{
	"onBoot": {
		"openURL": "/wp-admin/",
		"loginAs": "admin"
	}
}

What if we cannot start the server or open the browser, though? For example, we're building in a headless mode. Should the runtime ignore those options? Should it issue a warning? Should these options be runtime-specific?

WordPress setup

The following Blueprint options are responsible for setting up WordPress:

{
	"preferredVersions": {
		"wp": "5.9"
	},
	"steps": [
		{
			"step": "installPlugin",
			"pluginZipFile": {
				"resource": "wordpress.org/plugins",
				"slug": "friends"
			}
		},
		// ... other steps ...
	]
}

They could be bundled under a single top-level key as follows:

{
	"wpVersion": "5.9",
	"steps": [
		{
			"step": "installPlugin",
			"pluginZipFile": {
				"resource": "wordpress.org/plugins",
				"slug": "friends"
			}
		},
		// ... other steps ...
	]
}

Open questions

• In which directory should WordPress be installed? Current working directory? A directory provided by the runtime, e.g. blueprint --target=./build? How should that directory be referenced in steps like writeFile or runPHP? Using special syntax like %DOCROOT%?

Shorthand properties

The step-by-step syntax is overly verbose for most developers, let's make it shorter.

The verbose syntax must remain available as it's the only way to enable reproducible, reliable builds. Some developers may need to correct site options or import content after plugin A was activated but before plugin B was installed and Blueprints should empower them. However, most the developers will never run into nuances like that.

Let's design a schema that's convenient for most use-cases, yet powerful enough to handle nuanced setups.

Here's what it could look like:

{
	"wpVersion": "5.9",
	"plugins": [
		"woocommerce",
		"gutenberg"
	],
	// Optional: all plugins are activated if this isn't specified:
	"activatePlugins": [
		"woocommerce"
	],

	"themes": [ "pendant", "twentytwentythree" ],
	"siteOptions": {
		"blogname": "My new site"
	},
	"wpConfig": {
		"WP_DEBUG": true
	},
	"content": [
		"./theme-unit-test-data.xml",
		"./accessibility-testing-content.xml"
	],
	"files": {
		"wp-content/mu-plugins/0-my-mu-plugin.php": [
			"<?php",
			"add_filter('wp_init', function() {"
			"echo 'Hello, world';",
			"}"
		]
	},
	"steps": [
		// All the above options are translated into steps and prepended to the `steps` array
		// in an opinionated order. Whenever the developer needs to customize the execution
		// order, they could re-express the relevant part of the Blueprint using explicitly-ordered
		// operations.
	]
}

Metadata

WordPress.org could have a Blueprints community space on WordPress.org for folks to share and collaborate on WordPress setups. Similarly to plugins metadata, Blueprints would need to carry some meta information as well.

Here's what a top-level meta key could look like:

{
    "meta": {
        "title": "WooCommerce Developer Environment",
        "description": "A local development environment for WooCommerce that includes WP-CLI.",
        "version": "0.0.8",
        "author": "zieladam",
        "contributors": ["zieladam", "dmsnell"],
        "authorUrl": "https://example.com",
        "donateLink": "https://example.com",
        "tags": ["woocommerce", "developer environment"],
        "license": "GPLv2 or later",
    }
}

Which other fields would be required? Do we need to separate contributors and authors? Should each contributor be able to provide their own website URL?

It could be validated using the JSON Schema below. Note the main Blueprints library could simply ignore the meta key. The validation would happen exclusively during the submission process to the community space.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "meta": {
            "type": "object",
            "properties": {
                "title": {
                    "type": "string"
                },
                "description": {
                    "type": "string",
                    "maxLength": 150
                },
                "version": {
                    "type": "string"
                },
                "author": {
                    "type": "string"
                },
                "authorUrl": {
                    "type": "string",
                    "format": "uri"
                },
                "contributors": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "minItems": 1
                },
                "tags": {
                    "type": "array",
                    "items": {
                        "type": "string",
                        "enum": ["woocommerce", "developer environment"]
                    }
                },
                "donateLink": {
                    "type": "string",
                    "format": "uri"
                },
                "license": {
                    "type": "string"
                }
            },
            "required": ["author", "version", "title", "contributors", "tags", "license"]
        }
    },
    "required": ["meta"]
}

What new features would be useful?

• https://github.com/WordPress/blueprints/issues/32
• https://github.com/WordPress/wordpress-playground/pull/1020
• https://github.com/WordPress/blueprints/issues/46
• Creating a post and being able to reference it later, e.g. redirect to the editor in the openURL section

cc @bgrgicak @dmsnell @mtias @tellyworth @danielbachhuber

The issue names no repository files, tests, or entry points. Start by reviewing the existing Blueprint schema, the compatibility discussion in issue #5, and wp-env's config format, then compare the runtime examples here. Done means an agreed v2 specification covering compatibility, runtime and client behavior, WordPress setup, shorthand properties, and metadata.