Add PHP CLI working directory support

[benitoalba]

Motivation for the change, related issues

The php command currently requires absolute VFS paths for scripts and related configuration, even when a plugin or theme has already been auto-mounted. This makes common commands such as PHPUnit unnecessarily verbose.

Fixes #3803.

Implementation details

• Add a PHP-command-only --cwd=<vfs-path> option and expose it through RunCLIArgs.
• Use an explicit CWD when provided; otherwise infer the sole auto-mounted VFS path only when no manual mounts are configured.
• Pass the CWD together with the PHP CLI invocation so the selected pooled worker changes directory before execution.
• Preserve the existing default working directory for zero, manual, and ambiguous multi-mount configurations.
• Report invalid working directories with a descriptive filesystem error.
• Document php, --cwd, and relative PHPUnit command/configuration paths.

Testing Instructions (or ideally a Blueprint)

npm exec nx -- run playground-cli:test-playground-cli --testFiles=packages/playground/cli/tests/run-cli.spec.ts
npm exec nx -- run playground-cli:test-playground-cli
npm exec nx -- run playground-cli:lint
npm exec nx -- run playground-cli:typecheck
npm exec nx -- run playground-cli:build
npm exec nx -- run php-wasm-universal:lint
npm exec nx -- run php-wasm-universal:typecheck
npm exec prettier -- --check packages/playground/cli/src/run-cli.ts packages/php-wasm/universal/src/lib/php-worker.ts packages/php-wasm/universal/src/lib/php.ts packages/playground/cli/tests/run-cli.spec.ts packages/playground/cli/README.md packages/docs/site/docs/developers/05-local-development/04-wp-playground-cli.md packages/docs/site/docs/main/guides/phpunit-testing.md
git diff --check

The full Playground CLI suite passes with 190 tests passed and 6 platform-specific tests skipped.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds support for a PHP-specific working directory (--cwd) so PHP CLI executions can use relative script/config paths when a project is auto-mounted, reducing the need for verbose absolute VFS paths.

Changes:

• Introduces --cwd=<vfs-path> for the php command and threads it through CLI parsing and pooled worker execution.
• Infers the PHP working directory from a single auto-mounted path when no manual mounts exist and --cwd is omitted.
• Adds tests and documentation covering explicit/inferred/default cwd behavior and relative PHPUnit paths.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/playground/cli/src/run-cli.ts	Adds --cwd option for php, infers cwd from mounts, and passes cwd into pooled PHP CLI calls.
packages/php-wasm/universal/src/lib/php.ts	Applies options.cwd by calling chdir() before execution and wraps filesystem errors with a clearer message.
packages/php-wasm/universal/src/lib/php-worker.ts	Extends worker cli() options type to include cwd.
packages/playground/cli/tests/run-cli.spec.ts	Adds coverage for explicit cwd, inference rules, default behavior, and rejection cases.
packages/playground/cli/README.md	Documents php --cwd semantics and inference behavior.
packages/docs/site/docs/developers/05-local-development/04-wp-playground-cli.md	Adds php command and --cwd documentation to developer docs.
packages/docs/site/docs/main/guides/phpunit-testing.md	Updates PHPUnit guide to use relative paths with auto-mount/cwd support and documents --cwd with manual mounts.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.