Integrate PHP 5.2 support in web worker, CLI, and mu-plugins

Web worker: select pre-patched SQLite v2.2.22-php52 for legacy PHP,
force single-instance mode for legacy PHP (PROXYFS parser state bug),
disable WP_DEBUG for legacy WP (missing WP_DEBUG_DISPLAY).

CLI: pass phpVersion through boot chain, select correct SQLite version,
disable extensions for legacy PHP, add pre-built WordPress lookup.

Mu-plugins: add PHP 5.2-compatible stub (named functions instead of
closures), guard function_exists checks for WP < 3.0, use array()
syntax for PHP 5.3 compatibility, handle Requests class variations.

Skip update checks prefetch for legacy WordPress.

Author: JanJakes

packages/php-wasm/universal/src/lib/proxy-file-system.ts

@@ -1,5 +1,30 @@
 import type { PHP } from './php';
 
+/**
+ * Reads the major PHP version from an instance's Emscripten runtime and
+ * returns true for anything older than PHP 7. Used to decide whether the
+ * PROXYFS mmap patch should apply — see {@link proxyFileSystem} for the
+ * legacy-PHP rationale. Falls back to `false` when the runtime hasn't
+ * populated phpVersion yet, matching the pre-refactor default behaviour.
+ */
+function isLegacyPhpInstance(phpInstance: PHP): boolean {
+	// Find the private runtime symbol by inspecting its value rather
+	// than assuming it's the first symbol (fragile if more symbols
+	// are added to the PHP class).
+	const symbols = Object.getOwnPropertySymbols(phpInstance);
+	let runtime: any;
+	for (const sym of symbols) {
+		// @ts-ignore
+		const val = phpInstance[sym];
+		if (val && typeof val === 'object' && 'phpVersion' in val) {
+			runtime = val;
+			break;
+		}
+	}
+	const major: number | undefined = runtime?.phpVersion?.major;
+	return typeof major === 'number' && major < 7;
+}
+
 /**
  * Adds mmap support to PROXYFS for memory-mapping files across PHP instances.
  *
@@ -136,8 +161,12 @@ function ensureProxyFSHasMmapSupport(phpInstance: PHP) {
  * For example, mounting /wordpress from the parent instance into a child worker allows
  * both to access the same WordPress installation without copying the entire directory.
  *
- * The function automatically patches PROXYFS with mmap support before mounting, ensuring
- * libraries like ICU can memory-map data files through the proxied filesystem.
+ * The function automatically patches PROXYFS with mmap support before mounting on
+ * PHP 7+, so libraries like ICU can memory-map data files through the proxied
+ * filesystem. Legacy PHP (< 7) skips the mmap patch: its `zend_compile_file` trusts
+ * stale fstat sizes on mmap'd streams and reads past the real EOF when the primary
+ * has rewritten files after the secondary was created. PHP 7+ removed the mmap path
+ * from `zend_stream_fixup` entirely so the patch is only needed there.
  *
  * Mounts are registered via php.mount() so they survive runtime rotation.
  * When the replica's WASM module is hot-swapped, hotSwapPHPRuntime()
@@ -152,6 +181,7 @@ export async function proxyFileSystem(
 	replica: PHP,
 	paths: string[]
 ) {
+	const replicaIsLegacy = isLegacyPhpInstance(replica);
 	// We can't just import the symbol from the library because
 	// Playground CLI is built as ESM and php-wasm-node is built as
 	// CJS and the imported symbols will differ in the production build.
@@ -164,7 +194,9 @@ export async function proxyFileSystem(
 		// after runtime rotation in hotSwapPHPRuntime().
 		replica.mkdir(path);
 		await replica.mount(path, (php: PHP) => {
-			ensureProxyFSHasMmapSupport(php);
+			if (!replicaIsLegacy) {
+				ensureProxyFSHasMmapSupport(php);
+			}
 			const replicaSymbol = Object.getOwnPropertySymbols(php)[0];
 			// @ts-ignore
 			php[replicaSymbol].FS.mount(

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

@@ -2,6 +2,7 @@ import { logger } from '@php-wasm/logger';
 import { EmscriptenDownloadMonitor, ProgressTracker } from '@php-wasm/progress';
 import {
 	consumeAPI,
+	isLegacyPHPVersion,
 	type Pooled,
 	type UniversalPHP,
 } from '@php-wasm/universal';
@@ -116,7 +117,13 @@ export class BlueprintsV1Handler {
 			sqliteIntegrationPluginZip = undefined;
 		} else {
 			this.cliOutput.updateProgress('Preparing SQLite database');
-			sqliteIntegrationPluginZip = await fetchSqliteIntegration();
+			// Use pre-patched v2.2.22 for legacy PHP (closures replaced
+			// with named functions, PHP 5.2 polyfills added offline).
+			const phpVersion = this.args.php || RecommendedPHPVersion;
+			const isLegacyPhp = isLegacyPHPVersion(phpVersion);
+			const sqliteVersion = isLegacyPhp ? 'v2.2.22-php52' : 'trunk';
+			sqliteIntegrationPluginZip =
+				await fetchSqliteIntegration(sqliteVersion);
 		}
 
 		this.cliOutput.updateProgress('Booting WordPress');
@@ -130,6 +137,7 @@ export class BlueprintsV1Handler {
 			playground as unknown as PlaygroundCliBlueprintV1Worker
 		).bootWordPress(
 			{
+				phpVersion: runtimeConfiguration.phpVersion,
 				wpVersion: runtimeConfiguration.wpVersion,
 				siteUrl: this.siteUrl,
 				wordpressInstallMode:

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

@@ -6,7 +6,9 @@ import path, { basename } from 'path';
 
 export const CACHE_FOLDER = path.join(os.homedir(), '.wordpress-playground');
 
-export async function fetchSqliteIntegration(): Promise<File> {
+export async function fetchSqliteIntegration(
+	version: 'trunk' | 'v2.1.16' | 'v2.2.22' | 'v2.2.22-php52' = 'trunk'
+): Promise<File> {
 	// Production builds: the ZIP sits next to the bundled JS.
 	const dir =
 		typeof __dirname !== 'undefined' ? __dirname : import.meta.dirname;
@@ -22,7 +24,7 @@ export async function fetchSqliteIntegration(): Promise<File> {
 			wpBuildsDir,
 			'src',
 			'sqlite-database-integration',
-			'sqlite-database-integration-trunk.zip'
+			`sqlite-database-integration-${version}.zip`
 		);
 	}
 

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

@@ -1,7 +1,7 @@
 import type { FileLockManager } from '@php-wasm/universal';
 import { loadNodeRuntime } from '@php-wasm/node';
 import { EmscriptenDownloadMonitor } from '@php-wasm/progress';
-import type { PathAlias, SupportedPHPVersion } from '@php-wasm/universal';
+import type { AllPHPVersion, PathAlias } from '@php-wasm/universal';
 import {
 	PHPWorker,
 	releaseApiProxy,
@@ -27,6 +27,7 @@ import type { Mount } from '@php-wasm/cli-util';
 
 export type WorkerBootWordPressOptions = {
 	siteUrl: string;
+	phpVersion?: string;
 	wpVersion?: string;
 	wordpressInstallMode: WordPressInstallMode;
 	wordPressZip?: ArrayBuffer;
@@ -40,7 +41,7 @@ export type WorkerBootWordPressOptions = {
 
 interface WorkerBootRequestHandlerOptions {
 	siteUrl: string;
-	phpVersion: SupportedPHPVersion;
+	phpVersion: AllPHPVersion;
 	processId: number;
 	trace: boolean;
 	nativeInternalDirPath: string;
@@ -102,6 +103,7 @@ export class PlaygroundCliBlueprintV1Worker extends PHPWorker {
 		this.bootedWordPress = true;
 		const {
 			siteUrl,
+			phpVersion,
 			wordpressInstallMode,
 			wordPressZip,
 			sqliteIntegrationPluginZip,
@@ -112,6 +114,7 @@ export class PlaygroundCliBlueprintV1Worker extends PHPWorker {
 		try {
 			await bootWordPress(this.__internal_getRequestHandler()!, {
 				siteUrl,
+				phpVersion,
 				wordpressInstallMode,
 				wordPressZip:
 					wordPressZip !== undefined
@@ -161,6 +164,7 @@ export class PlaygroundCliBlueprintV1Worker extends PHPWorker {
 		try {
 			const requestHandler = await bootRequestHandler({
 				siteUrl: options.siteUrl,
+				phpVersion: options.phpVersion,
 				maxPhpInstances: 1,
 				createPhpRuntime: createPhpRuntimeFactory(
 					options,

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

@@ -6,7 +6,7 @@ import {
 	type PHPRequest,
 	type PathAlias,
 	type RemoteAPI,
-	type SupportedPHPVersion,
+	type AllPHPVersion,
 } from '@php-wasm/universal';
 import {
 	PHPResponse,
@@ -46,6 +46,8 @@ import type { PlaygroundCliBlueprintV2Worker } from './blueprints-v2/worker-thre
 import type { XdebugOptions } from '@php-wasm/node';
 /* eslint-disable no-console */
 import {
+	AllPHPVersions,
+	isLegacyPHPVersion,
 	SupportedPHPVersions,
 	FileLockManagerInMemory,
 } from '@php-wasm/universal';
