Simplify legacy-wp/ patches and trim verbose comments

Reviewed every patch in legacy-wp/legacy-fixes.ts (and supporting files)
for need, gating tightness, and comment clarity. Net: 4828 → 3672 lines.
Verified WP 1.0–4.9 + PHP 5.2 still boot end-to-end.

Notable changes:
- Drop ensureLegacyAdminAuth — duplicated the auto-login flow already
  provided by legacy-mu-plugins.ts.
- Drop the wp_check_mysql_version no-op — mysql-shims.ts already
  returns '8.0.0' from mysql_get_server_info.
- Drop the dead overrides array in patchWpAdminRelativePaths — the
  generic regex pass already covers every entry.
- Drop duplicate mysql_/mysqli_/str_* stubs from generateDbPhpContent —
  the 0-sqlite.php preload runs first and already defines them.
- Share legacyAuthCookieBlock(usernameExpr) between
  patchAdminAuthRedirect and patchAdminAjaxAuth; replace their brittle
  wp-settings.php text scans with readOnDiskWpVersion gates.
- Add explicit version gates to patchLegacyWpCategoriesZeroPk,
  patchWpSchemaPhp, patchWp47ThemeSearchForms, and
  patchAdminNetworkCalls instead of needle-only / file-existence
  heuristics.
- Replace the fragile one-level-nesting regex in patchCheckAdminReferer
  with a reusable balanced-brace helper (replacePhpFunctionBody), reused
  by the "not installed" die() and the do_action('init') rewrite
  extracted out of patchWpSettingsPhp.
- Fix patchWpSettingsPhp bug where settingsChanged was set
  unconditionally inside the error_reporting block, rewriting
  wp-settings on every boot.
- Split the PHP 5.2 vs 5.3+ error-handler boilerplate in
  legacy-mu-plugins.ts into named helpers instead of inline ternaries.
- Trim multi-paragraph "## The bug / ## The fix" docblocks to a single
  why-sentence each, dropping embedded WP source samples and
  indentation diagrams.

Author: JanJakes

packages/playground/wordpress/src/legacy-wp/legacy-boot.ts

