wp_mysql_parser: conditional WASM loader for PHP 8.4 (draft, stacked)

packages/php-wasm/node/src/lib/extensions/wp-mysql-parser/with-wp-mysql-parser.ts

@@ -0,0 +1,65 @@
+import {
+	type EmscriptenOptions,
+	type PHPRuntime,
+	type SupportedPHPVersion,
+	installPHPExtensionFilesSync,
+	PHP_EXTENSIONS_DIR,
+} from '@php-wasm/universal';
+import fs from 'fs';
+
+export interface WpMysqlParserOptions {
+	/**
+	 * Absolute path on the host filesystem to a `wp_mysql_parser.so` side
+	 * module compiled for the target PHP version and async mode.
+	 *
+	 * The extension itself lives at
+	 * https://github.com/WordPress/sqlite-database-integration/pull/381
+	 * and is not yet packaged with Playground; users build it themselves
+	 * (or fetch it from a release artifact) and pass the path via
+	 * `--wp-mysql-parser-so=<path>` on the CLI.
+	 */
+	soPath: string;
+}
+
+/*
+ * The PR #381 build hasn't been validated against earlier PHP versions
+ * yet, so this run only wires it up for PHP 8.4. Widening to other
+ * versions is a one-line change once we have artifacts to test against.
+ */
+const SUPPORTED_VERSIONS: ReadonlyArray<SupportedPHPVersion> = ['8.4'];
+
+export async function withWpMysqlParser(
+	version: SupportedPHPVersion,
+	options: EmscriptenOptions,
+	wpMysqlParserOptions: WpMysqlParserOptions
+): Promise<EmscriptenOptions> {
+	if (!SUPPORTED_VERSIONS.includes(version)) {
+		throw new Error(
+			`withWpMysqlParser: only PHP ${SUPPORTED_VERSIONS.join(
+				', '
+			)} are supported in this build; got ${version}.`
+		);
+	}
+
+	const soBytes = new Uint8Array(
+		fs.readFileSync(wpMysqlParserOptions.soPath)
+	);
+
+	return {
+		...options,
+		ENV: {
+			...options.ENV,
+			PHP_INI_SCAN_DIR: PHP_EXTENSIONS_DIR,
+		},
+		onRuntimeInitialized: (phpRuntime: PHPRuntime) => {
+			if (options.onRuntimeInitialized) {
+				options.onRuntimeInitialized(phpRuntime);
+			}
+
+			installPHPExtensionFilesSync(phpRuntime.FS, {
+				name: 'wp_mysql_parser',
+				soBytes,
+			});
+		},
+	};
+}

packages/php-wasm/node/src/lib/load-runtime.ts

@@ -25,6 +25,10 @@ import {
 import { withIntl } from './extensions/intl/with-intl';
 import { withRedis } from './extensions/redis/with-redis';
 import { withMemcached } from './extensions/memcached/with-memcached';
+import {
+	withWpMysqlParser,
+	type WpMysqlParserOptions,
+} from './extensions/wp-mysql-parser/with-wp-mysql-parser';
 import { dirname, joinPaths, toPosixPath } from '@php-wasm/util';
 import { platform } from 'os';
 
@@ -34,6 +38,7 @@ export interface PHPLoaderOptions {
 	withIntl?: boolean;
 	withRedis?: boolean;
 	withMemcached?: boolean;
+	withWpMysqlParser?: WpMysqlParserOptions;
 }
 
 export type PHPLoaderOptionsForNode = PHPLoaderOptions & {
@@ -344,6 +349,13 @@ export async function loadNodeRuntime(
 				emscriptenOptions
 			);
 		}
+		if (options?.withWpMysqlParser) {
+			emscriptenOptions = await withWpMysqlParser(
+				modernVersion,
+				emscriptenOptions,
+				options.withWpMysqlParser
+			);
+		}
 	}
 
 	emscriptenOptions = await withNetworking(emscriptenOptions);

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

@@ -201,6 +201,7 @@ export class BlueprintsV1Handler {
 			withRedis: this.args.redis,
 			withMemcached: this.args.memcached,
 			withXdebug: !!this.args.xdebug,
+			withWpMysqlParserSo: this.args['wp-mysql-parser-so'],
 			nativeInternalDirPath,
 			pathAliases: this.args.pathAliases,
 		});

packages/playground/cli/src/blueprints-v1/worker-thread-v1.ts

@@ -52,6 +52,7 @@ interface WorkerBootRequestHandlerOptions {
 	withRedis?: boolean;
 	withMemcached?: boolean;
 	withXdebug?: boolean;
+	withWpMysqlParserSo?: string;
 	pathAliases?: PathAlias[];
 }
 
@@ -251,6 +252,9 @@ function createPhpRuntimeFactory(
 				withRedis: options.withRedis,
 				withMemcached: options.withMemcached,
 				withXdebug: options.withXdebug,
+				withWpMysqlParser: options.withWpMysqlParserSo
+					? { soPath: options.withWpMysqlParserSo }
+					: undefined,
 			}
 		);
 	};

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

@@ -299,6 +299,14 @@ export async function parseOptionsAndRunCLI(argsToParse: string[]) {
 				type: 'boolean',
 				default: false,
 			},
+			'wp-mysql-parser-so': {
+				describe:
+					'Path to a wp_mysql_parser.so side module compiled for the ' +
+					'target PHP version. Only PHP 8.4 is supported in this build. ' +
+					'See https://github.com/WordPress/sqlite-database-integration/pull/381',
+				type: 'string',
+				normalize: true,
+			},
 			'experimental-unsafe-ide-integration': {
 				describe:
 					'Enable experimental IDE development tools. This option edits IDE config files ' +
@@ -890,6 +898,7 @@ export interface RunCLIArgs {
 	redis?: boolean;
 	memcached?: boolean;
 	xdebug?: boolean | XdebugOptions;
+	'wp-mysql-parser-so'?: string;
 	experimentalUnsafeIdeIntegration?: string[];
 	experimentalDevtools?: boolean;
 	'experimental-blueprints-v2-runner'?: boolean;