@@ -118,7 +120,7 @@ export async function parseOptionsAndRunCLI(argsToParse: string[]) {
 				describe: 'PHP version to use.',
 				type: 'string',
 				default: RecommendedPHPVersion,
-				choices: SupportedPHPVersions,
+				choices: AllPHPVersions,
 			},
 			wp: {
 				describe: 'WordPress version to use.',
@@ -373,7 +375,7 @@ export async function parseOptionsAndRunCLI(argsToParse: string[]) {
 				describe: 'PHP version to use.',
 				type: 'string',
 				default: RecommendedPHPVersion,
-				choices: SupportedPHPVersions,
+				choices: AllPHPVersions,
 			},
 			wp: {
 				describe: 'WordPress version to use.',
@@ -662,14 +664,24 @@ export async function parseOptionsAndRunCLI(argsToParse: string[]) {
 		const hasDebugDefine = (name: string) => {
 			return name in define || name in defineBool || name in defineNumber;
 		};
-		if (!hasDebugDefine('WP_DEBUG')) {
-			define['WP_DEBUG'] = 'true';
-		}
-		if (!hasDebugDefine('WP_DEBUG_LOG')) {
-			define['WP_DEBUG_LOG'] = 'true';
-		}
-		if (!hasDebugDefine('WP_DEBUG_DISPLAY')) {
-			define['WP_DEBUG_DISPLAY'] = 'false';
+		// Don't default WP_DEBUG* on for legacy PHP: old WordPress
+		// (pre-2.3) prints E_NOTICE output before headers are sent,
+		// which corrupts redirects and breaks the installer. The web
+		// worker path applies the same gate in
+		// @wp-playground/client/src/blueprints-v1-handler.ts.
+		const phpVersionForDebug = (args['php'] ||
+			RecommendedPHPVersion) as AllPHPVersion;
+		const isLegacyPhpForDebug = isLegacyPHPVersion(phpVersionForDebug);
+		if (!isLegacyPhpForDebug) {
+			if (!hasDebugDefine('WP_DEBUG')) {
+				define['WP_DEBUG'] = 'true';
+			}
+			if (!hasDebugDefine('WP_DEBUG_LOG')) {
+				define['WP_DEBUG_LOG'] = 'true';
+			}
+			if (!hasDebugDefine('WP_DEBUG_DISPLAY')) {
+				define['WP_DEBUG_DISPLAY'] = 'false';
+			}
 		}
 
 		const cliArgs = {
@@ -736,9 +748,7 @@ export async function parseOptionsAndRunCLI(argsToParse: string[]) {
 					currentError = currentError.cause as Error;
 				} while (currentError instanceof Error);
 				console.error(
-					'\x1b[1m' +
-						messageChain.join(' caused by: ') +
-						'\x1b[0m'
+					'\x1b[1m' + messageChain.join(' caused by: ') + '\x1b[0m'
 				);
 			}
 		} else {
@@ -811,7 +821,7 @@ export interface RunCLIArgs {
 	mount?: Mount[];
 	'mount-before-install'?: Mount[];
 	outfile?: string;
-	php?: SupportedPHPVersion;
+	php?: AllPHPVersion;
 	port?: number;
 	'site-url'?: string;
 	quiet?: boolean;
@@ -990,6 +1000,15 @@ export async function runCLI(args: RunCLIArgs): Promise<RunCLIServer | void> {
 		args.memcached = await jspi();
 	}
 
+	// Disable all extensions for legacy PHP versions — they're not available.
+	const isLegacyPhp = isLegacyPHPVersion(args.php || RecommendedPHPVersion);
+	if (isLegacyPhp) {
+		args.intl = false;
+		args.redis = false;
+		args.memcached = false;
+		args.xdebug = false;
+	}
+
 	// Setup phpMyAdmin if enabled.
 	if (args.phpmyadmin) {
 		if (true === args.phpmyadmin) {
@@ -1098,13 +1117,16 @@ export async function runCLI(args: RunCLIArgs): Promise<RunCLIServer | void> {
 					vfsPath: '/',
 				};
 
-				const isPHP85orHigher =
-					SupportedPHPVersions.indexOf(
-						args.php || RecommendedPHPVersion
-					) <= SupportedPHPVersions.indexOf('8.5');
+				const phpVer = args.php || RecommendedPHPVersion;
+				// SupportedPHPVersions is ordered newest-first, so a
+				// lower index means a higher version.
+				const isPhp85OrHigher =
+					SupportedPHPVersions.includes(phpVer as any) &&
+					SupportedPHPVersions.indexOf(phpVer as any) <=
+						SupportedPHPVersions.indexOf('8.5');
 
 				// And, if PHP >= 8.5, add the new Xdebug config.
-				if (isPHP85orHigher) {
+				if (isPhp85OrHigher) {
 					await createTempDirSymlink(
 						nativeDir.path,
 						symlinkPath,

packages/playground/cli/tests/run-cli.spec.ts

@@ -171,10 +171,11 @@ describe.each(blueprintVersions)(
 		test('should set WordPress version', async () => {
 			const { MinifiedWordPressVersionsList } =
 				await import('@wp-playground/wordpress-builds');
-			const oldestSupportedVersion =
-				MinifiedWordPressVersionsList[
-					MinifiedWordPressVersionsList.length - 1
-				];
+			// Use the oldest non-legacy version. Legacy versions
+			// (< 5.0) require legacy PHP and can't boot on modern PHP.
+			const oldestSupportedVersion = MinifiedWordPressVersionsList.filter(
+				(v) => parseFloat(v) >= 5
+			).pop()!;
 			await using cliServer = await runCLI({
 				...suiteCliArgs,
 				command: 'server',
@@ -339,10 +340,7 @@ describe.each(blueprintVersions)(
 
 			const mounts = [];
 			for (let i = 0; i < 5; i++) {
-				const hostSubDir = path.join(
-					hostTmpDir,
-					`migration-${i}`
-				);
+				const hostSubDir = path.join(hostTmpDir, `migration-${i}`);
 				mkdirSync(hostSubDir, { recursive: true });
 				const hostFilePath = path.join(
 					hostSubDir,

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

@@ -87,10 +87,15 @@ export class BlueprintsV1Handler {
 
 		/**
 		 * Pre-fetch WordPress update checks to speed up the initial wp-admin load.
+		 * Skip for old WordPress versions — the functions called by prefetch
+		 * (wp_check_php_version, wp_update_plugins, etc.) don't exist or crash
+		 * on legacy WP, and the resulting PHP errors create noise.
 		 *
 		 * @see https://github.com/WordPress/wordpress-playground/pull/2295
 		 */
-		if (runtimeConfiguration.networking) {
+		const wpMajor = parseFloat(runtimeConfiguration.wpVersion);
+		const isLegacyWpVersion = Number.isFinite(wpMajor) && wpMajor < 5;
+		if (runtimeConfiguration.networking && !isLegacyWpVersion) {
 			await playground.prefetchUpdateChecks();
 		}