Allow embedding the PHP CLI and installing it

[withinboredom]

This allows embedding a statically built php-cli in the FrankenPHP binary and offers a command to install the embedded PHP CLI if it is embedded. This provides users with a way to avoid having to have php-cli installed for running things like workers, or certain scripts.

Example usage:

❯ frankenphp install-php php
❯ ./php --version
PHP 8.4.7 (cli) (built: May 13 2025 23:26:58) (ZTS)
Copyright (c) The PHP Group
Zend Engine v4.4.7, Copyright (c) Zend Technologies

[AlliBalliBaba]

I guess I'd be fine with merging this as an experimental feature. If it ends up being the way we go about cli, it would also be nice to have some kind of test or sanity check. Depends on what @dunglas thinks.

How much bigger does the binary end up being?

[henderkes]

About 20-30mb before compression I think.

That's quite something for the musl binary, but the gnu binary is comically large already anyway. I couldn't find a way for FrankenPHP to retain extension loading symbols without marking all exports as dynamic.

And I don't think this should be the recommended way to go about installing php. The recommended way is using docker, homebrew, or soon package repositories (I've finished rpm support, but debian will still take a while and I'm not sure if I can even do alpine on the same runner).

Long term it would be great if php-cli is written as a wrapper about libphp.so, then integrating all options into frankenphp php-cli would become trivial.

[dunglas]

Why not merge this, but then we should make it very clear that it's a temporary workaround while we're working on making the CLI SAPI embed-friendly.

[henderkes]

Yeah, thinking about it in this way, it might be smarter to do the extraction ourselves in the background (even if it causes problems with /tmp/) only when necessary and pass the php-cli arguments to that php.
If it fails, print a warning and fall back to ignoring the incompatible arguments and attempting the baked in php-cli command.

It also depends on the timeline a bit, if the cli sapi can be reworked in a few weeks, we shouldn't offer this even temporarily, if it might take years, that's a different story.

[withinboredom]

I don't think it would be wise to extract it to the filesystem and execute it in the background. For a number of reasons (not just security).

I've already started experimenting with ways to export the main method of php-cli. It's not entirely straightforward (some big refactors if doing it properly). It may be worth bringing up on internals, because it's new code to maintain for a niche purpose. It also exposes this as part of the php ABI AND user API and they both have different "SLAs" (to put it in corporate speak). One can change somewhat freely, while one requires an RFC.

[bukka]

Usually SAPI's (cli and embed) should not share functionality so we would be probably more looking to move the common functionality to main/ so it can be re-used / exported. This can, of course, happen only in the minor version update so if you don't manage to do it in the next few months, then it's next year timeline...

[bukka]

It really just need php-src PR to happen. I don't think you need internals discussion for this. It can be merged when the PR is ready as it's really just an internal change.

[withinboredom]

Thanks @bukka! I am on it then!

[henderkes]

Can close this. CLI refactor is quite pain free.