Safely auto-configure wp-config.php when some configuration is missing

packages/playground/blueprints/src/lib/steps/define-wp-config-consts.ts

@@ -62,12 +62,7 @@ export const defineWpConfigConsts: StepHandler<
 		case 'rewrite-wp-config': {
 			const documentRoot = await playground.documentRoot;
 			const wpConfigPath = joinPaths(documentRoot, '/wp-config.php');
-			await defineWpConfigConstants(
-				playground,
-				wpConfigPath,
-				consts,
-				'rewrite'
-			);
+			await defineWpConfigConstants(playground, wpConfigPath, consts);
 			break;
 		}
 		default:

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

@@ -142,6 +142,7 @@ export class BlueprintsV1Handler {
 			mountsBeforeWpInstall,
 			mountsAfterWpInstall,
 			wordPressZip: wordPressZip && (await wordPressZip!.arrayBuffer()),
+			wpConfigDefaultConstants: this.args.wpConfigDefaultConstants,
 			sqliteIntegrationPluginZip:
 				await sqliteIntegrationPluginZip?.arrayBuffer(),
 			firstProcessId: 0,

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

@@ -50,6 +50,7 @@ export type WorkerBootOptions = {
 export type PrimaryWorkerBootOptions = WorkerBootOptions & {
 	wpVersion?: string;
 	wordPressZip?: ArrayBuffer;
+	wpConfigDefaultConstants?: Record<string, string | number | boolean | null>;
 	sqliteIntegrationPluginZip?: ArrayBuffer;
 	dataSqlPath?: string;
 };
@@ -129,6 +130,7 @@ export class PlaygroundCliBlueprintV1Worker extends PHPWorker {
 		mountsAfterWpInstall,
 		phpVersion: php = RecommendedPHPVersion,
 		wordPressZip,
+		wpConfigDefaultConstants,
 		sqliteIntegrationPluginZip,
 		firstProcessId,
 		processIdSpaceLength,
@@ -182,6 +184,7 @@ export class PlaygroundCliBlueprintV1Worker extends PHPWorker {
 					wordPressZip !== undefined
 						? new File([wordPressZip], 'wordpress.zip')
 						: undefined,
+				wpConfigDefaultConstants,
 				sqliteIntegrationPluginZip:
 					sqliteIntegrationPluginZip !== undefined
 						? new File(

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

@@ -27,7 +27,7 @@ import {
 	type ParsedBlueprintV2String,
 	type RawBlueprintV2Data,
 } from '@wp-playground/blueprints';
-import { bootRequestHandler } from '@wp-playground/wordpress';
+import { bootRequestHandler, ensureWpConfig } from '@wp-playground/wordpress';
 import { existsSync } from 'fs';
 import path from 'path';
 import { rootCertificates } from 'tls';
@@ -250,6 +250,17 @@ export class PlaygroundCliBlueprintV2Worker extends PHPWorker {
 			return;
 		}
 
+		/*
+		 * Add required constants to "wp-config.php" if they are not already defined.
+		 * This is needed, because some WordPress backups and exports may not include
+		 * definitions for some of the necessary constants.
+		 */
+		await ensureWpConfig(
+			primaryPhp,
+			primaryPhp.requestHandler!.documentRoot,
+			args.wpConfigDefaultConstants
+		);
+
 		await this.runBlueprintV2(args);
 	}
 

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

@@ -153,6 +153,20 @@ export async function parseOptionsAndRunCLI() {
 				type: 'boolean',
 				default: false,
 			})
+			.option('wp-config-default-constants', {
+				describe:
+					'Configure default constant values to use in "wp-config.php", in case the constants are missing. Encoded as JSON string.',
+				type: 'string',
+				coerce: (value: string) => {
+					try {
+						return JSON.parse(value);
+					} catch (e /* eslint-disable-line @typescript-eslint/no-unused-vars */) {
+						throw new Error(
+							'Invalid JSON string for --wp-config-default-constants'
+						);
+					}
+				},
+			})
 			.option('skip-wordpress-setup', {
 				describe:
 					'Do not download, unzip, and install WordPress. Useful for mounting a pre-configured WordPress directory at /wordpress.',
@@ -420,6 +434,7 @@ export interface RunCLIArgs {
 	xdebug?: boolean;
 	experimentalDevtools?: boolean;
 	'experimental-blueprints-v2-runner'?: boolean;
+	wpConfigDefaultConstants?: Record<string, string | number | boolean | null>;
 
 	// --------- Blueprint V1 args -----------
 	skipWordPressSetup?: boolean;

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

@@ -11,6 +11,7 @@ import { exec } from 'node:child_process';
 import {
 	mkdirSync,
 	readdirSync,
+	readFileSync,
 	writeFileSync,
 	symlinkSync,
 	unlinkSync,
@@ -131,6 +132,129 @@ describe.each(blueprintVersions)(
 			expect(response.text).toContain(oldestSupportedVersion);
 		});
 
+		test('should add missing constants to wp-config.php', async () => {
+			const tmpDir = await mkdtemp(
+				path.join(tmpdir(), 'playground-test-')
+			);
+
+			const args: RunCLIArgs = {
+				...suiteCliArgs,
+				command: 'server',
+				'mount-before-install': [
+					{
+						hostPath: tmpDir,
+						vfsPath: '/wordpress',
+					},
+				],
+				mode: 'create-new-site',
+			};
+
+			const newSiteArgs: RunCLIArgs =
+				version === 2
+					? {
+							...args,
+							'experimental-blueprints-v2-runner': true,
+							mode: 'create-new-site',
+					  }
+					: args;
+
+			const existingSiteArgs: RunCLIArgs =
+				version === 2
+					? {
+							...args,
+							'experimental-blueprints-v2-runner': true,
+							mode: 'apply-to-existing-site',
+					  }
+					: {
+							...args,
+							skipWordPressSetup: true,
+					  };
+
+			// Create a new site so we can load it as an existing site later.
+			cliServer = await runCLI(newSiteArgs);
+			const wpConfigPath = path.join(tmpDir, 'wp-config.php');
+			let wpConfig = readFileSync(wpConfigPath, 'utf8');
+			expect(wpConfig).toContain(
+				"define( 'DB_NAME', 'database_name_here' );"
+			);
+			expect(wpConfig).not.toContain(
+				'BEGIN: Added by WordPress Playground.'
+			);
+			expect(wpConfig).not.toContain(
+				'END: Added by WordPress Playground.'
+			);
+
+			// Remove the "DB_NAME" constant.
+			writeFileSync(
+				wpConfigPath,
+				wpConfig.replace("'DB_NAME'", "'UNKNOWN_CONSTANT'")
+			);
+			wpConfig = readFileSync(wpConfigPath, 'utf8');
+			expect(wpConfig).not.toContain(
+				"define( 'DB_NAME', 'database_name_here' );"
+			);
+
+			// Use the existing site and confirm the missing constant is added.
+			cliServer = await runCLI(existingSiteArgs);
+			wpConfig = readFileSync(wpConfigPath, 'utf8');
+			expect(wpConfig).toContain(
+				"define( 'DB_NAME', 'database_name_here' );"
+			);
+			expect(wpConfig).toContain('BEGIN: Added by WordPress Playground.');
+			expect(wpConfig).toContain('END: Added by WordPress Playground.');
+
+			// Ensure the "--wp-config-default-constants" argument works as well.
+			try {
+				cliServer = await runCLI({
+					...existingSiteArgs,
+					wpConfigDefaultConstants: {
+						DB_NAME: 'test_database_name',
+						CUSTOM_CONSTANT: 'test_custom_constant',
+					},
+				});
+				// eslint-disable-next-line @typescript-eslint/no-unused-vars
+			} catch (_) {
+				// The boot will fail due to incorrect database name,
+				// but the wp-config.php file should be updated.
+			}
+
+			wpConfig = readFileSync(wpConfigPath, 'utf8');
+			expect(wpConfig).not.toContain(
+				"define( 'DB_NAME', 'database_name_here' );"
+			);
+			expect(wpConfig).toContain(
+				"define( 'DB_NAME', 'test_database_name' );"
+			);
+			expect(wpConfig).toContain(
+				"define( 'CUSTOM_CONSTANT', 'test_custom_constant' );"
+			);
+			expect(wpConfig).toContain('BEGIN: Added by WordPress Playground.');
+			expect(wpConfig).toContain('END: Added by WordPress Playground.');
+
+			// Ensure the injected constants are removed when no longer needed.
+			writeFileSync(
+				wpConfigPath,
+				wpConfig.replace("'UNKNOWN_CONSTANT'", "'DB_NAME'")
+			);
+			await runCLI(existingSiteArgs);
+			wpConfig = readFileSync(wpConfigPath, 'utf8');
+			expect(wpConfig).toContain(
+				"define( 'DB_NAME', 'database_name_here' );"
+			);
+			expect(wpConfig).not.toContain(
+				"define( 'DB_NAME', 'test_database_name' );"
+			);
+			expect(wpConfig).not.toContain(
+				"define( 'CUSTOM_CONSTANT', 'test_custom_constant' );"
+			);
+			expect(wpConfig).not.toContain(
+				'BEGIN: Added by WordPress Playground.'
+			);
+			expect(wpConfig).not.toContain(
+				'END: Added by WordPress Playground.'
+			);
+		});
+
 		test('should run blueprint', async () => {
 			cliServer = await runCLI({
 				...suiteCliArgs,

packages/playground/wordpress/src/boot.ts

@@ -23,7 +23,7 @@ import {
 } from '.';
 import { basename, dirname, joinPaths } from '@php-wasm/util';
 import { logger } from '@php-wasm/logger';
-import { ensureWpConfig } from './rewrite-wp-config';
+import { ensureWpConfig } from './wp-config';
 
 export type PhpIniOptions = Record<string, string>;
 export type Hook = (php: PHP) => void | Promise<void>;
@@ -126,6 +126,10 @@ export interface BootWordPressOptions {
 	dataSqlPath?: string;
 	/** Zip with the WordPress installation to extract in /wordpress. */
 	wordPressZip?: File | Promise<File> | undefined;
+	/**
+	 * Default constant values to use in "wp-config.php", in case they are missing.
+	 */
+	wpConfigDefaultConstants?: Record<string, string | number | boolean | null>;
 	/** Preloaded SQLite integration plugin. */
 	sqliteIntegrationPluginZip?: File | Promise<File>;
 	/**
@@ -186,7 +190,11 @@ export async function bootWordPress(
 	 * This is needed, because some WordPress backups and exports may not include
 	 * definitions for some of the necessary constants.
 	 */
-	await ensureWpConfig(php, requestHandler.documentRoot);
+	await ensureWpConfig(
+		php,
+		requestHandler.documentRoot,
+		options.wpConfigDefaultConstants
+	);
 	// Run "before database" hooks to mount/copy more files in
 	if (options.hooks?.beforeDatabaseSetup) {
 		await options.hooks.beforeDatabaseSetup(php);

packages/playground/wordpress/src/index.ts

@@ -10,7 +10,7 @@ export {
 	getFileNotFoundActionForWordPress,
 } from './boot';
 export type { PhpIniOptions, PHPInstanceCreatedHook } from './boot';
-export { defineWpConfigConstants, ensureWpConfig } from './rewrite-wp-config';
+export { defineWpConfigConstants, ensureWpConfig } from './wp-config';
 export { getLoadedWordPressVersion } from './version-detect';
 
 export * from './version-detect';