[CLI] php command to run PHP scripts

[adamziel]

Motivation for the change, related issues

Adds a new CLI command called php that can run PHP scripts using the PHP CLI SAPI.

Try it locally as follows:

mkdir tmp
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
cp wp-cli.phar tmp
node --no-warnings=ExperimentalWarning  --experimental-strip-types --experimental-transform-types --import ./packages/meta/src/node-es-module-loader/register.mts ./packages/playground/cli/src/cli.ts -- php=8.0 --mount-before-install=./tmp:/wordpress --skip-wordpress-setup -- php /wordpress/wp-cli.phar user list

You should see:

Starting a PHP server...
Setting up WordPress latest
Resolved WordPress release URL: https://downloads.w.org/release/wordpress-6.8.2.zip
Fetching SQLite integration plugin...
Booting WordPress...
Booted!
Running the Blueprint...
Running the Blueprint – 100%
Finished running the blueprint
+----+------------+--------------+---------------------+---------------------+---------------+
| ID | user_login | display_name | user_email          | user_registered     | roles         |
+----+------------+--------------+---------------------+---------------------+---------------+
| 1  | admin      | admin        | [email protected] | 2025-07-15 23:08:50 | administrator |
+----+------------+--------------+---------------------+---------------------+---------------+

The part after the double dash is the php command to run, in this case it's php /wordpress/wp-cli.phar user list

Discussion

Developer experience

The command accepts all the same parameters as the server command. This means two things:

• It is a powerful low-level tool that can reproduce the same PHP runtime as the server command.
• It is very annoying to use.

Let's discuss how can we simplify the experience without adding implicit magic.

Paths

All the paths are VFS paths, see how I'm running php /wordpress/wp-cli.phar and not php ./wp-cli.phar. I'd love to be able to run php ./wp-cli.phar --import-wxr=./wxr.xml and such – is there any sensible way of making it happen?

Using only host paths isn't an option. The complete site directory structure only exists in VFS. I can't think of a portable way of re-creating /wordpress on host. Even with native mounts in place, there may be 15 different mounts in VFS /wordpress that are not there on host and that we cannot easily overlay on host.

Mixing host paths and WordPress paths feels super risky. Imagine we magically had a way to resolve both /wordpress/wp-cli.phar and /Users/adam/www/wp/wp-cli.phar. Are we better off in any way now? What's cwd and how do we calculate the path when wp-cli command refers to ../imports/wxr.xml? What if both VFS and host have different files under that path? How would rename etc. work?

That leaves us with only one option – using only VFS paths like we would do in Docker. This complicates things for the package consumer – we need to train them to mount their PHP scripts and source data like they'd do with Docker.

Can anyone see any alternatives?

Auto-download wp-cli.phar

We could ship two commands: php that lets you run any command, and wp that downloads and runs wp-cli.phar specifically. That way we'd save folks from typing that same one mount every single time.

cc @JanJakes @zaerl @brandonpayton @Jameswlepage @akirk