WordPress · benitoalba · Jul 24, 2026
diff --git a/packages/docs/site/docs/developers/05-local-development/04-wp-playground-cli.md b/packages/docs/site/docs/developers/05-local-development/04-wp-playground-cli.md
@@ -277,6 +277,7 @@ to your unique WordPress setup. With the Playground CLI, you can use the followi
 - **`server`**: (Advanced) Starts a local WordPress server with full manual control over configuration.
 - **`run-blueprint`**: Executes a Blueprint file without starting a web server.
 - **`build-snapshot`**: Builds a ZIP snapshot of a WordPress site based on a Blueprint.
+- **`php`**: Runs a PHP script.
 
 The `start` command supports these common optional arguments. Run
 `npx @wp-playground/cli@latest start --help` for the full list:
@@ -291,6 +292,14 @@ The `start` command supports these common optional arguments. Run
 - `--reset`: Delete the stored site and start fresh. Defaults to false.
 - `--no-auto-mount`: Disable automatic project detection.
 
+The `php` command supports the shared runtime and mount options plus:
+
+- `--cwd=<vfs-path>`: Set the PHP process working directory to a virtual filesystem path.
+
+When `--cwd` is omitted, a single auto-mounted directory becomes the working directory
+automatically. With manual mounts or multiple auto-mounts, PHP keeps its default
+working directory unless you provide `--cwd`.
+
 The `server` command supports these common optional arguments. Run `npx @wp-playground/cli@latest server --help` for the full list:
 
 - `--port=<port>`: The port number for the server to listen on. Defaults to 9400.