@@ -31,10 +31,10 @@ import {
 } from './legacy-fixes';
 
 /**
- * Network I/O functions that must be disabled on legacy PHP builds
- * (< 7) to avoid "null function or function signature mismatch"
- * WASM crashes when WordPress calls fsockopen or cURL during cron,
- * update checks, dashboard RSS widgets, etc.
+ * Network I/O functions disabled on legacy PHP (< 7) to keep
+ * fsockopen/cURL calls (cron, update checks, dashboard RSS) from
+ * tripping "null function or function signature mismatch" WASM
+ * crashes — let them fail safely instead.
  */
 const LEGACY_PHP_DISABLED_NETWORK_FUNCTIONS = [
 	'fsockopen',
@@ -45,21 +45,9 @@ const LEGACY_PHP_DISABLED_NETWORK_FUNCTIONS = [
 ] as const;
 
 /**
- * Disables network I/O on legacy PHP (< 7) and merges the legacy
- * disable_functions list with any caller-supplied list.
- *
- * No-op on modern PHP — called unconditionally from bootRequestHandler.
- *
- * Old WordPress (2.5–3.6) calls fsockopen/cURL during cron, update
- * checks, and dashboard RSS widgets. The underlying socket/cURL
- * operations trigger "null function or function signature mismatch"
- * WASM errors; disabling them makes the calls fail safely (return
- * false) instead of crashing.
- *
- * setPhpIniEntries overwrites keys, so we merge with whatever the
- * caller already passed in `phpIniEntries` — otherwise a
- * networking-disabled list from the web worker would be silently
- * replaced by this legacy-only list.
+ * Merges the legacy network disable list into php.ini for legacy PHP
+ * (no-op on modern). Merge instead of overwrite so a caller-supplied
+ * disable_functions list is preserved.
  */
 export function applyLegacyPhpIniOverrides(
 	php: PHP,
@@ -220,17 +208,12 @@ async function installLegacyWordPress(
  * catches the throw and proceeds to post-install fixups regardless.
  */
 async function runLegacyInstaller(php: PHP): Promise<void> {
-	// WP 1.0–3.0 on legacy PHP: skip the install.php HTTP request
-	// entirely. These old installers trigger various unreachable
-	// WASM traps (mail(), mysql_get_server_info(), etc.) that the
-	// PHP 5.2 binary can't handle. The post-install PDO fallback
-	// creates all tables, users, options, and content without
-	// running any crashable PHP.
-	//
-	// WP 1.0–1.2: the post-install PDO fallback creates the very
-	//   simple schema entirely.
-	// WP 1.5–3.0: needs dbDelta() for proper table schemas but
-	//   skips the rest of the installer.
+	// WP 1.0–3.0 installers trigger WASM traps (mail(),
+	// mysql_get_server_info(), etc.) on the PHP 5.2 binary, so skip
+	// the install.php HTTP request entirely.
+	//   WP 1.0–1.2: post-install PDO fallback builds the full schema.
+	//   WP 1.5–3.0: needs dbDelta() for the schema; the rest is left
+	//     to the PDO fallback.
 	const wpVersion = readOnDiskWpVersion(php, php.documentRoot);
 	if (wpVersion !== null) {
 		const parsed = parseFloat(wpVersion);
@@ -243,17 +226,12 @@ async function runLegacyInstaller(php: PHP): Promise<void> {
 		}
 	}
 
-	// Disable networking + mail functions during installation. This
-	// must include all the functions already disabled via
-	// applyLegacyPhpIniOverrides() — setPhpIniEntries replaces the
-	// entire value, so listing only 'fsockopen' would re-enable
-	// curl_init/curl_exec and cause WASM crashes when the installer
-	// makes outbound HTTP requests.
-	//
-	// error_reporting is suppressed at the ini level too: old WP
-	// class declarations (e.g. Walker_Page) trigger E_STRICT during
-	// compile, which PHP may report using the ini value rather than
-	// the runtime error_reporting() call.
+	// withPHPIniValues replaces values wholesale, so re-list every
+	// function from LEGACY_PHP_DISABLED_NETWORK_FUNCTIONS plus mail()
+	// (the installer otherwise calls it and crashes). error_reporting
+	// is suppressed at the ini level because old WP class declarations
+	// trigger E_STRICT at compile time, which PHP reports against the
+	// ini value rather than the runtime error_reporting() call.
 	const iniOverrides: Record<string, string> = {
 		disable_functions: [
 			...LEGACY_PHP_DISABLED_NETWORK_FUNCTIONS,
@@ -284,10 +262,9 @@ async function runLegacyInstaller(php: PHP): Promise<void> {
 			})
 	);
 
-	// Skip isWordPressInstalled() entirely — it can trigger a WASM
-	// trap (not a PHP exception) on old WordPress (< 3.0), which
-	// corrupts the runtime beyond recovery. Use the installer
-	// response text as a heuristic instead.
+	// isWordPressInstalled() can WASM-trap on old WP (< 3.0) and
+	// corrupt the runtime, so detect success from the installer
+	// response text instead.
 	const installSucceeded =
 		response.text?.includes('Success') ||
 		response.text?.includes('successful') ||
@@ -357,8 +334,8 @@ async function setLegacyPermalinkStructureViaPdo(php: PHP): Promise<void> {
 
 /**
  * Runs dbDelta() and populate_options/populate_roles without the
- * full wp_install() function. Used for WP 2.3–3.0 where the
- * installer crashes but we still need the table schemas.
+ * full wp_install(). Used for WP 2.1–3.0 where install.php crashes
+ * but we still need the table schemas.
  */
 async function runDbDeltaOnly(php: PHP): Promise<void> {
 	try {
@@ -370,26 +347,17 @@ async function runDbDeltaOnly(php: PHP): Promise<void> {
 				ob_start();
 				require getenv('DOCUMENT_ROOT') . '/wp-load.php';
 				ob_clean();
-				// Load upgrade functions for dbDelta
 				if (file_exists(ABSPATH . 'wp-admin/includes/upgrade.php')) {
 					require_once ABSPATH . 'wp-admin/includes/upgrade.php';
 				} elseif (file_exists(ABSPATH . 'wp-admin/upgrade-functions.php')) {
 					require_once ABSPATH . 'wp-admin/upgrade-functions.php';
 				}
-				// Create tables via dbDelta — the critical step that
-				// creates the proper schema for the WP version.
 				if (function_exists('make_db_current_silent')) {
 					make_db_current_silent();
 				}
-				// populate_options/populate_roles on WP 2.3+ only.
-				// WP 2.1-2.2 crash in these functions (WASM traps
-				// from mail/network calls that bypass PHP try/catch).
-				// The PDO fallback seeds essential options/roles.
-				global $wp_version;
-				// populate_options sets db_version and other essential
-				// options. populate_roles creates the roles/capabilities.
-				// On PHP 5.2 WP 2.1-2.2 these crash with WASM traps.
-				// Run them for any WP version that defines them.
+				// Seed essential options/roles when the loader exposes
+				// them. The PDO fallback in runPostInstallLegacyFixups
+				// backfills anything missing if either call dies.
 				if (function_exists('populate_options')) populate_options();
 				if (function_exists('populate_roles')) populate_roles();
 				echo 'OK';