v1 WordPress Boot Protocol

[adamziel]

What is this PR doing?

Implements a bootWordPress() function aiming to provide a reliable and consistent boot pipeline for every Playground-based app, whether it's a browser app, server app, a VS Code extension, or anything else.

As a nice side-effect, Playground can now boot not just from the custom minified WordPress builds, but also from the official WordPress releases!

Related issue: #1398

How does it work?

bootWordPress() ties together all the pieces from different Playground-based apps. Boot flow diagram demonstrates the idea. A tl;dr pipeline is:

• Mount resources (stage=before WordPress files)
• Unzip WordPress, if that's requested
• Mount resources (stage=before database setup)
• Setup SQLite, MySQL (TODO), or rely on a mounted database
• Run WordPress installer, if the site isn't installed yet

Here's a usage example in a Node.js app:

const requestHandler = await bootWordPress({
	siteUrl: absoluteUrl,
	createPhpInstance() {
		return new NodePHP();
	},
	createPhpRuntime: async () =>
		await NodePHP.loadRuntime(compiledBlueprint.versions.php),
	wordPressZip,
	sqliteIntegrationPluginZip: fetchSqliteIntegration(monitor),
	sapiName: 'cli',
	createFiles: {
		'/internal/shared/ca-bundle.crt':
			rootCertificates.join('\n'),
	},
	phpIniEntries: {
		'openssl.cafile': '/internal/shared/ca-bundle.crt',
		allow_url_fopen: '1',
		disable_functions: '',
	},
	hooks: {
		async beforeWordPressFiles(php) {
			if (args.mountBeforeInstall) {
				mountResources(php, args.mountBeforeInstall);
			}
		},
	},
});

Testing instructions

• Confirm all the CI checks work
• Load the latest nightly official WordPress build into Playground:
  http://localhost:5400/website-server/?php=8.0&wp=http://localhost:5400/plugin-proxy.php?url=https://wordpress.org/nightly-builds/wordpress-latest.zip
• Load the official WordPress 6.5 release into Playground: http://localhost:5400/website-server/?php=8.0&wp=http://localhost:5400/plugin-proxy.php?url=https://wordpress.org/latest.zip
• Confirm Playground CLI still works: Run bun packages/playground/cli/src/cli.ts server --login and confirm it loads an installed WordPress.

Follow-up work

• Replace manual calls to setupPlatformLevelMuPlugins() in unit tests with bootWordPress()
• Add unit tests to confirm boot works with minified WordPress build, official WordPress release, SQLite, MySQL. Test all the BootOptions and confirm PHP.ini directives are used, constants are created etc.
• Remove the createPhpInstance() argument in favor of using just the PHP class – once Breaking: PHP: Remove NodePHP and WebPHP classes in favor of a single "PHP" class #1457 merges
• Figure out storing debug.log in the configureErrorLogging mu-plugin – right now it's stored in /wordpress/wp-content
• Support more database modes: MySQL and custom where Playground relies on db.php brought in from
• Replace hooks with a Mount data type that would have different implementations, like OPFS, Native FS, and Node FS – explorations started in Breaking: PHP: Remove NodePHP and WebPHP classes in favor of a single "PHP" class #1457
• Once the API settles, document the usage for developers

cc @brandonpayton @bgrgicak

[bgrgicak]

I really like the direction of this PR. It will at least make it much easier to understand how Playground is booting.

[adamziel]

There are follow-up tasks, but there's a clear value add already so I'm going to merge this as it is. Let's keep iterating.

(the unit test failures are intermittent)