Add CLI support for custom PHP extensions

Author: adamziel

packages/playground/cli/README.md

@@ -94,13 +94,50 @@ The `server` command supports the following optional arguments:
 - `--wordpress-install-mode <mode>`: Control how Playground prepares WordPress before booting. Defaults to `download-and-install`. Other options: `install-from-existing-files` (install using files you've mounted), `install-from-existing-files-if-needed` (same, but skip setup when an existing site is detected), and `do-not-attempt-installing` (never download or install WordPress).
 - `--skip-sqlite-setup`: Do not set up the SQLite database integration.
 - `--verbosity`: Output logs and progress messages (choices: "quiet", "normal", "debug"). Defaults to "normal".
-
 - `--debug`: Print the PHP error log if an error occurs during boot.
 - `--follow-symlinks`: Allow Playground to follow symlinks by automatically mounting symlinked directories and files encountered in mounted directories. ⚠️ Warning: Following symlinks will expose files outside mounted directories to Playground and could be a security risk.
 - `--workers=<n|auto>`: Number of request-handling worker threads. Pass a positive integer, or `auto` to use one worker per CPU core (minus one). Defaults to `min(6, cpus-1)`. Useful for multi-client workloads (e.g. parallel e2e suites) that need more than 6 in-flight requests.
 - `--experimental-multi-worker`: Deprecated. Use `--workers=<n|auto>` instead. The value of this flag is ignored.
 - `--phpmyadmin[=<path>]`: Install phpMyAdmin for database management. The phpMyAdmin URL will be printed after boot. Optionally specify a custom URL path (default: `/phpmyadmin`).
 - `--internal-cookie-store`: Enables Playground's internal cookie handling. When active, Playground uses an HttpCookieStore to manage and persist cookies across requests. If disabled, cookies are handled externally, like by a browser in Node.js.
+- `--php-extension=<manifest>`: Load a custom PHP.wasm extension manifest before PHP starts. Accepts local paths, `file:` URLs, and `http(s):` URLs. Can be used multiple times.
+- `--php-extension-config=<path>`: Load a JSON extension config before PHP starts. Use this for direct `.so` URLs or extension-specific `iniEntries` and `env` settings. Can be used multiple times.
+
+### Loading Custom PHP.wasm Extensions
+
+Custom extensions built with `@php-wasm/compile-extension` can be loaded with
+`--php-extension`:
+
+```bash
+npx @wp-playground/cli@latest server \
+	--php=8.4 \
+	--php-extension=./dist/wp_mysql_parser/manifest.json
+```
+
+The manifest selects the `.so` artifact matching the active PHP version and can
+stage sidecar files before PHP starts. External extensions are JSPI-only, so use
+Node.js 23 or newer.
+
+Use `--php-extension-config` when the extension needs more runtime settings:
+
+```json
+{
+	"source": {
+		"format": "manifest",
+		"manifestUrl": "./dist/spx/manifest.json"
+	},
+	"iniEntries": {
+		"spx.http_enabled": "1"
+	},
+	"env": {
+		"SPX_DATA_DIR": "/internal/shared/spx/data"
+	}
+}
+```
+
+```bash
+npx @wp-playground/cli@latest server --php-extension-config=./spx.json
+```
 
 ## Need some help with the CLI?
 

packages/playground/cli/src/blueprints-v1/blueprints-v1-handler.ts

@@ -32,7 +32,7 @@ import {
 	mergeDefinedConstants,
 } from '../run-cli';
 import type { CLIOutput } from '../cli-output';
-import { legacyPHPExtensionsObjectToExtensionsArray } from '../php-extensions';
+import { cliExtensionArgsToExtensionsArray } from '../php-extensions';
 
 /**
  * Boots Playground CLI workers using Blueprint version 1.
@@ -198,7 +198,7 @@ export class BlueprintsV1Handler {
 			processId: worker.processId,
 			followSymlinks: this.args.followSymlinks === true,
 			trace: this.args.experimentalTrace === true,
-			extensions: legacyPHPExtensionsObjectToExtensionsArray(this.args),
+			extensions: cliExtensionArgsToExtensionsArray(this.args),
 			nativeInternalDirPath,
 			pathAliases: this.args.pathAliases,
 		});

packages/playground/cli/src/blueprints-v2/blueprints-v2-handler.ts

@@ -13,7 +13,7 @@ import {
 	mergeDefinedConstants,
 } from '../run-cli';
 import type { CLIOutput } from '../cli-output';
-import { legacyPHPExtensionsObjectToExtensionsArray } from '../php-extensions';
+import { cliExtensionArgsToExtensionsArray } from '../php-extensions';
 
 /**
  * Boots Playground CLI workers using Blueprint version 2.
@@ -83,7 +83,7 @@ export class BlueprintsV2Handler {
 			siteUrl: this.siteUrl,
 			processId: worker.processId,
 			trace: this.args.verbosity === 'debug',
-			extensions: legacyPHPExtensionsObjectToExtensionsArray(this.args),
+			extensions: cliExtensionArgsToExtensionsArray(this.args),
 			nativeInternalDirPath,
 			mountsBeforeWpInstall: this.args['mount-before-install'] || [],
 			mountsAfterWpInstall: this.args.mount || [],

packages/playground/cli/src/php-extensions.ts

@@ -1,24 +1,32 @@
-import type { PHPExtension, XdebugOptions } from '@php-wasm/node';
+import { readFileSync } from 'node:fs';
+import type {
+	PHPExtension,
+	RuntimePHPExtensionSource,
+	XdebugOptions,
+} from '@php-wasm/node';
 
 /**
- * Converts the legacy Playground CLI extension options object into the runtime
- * `extensions` array.
+ * Converts Playground CLI extension options into the runtime `extensions`
+ * array.
  *
- * The CLI still receives extensions as individual options: `intl`, `redis`,
- * `memcached`, and `xdebug`. The PHP runtime no longer has separate `with*`
- * entry points for new callers; it expects one array that can contain built-in
- * extension names and, elsewhere, external extension sources. This function is
- * the CLI boundary between those two shapes.
+ * The CLI receives built-in extensions as individual options (`intl`, `redis`,
+ * `memcached`, and `xdebug`) and external extensions as manifest/config paths.
+ * The PHP runtime expects one array that can contain built-in names and
+ * external extension sources side by side.
  *
  * Xdebug is the only CLI extension here with options. A plain `true` becomes
  * the built-in `xdebug` request, while an object preserves the Xdebug settings
  * and passes them through to the Node runtime.
  */
-export function legacyPHPExtensionsObjectToExtensionsArray(args: {
+export function cliExtensionArgsToExtensionsArray(args: {
 	intl?: boolean;
 	redis?: boolean;
 	memcached?: boolean;
 	xdebug?: boolean | XdebugOptions;
+	phpExtension?: string[];
+	'php-extension'?: string[];
+	phpExtensionConfig?: string[];
+	'php-extension-config'?: string[];
 }): PHPExtension[] {
 	const extensions: PHPExtension[] = [];
 	if (args.intl) {
@@ -37,5 +45,89 @@ export function legacyPHPExtensionsObjectToExtensionsArray(args: {
 				: 'xdebug'
 		);
 	}
+	for (const manifestUrl of getArrayOption(args, 'phpExtension')) {
+		extensions.push({
+			source: {
+				format: 'manifest',
+				manifestUrl,
+			},
+		});
+	}
+	for (const configPath of getArrayOption(args, 'phpExtensionConfig')) {
+		extensions.push(readPHPExtensionConfig(configPath));
+	}
 	return extensions;
 }
+
+export function readPHPExtensionConfig(
+	configPath: string
+): RuntimePHPExtensionSource {
+	let config: unknown;
+	try {
+		config = JSON.parse(readFileSync(configPath, 'utf8'));
+	} catch (error) {
+		throw new Error(`Could not read PHP extension config: ${configPath}`, {
+			cause: error,
+		});
+	}
+
+	if (!isRecord(config) || !isRecord(config['source'])) {
+		throw new Error(
+			`Invalid PHP extension config: ${configPath}. Expected an object with a source field.`
+		);
+	}
+
+	const source = config['source'];
+	if (source['format'] === 'so') {
+		throw new Error(
+			`Invalid PHP extension config: ${configPath}. The CLI cannot load direct bytes; use a manifest or URL source.`
+		);
+	}
+	if (source['format'] === 'url') {
+		if (typeof source['url'] !== 'string') {
+			throw new Error(
+				`Invalid PHP extension config: ${configPath}. A URL source requires a string url.`
+			);
+		}
+		return config as RuntimePHPExtensionSource;
+	}
+	if (source['format'] === 'manifest') {
+		if (
+			typeof source['manifestUrl'] !== 'string' &&
+			!isRecord(source['manifest'])
+		) {
+			throw new Error(
+				`Invalid PHP extension config: ${configPath}. A manifest source requires manifestUrl or manifest.`
+			);
+		}
+		return config as RuntimePHPExtensionSource;
+	}
+
+	throw new Error(
+		`Invalid PHP extension config: ${configPath}. Unknown source format.`
+	);
+}
+
+function getArrayOption(
+	args: {
+		phpExtension?: string[];
+		'php-extension'?: string[];
+		phpExtensionConfig?: string[];
+		'php-extension-config'?: string[];
+	},
+	camelCaseKey: 'phpExtension' | 'phpExtensionConfig'
+): string[] {
+	const dashCaseKey =
+		camelCaseKey === 'phpExtension'
+			? 'php-extension'
+			: 'php-extension-config';
+	const value = args[camelCaseKey] ?? args[dashCaseKey];
+	if (value === undefined) {
+		return [];
+	}
+	return Array.isArray(value) ? value : [value];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

packages/playground/cli/src/run-cli.ts

@@ -299,6 +299,20 @@ export async function parseOptionsAndRunCLI(argsToParse: string[]) {
 				type: 'boolean',
 				default: false,
 			},
+			'php-extension': {
+				describe:
+					'Load a custom PHP.wasm extension manifest before PHP starts. Can be a local path, file: URL, or http(s) URL. Can be used multiple times.',
+				type: 'array',
+				string: true,
+				nargs: 1,
+			},
+			'php-extension-config': {
+				describe:
+					'Load a JSON PHP.wasm extension config before PHP starts. Use this for direct .so URLs or extension-specific ini/env settings. Can be used multiple times.',
+				type: 'array',
+				string: true,
+				nargs: 1,
+			},
 			'experimental-unsafe-ide-integration': {
 				describe:
 					'Enable experimental IDE development tools. This option edits IDE config files ' +
@@ -422,6 +436,8 @@ export async function parseOptionsAndRunCLI(argsToParse: string[]) {
 				type: 'boolean',
 				default: false,
 			},
+			'php-extension': sharedOptions['php-extension'],
+			'php-extension-config': sharedOptions['php-extension-config'],
 			'experimental-unsafe-ide-integration':
 				sharedOptions['experimental-unsafe-ide-integration'],
 			'skip-browser': {
@@ -896,6 +912,8 @@ export interface RunCLIArgs {
 	redis?: boolean;
 	memcached?: boolean;
 	xdebug?: boolean | XdebugOptions;
+	phpExtension?: string[];
+	phpExtensionConfig?: string[];
 	experimentalUnsafeIdeIntegration?: string[];
 	experimentalDevtools?: boolean;
 	'experimental-blueprints-v2-runner'?: boolean;

packages/playground/cli/tests/php-extensions.spec.ts

@@ -0,0 +1,96 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import {
+	cliExtensionArgsToExtensionsArray,
+	readPHPExtensionConfig,
+} from '../src/php-extensions';
+
+describe('CLI PHP extensions', () => {
+	test('converts built-in extension flags to runtime extension requests', () => {
+		expect(
+			cliExtensionArgsToExtensionsArray({
+				intl: true,
+				redis: true,
+				memcached: true,
+				xdebug: true,
+			})
+		).toEqual(['intl', 'redis', 'memcached', 'xdebug']);
+	});
+
+	test('converts --php-extension values to manifest extension requests', () => {
+		expect(
+			cliExtensionArgsToExtensionsArray({
+				phpExtension: [
+					'./dist/wp_mysql_parser/manifest.json',
+					'https://example.com/spx/manifest.json',
+				],
+			})
+		).toEqual([
+			{
+				source: {
+					format: 'manifest',
+					manifestUrl: './dist/wp_mysql_parser/manifest.json',
+				},
+			},
+			{
+				source: {
+					format: 'manifest',
+					manifestUrl: 'https://example.com/spx/manifest.json',
+				},
+			},
+		]);
+	});
+
+	test('reads --php-extension-config JSON files', async () => {
+		const tempDir = await mkdtemp(path.join(tmpdir(), 'php-extension-'));
+		const configPath = path.join(tempDir, 'extension.json');
+		await writeFile(
+			configPath,
+			JSON.stringify({
+				name: 'wp_mysql_parser',
+				source: {
+					format: 'url',
+					url: './dist/wp_mysql_parser-php8.4-jspi.so',
+				},
+				iniEntries: {
+					'wp_mysql_parser.mode': 'parser',
+				},
+			})
+		);
+
+		try {
+			expect(readPHPExtensionConfig(configPath)).toEqual({
+				name: 'wp_mysql_parser',
+				source: {
+					format: 'url',
+					url: './dist/wp_mysql_parser-php8.4-jspi.so',
+				},
+				iniEntries: {
+					'wp_mysql_parser.mode': 'parser',
+				},
+			});
+			expect(
+				cliExtensionArgsToExtensionsArray({
+					phpExtensionConfig: [configPath],
+				})
+			).toEqual([readPHPExtensionConfig(configPath)]);
+		} finally {
+			await rm(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	test('rejects config files without an external extension source', async () => {
+		const tempDir = await mkdtemp(path.join(tmpdir(), 'php-extension-'));
+		const configPath = path.join(tempDir, 'extension.json');
+		await writeFile(configPath, JSON.stringify({ name: 'broken' }));
+
+		try {
+			expect(() => readPHPExtensionConfig(configPath)).toThrow(
+				'Expected an object with a source field'
+			);
+		} finally {
+			await rm(tempDir, { recursive: true, force: true });
+		}
+	});
+});