Blueprints v2 all-PHP Runner

[adamziel]

Blueprints v2 runner

Warning

This is an early alpha version. Proceed with caution!

This PR ships a reference implementation of a subset of the Blueprints version 2 spec. It consists of:

• A CLI runner tool (bundled as .phar) for easy consumption
• A PHP library that can be integrated in other PHP software

These tools are compatible with PHP 7.2+ on Mac, Linux, Windows and require no PHP extensions. Libraries for processing ZIP, HTTP, XML, HTML, and Git are included.

This huge PR also:

• Downgrades the codebase to PHP 7.2
• Gets the unit tests to run
• Resolves a number of bugs in most components (HttpClient, Zip, Filesystem, ByteStream, and more)
• Introduces an all-php TCP server for testing

Splitting it into atomic changes and documenting them could easily take a week. Therefore I apologize, but I am not going to do that. Let's treat it as the new initial commit and apply atomic changes from this point forward.

Remaining work

First and foremost: stabilize this runner with a large and meaningful suite of tests.

Other than that:

In this PR

• Remove the buggy, experimental HTTP cache support from this PR

Independently of this PR

• Consolidate and prioritize the @TODO comments in a way that can be discussed and tracked
• A large set of unit tests for the HTTP client covering all sorts of use-cases
• (nice to have) An actual, reliable HTTP cache implementation for faster execution
• A unit test suite running the 100 most popular Blueprints

Out of scope until the baseline functionality works

• Integrate Data Liberation data importers. The runner uses the HumanMade/WordPress-importer for now.

Using it

Download blueprints.phar from the latest alpha release and follow the instructions there.

For running from source, use this command:

> php ./components/Blueprints/bin/blueprint.php
WordPress Blueprint Runner
Usage: php blueprint.php exec <blueprint> --site-url=<url> --site-path=<path> [options]

Positional arguments:
  blueprint            Path / URL / DataReference to the blueprint (required)

Options:
  -u, --site-url <value>           Public site URL (https://example.com)
      --site-path <value>          Target directory with WordPress install context) (required)
  -x, --execution-context <value>  Source directory with Blueprint context files
  -m, --mode <value>               Execution mode (create|apply) (default 'create')
  -d, --db-engine <value>          Database engine (mysql|sqlite) (default 'mysql')
      --db-host <value>            MySQL host (default 'localhost')
      --db-user <value>            MySQL user (default 'root')
      --db-pass <value>            MySQL password (default '')
      --db-name <value>            MySQL database (default 'wordpress')
  -p, --db-path <value>            SQLite file path (default 'wp.db')
      --dry-run                    Don’t change anything, just validate (default false)
  -h, --help                       Show full help (default false)
  -V, --version                    Show version (default false)

Examples:
  php blueprint.php exec my-blueprint.json --site-url https://mysite.test --site-path /var/www/mysite.com
  php blueprint.php exec my-blueprint.json --execution-context /var/www --site-url https://mysite.test --mode apply --site-path ./site

Here's an example of using it to create a new site (with a complex v1 Blueprint to showcase compatibility):

> php ./components/Blueprints/bin/blueprint.php exec https://github.com/wordpress/blueprints/blob/trunk/blueprints/stylish-press/blueprint.json --site-path=./newsite/ --site-url=http://127.0.0.1:4356 --db-engine=sqlite --mode create
Creating a new site
  Site URL:  http://127.0.0.1:4356
  Site path: /www/php-toolkit/untracked/newsite
  Blueprint: /www/php-toolkit/untracked/blueprint.json
[100%] Complete                                                                
✔ Blueprint successfully executed.

CleanShot.2025-05-12.at.21.17.02.mp4

The command above created a new WordPress site in a newsite directory. Here's what it did under the hood:

• Validated Blueprint v1 and transpiled it to v2 schema
• Reported live progress
• Downloaded files in parallel
• Imported content and media files
• Ran code in subprocesses

With another Blueprint, you could also create new post types, source data directly from a git repo, and more.

Scripts

Bundle blueprints.phar

To build a single blueprints.phar executable, install box and run:

composer build-blueprints-phar
# Under the hood it runs:
#    box compile -c phar-box.json
# and recreates dist/blueprints.phar

Regenerate JSON Schema based on TypeScript types

This PR ships a copy of the Blueprints v2 proposal including the TypeScript types. To regenerate the JSON schema used to validate input Blueprints, run:

# Install dependencies
npm install
composer regenerate-json-schema

# Under the hood, it runs:
#     node components/Blueprints/json-schema/regenerate-schema.ts
# and recreates components/Blueprints/json-schema/blueprint-v2-schema.json