diff --git a/packages/docs/site/docs/main/guides/phpunit-testing.md b/packages/docs/site/docs/main/guides/phpunit-testing.md
@@ -15,36 +15,27 @@ This guide assumes your plugin or theme has PHPUnit installed via Composer (`com
 
 ## Running tests
 
-From your plugin or theme directory, run the following command. Replace `themes/THEME_NAME` with the path to your plugin or theme:
+From your plugin or theme directory, run the following command:
 
 ```bash
 npx @wp-playground/cli@latest php \
   --auto-mount \
   -- \
-  /wordpress/wp-content/themes/THEME_NAME/vendor/bin/phpunit \
-  -c /wordpress/wp-content/themes/THEME_NAME/phpunit.xml.dist
+  vendor/bin/phpunit \
+  -c phpunit.xml.dist
 ```
 
-The `--auto-mount` flag detects whether the current directory is a plugin, theme, or WordPress installation and mounts it at the correct path under `/wordpress/wp-content/`. The `--` separates CLI flags from arguments passed to the PHP interpreter, and you can pass any arguments supported by your PHPUnit configuration.
+The `--auto-mount` flag detects whether the current directory is a plugin, theme, or WordPress installation, mounts it at the correct path under `/wordpress/wp-content/`, and uses that single mount as the PHP working directory. The same relative command works for both plugins and themes. The `--` separates CLI flags from arguments passed to the PHP interpreter, and you can pass any arguments supported by your PHPUnit configuration.
 
-For a plugin, the path would use `plugins/` instead:
-
-```bash
-npx @wp-playground/cli@latest php \
-  --auto-mount \
-  -- \
-  /wordpress/wp-content/plugins/MY_PLUGIN/vendor/bin/phpunit \
-  -c /wordpress/wp-content/plugins/MY_PLUGIN/phpunit.xml.dist
-```
-
-You can also use `--mount` to explicitly map a local directory to a path inside the Playground filesystem:
+You can also use `--mount` to explicitly map a local directory to a path inside the Playground filesystem. Set `--cwd` to that virtual path when you want to use relative command arguments:
 
 ```bash
 npx @wp-playground/cli@latest php \
   --mount=.:/wordpress/wp-content/plugins/MY_PLUGIN \
+  --cwd=/wordpress/wp-content/plugins/MY_PLUGIN \
   -- \
-  /wordpress/wp-content/plugins/MY_PLUGIN/vendor/bin/phpunit \
-  -c /wordpress/wp-content/plugins/MY_PLUGIN/phpunit.xml.dist
+  vendor/bin/phpunit \
+  -c phpunit.xml.dist
 ```
 
 ## Choosing PHP and WordPress versions
@@ -57,8 +48,8 @@ npx @wp-playground/cli@latest php \
   --php=8.1 \
   --wp=6.5 \
   -- \
-  /wordpress/wp-content/plugins/MY_PLUGIN/vendor/bin/phpunit \
-  -c /wordpress/wp-content/plugins/MY_PLUGIN/phpunit.xml.dist
+  vendor/bin/phpunit \
+  -c phpunit.xml.dist
 ```
 
 Supported PHP versions range from 7.4 to 8.5. For WordPress, you can use a specific version number, `latest`, `nightly`, or `beta`.

diff --git a/packages/php-wasm/universal/src/lib/php-worker.ts b/packages/php-wasm/universal/src/lib/php-worker.ts
@@ -220,7 +220,7 @@ export class PHPWorker implements LimitedPHPApi, AsyncDisposable {
 	/** @inheritDoc @php-wasm/universal!/PHP.cli */
 	async cli(
 		argv: string[],
-		options?: { env?: Record<string, string> }
+		options?: { env?: Record<string, string>; cwd?: string }
 	): Promise<StreamedPHPResponse> {
 		const state = _private.get(this)!;
 		const primaryPhp = state.php;

diff --git a/packages/php-wasm/universal/src/lib/php.ts b/packages/php-wasm/universal/src/lib/php.ts
@@ -16,6 +16,7 @@ import type { PHPRuntimeId } from './load-php-runtime';
 import { popLoadedRuntime } from './load-php-runtime';
 import type { PHPRequestHandler } from './php-request-handler';
 import { PHPResponse, StreamedPHPResponse } from './php-response';
+import { ErrnoError, getEmscriptenFsError } from './rethrow-file-system-error';
 import type {
 	ChildProcess,
 	MessageListener,
@@ -1703,6 +1704,21 @@ export class PHP implements Disposable {
 		const release = await this.semaphore.acquire();
 
 		return await this.#executeWithErrorHandling(() => {
+			if (options.cwd !== undefined) {
+				try {
+					this.chdir(options.cwd);
+				} catch (error) {
+					const fileSystemError = getEmscriptenFsError(error);
+					if (fileSystemError !== undefined) {
+						throw new ErrnoError(
+							(error as { errno: number }).errno,
+							`Could not change the PHP working directory to "${options.cwd}": ${fileSystemError}`,
+							{ cause: error }
+						);
+					}
+					throw error;
+				}
+			}
 			const env = options.env || {};
 			for (const [key, value] of Object.entries(env)) {
 				this.#setEnv(key, value);

diff --git a/packages/playground/cli/README.md b/packages/playground/cli/README.md
@@ -151,6 +151,14 @@ The `start` command supports these common optional arguments. Run `npx @wp-playg
 - `--reset`: Delete the stored site directory and start fresh.
 - `--no-auto-mount`: Disable automatic project detection.
 
+The `php` command supports the shared runtime and mount options plus:
+
+- `--cwd=<vfs-path>`: Set the PHP process working directory to a virtual filesystem path.
+
+When `--cwd` is omitted, a single auto-mounted directory becomes the working directory
+automatically. With manual mounts or multiple auto-mounts, PHP keeps its default
+working directory unless you provide `--cwd`.
+
 The `server` command supports these common optional arguments. Run `npx @wp-playground/cli@latest server --help` for the full list:
 
 - `--port=<port>`: The port number for the server to listen on. Defaults to 9400.

diff --git a/packages/playground/cli/src/run-cli.ts b/packages/playground/cli/src/run-cli.ts
@@ -533,6 +533,14 @@ export async function parseOptionsAndRunCLI(
 			},
 		};
 
+		const phpCommandOnlyOptions: Record<string, YargsOptions> = {
+			cwd: {
+				describe:
+					'Virtual filesystem path to use as the PHP process working directory.',
+				type: 'string',
+			},
+		};
+
 		const yargsObject = yargs(argsToParse)
 			.usage('Usage: wp-playground <command> [options]')
 			.command(
@@ -579,7 +587,10 @@ export async function parseOptionsAndRunCLI(
 					})
 			)
 			.command('php', 'Run a PHP script', (yargsInstance: Argv) =>
-				yargsInstance.options({ ...sharedOptions })
+				yargsInstance.options({
+					...sharedOptions,
+					...phpCommandOnlyOptions,
+				})
 			)
 			.demandCommand(1, 'Please specify a command')
 			.strictCommands()
@@ -828,6 +839,7 @@ export interface RunCLIArgs {
 		| BlueprintV2Declaration
 		| BlueprintBundle;
 	command: 'start' | 'server' | 'run-blueprint' | 'build-snapshot' | 'php';
+	cwd?: string;
 	debug?: boolean;
 	login?: boolean;
 	mount?: Mount[];
@@ -985,6 +997,22 @@ export async function runCLI(
 		args = expandAutoMounts(args);
 	}
 
+	let phpCommandCwd: string | undefined;
+	if (args.command === 'php') {
+		phpCommandCwd = args.cwd;
+		if (phpCommandCwd === undefined) {
+			const mounts = [
+				...(args['mount-before-install'] || []),
+				...(args.mount || []),
+			];
+			const hasManualMounts = mounts.some((mount) => !mount.autoMounted);
+			const autoMounts = mounts.filter((mount) => mount.autoMounted);
+			if (!hasManualMounts && autoMounts.length === 1) {
+				phpCommandCwd = autoMounts[0].vfsPath;
+			}
+		}
+	}
+
 	// Keeping the '--quiet' option to preserve backward compatibility
 	if (args.quiet) {
 		args.verbosity = 'quiet';
@@ -1664,7 +1692,9 @@ export async function runCLI(
 							'/internal/shared/bin/php',
 							...(args['_'] || []).slice(1),
 						];
-						const response = await playgroundPool.cli(argv);
+						const response = await playgroundPool.cli(argv, {
+							cwd: phpCommandCwd,
+						});
 						const [exitCode] = await Promise.all([
 							response.exitCode,
 							response.stdout.pipeTo(