From 548463bad1f72c97f68b47f54a263a4f4ad87b3a Mon Sep 17 00:00:00 2001 From: nsfisis Date: Sat, 15 Aug 2026 07:37:45 +0900 Subject: feat(php-rpc): embed the Composer PHP runtime in the executable Plugins and scripts need the real `Composer\` classes and the packages Composer depends on, which so far came from a checkout found through SHIRABE_COMPOSER_PHP_DIR or a path next to the workspace. Neither exists for a distributed binary. The build script now archives those PHP sources into a phar the way Compiler.php does and the executable carries it. The worker maps it with Phar::loadPhar and reads a content-addressed sentinel back to tell a bundle it can use from one it cannot; where its PHP cannot open the phar, the bundle is unpacked once into the cache directory and autoloaded from there. SHIRABE_COMPOSER_PHP_DIR still overrides both for development. PHP locates a phar's manifest by the first __HALT_COMPILER(); token in the file, so the executable must hold no other copy of it: phar.rs builds the token at run time, and a linter keeps further literals out of the sources that reach the binary. Co-Authored-By: Claude Opus 5 (1M context) --- docs/dev/composer-runtime-bundle.md | 40 +++++++++++++++++++++++++++++++++++++ docs/dev/php-rpc.md | 13 +++++++----- 2 files changed, 48 insertions(+), 5 deletions(-) create mode 100644 docs/dev/composer-runtime-bundle.md (limited to 'docs') diff --git a/docs/dev/composer-runtime-bundle.md b/docs/dev/composer-runtime-bundle.md new file mode 100644 index 00000000..f152897f --- /dev/null +++ b/docs/dev/composer-runtime-bundle.md @@ -0,0 +1,40 @@ +# Composer runtime bundle + +Composer plugins and scripts expect the real PHP classes in `Composer\` itself +and packages that Composer depends on to be available. Shirabe embeds the +runtime PHP sources into the binary at compile time. + +## Building and embedding the bundle + +Shirabe archives all PHP sources and resources of Composer and its dependencies, +and embeds the archived phar file into the binary. Shirabe also calculates a +hash value from all included files and puts a file that contains the hash, +`shirabe/bundle-id`. It is used for verifying the bundle. See +`crates/shirabe-php-rpc/build.rs` for details. + +### Phar signature + +A phar signature is an optional signature to verify the archive's integrity, and +must be appended to the end of the file. Shirabe's runtime bundle has no +signature because the bundle is not always at the end of the executable file. +To disable phar verification, the PHP worker is started with `-d phar.require_hash=0`. +The worker restores it to `1` right after opening the bundle, so that the rest +of the process still verifies the phars it opens. A verification result is +cached per file, and the bundle is never re-verified. + +### `__HALT_COMPILER();` tokens + +A phar file consists of 3 or 4 sections: a stub, a manifest, the actual contents +and an optional signature. The stub and the manifest are separated by +`__HALT_COMPILER();` tokens, which means that Shirabe's executable binary +must not contain the tokens except for phar's one. + +## Accessing files at runtime + +Shirabe tries to open the embedded bundle, and sets the executable as the base +path of autoloading. If loading phar fails for some reason, e.g., no phar ext, +Shirabe unpacks the archive to `/runtime/` once, +and uses that directory for the base path instead. + +NOTE: the environment variable `SHIRABE_COMPOSER_PHP_DIR` can override the +location for development. diff --git a/docs/dev/php-rpc.md b/docs/dev/php-rpc.md index 8418db88..b1c992d7 100644 --- a/docs/dev/php-rpc.md +++ b/docs/dev/php-rpc.md @@ -7,12 +7,15 @@ runtime. The `shirabe-php-rpc` crate spawns the system PHP as a child process and talks to it over a Unix domain socket. There is exactly one child process per Shirabe process, shared by every caller. -## Locating PHP +## Locating and spawning PHP -The existing `PhpExecutableFinder` class resolves the PHP binary. The child is started with -`-d serialize_precision=-1` so the wire codec's float formatting is pinned to the default PHP -behavior, and with `-d xdebug.mode=off` unless `COMPOSER_ALLOW_XDEBUG` asks for Xdebug to stay -(see `xdebug.md`). +The existing `PhpExecutableFinder` class resolves the PHP binary. + +The child is started with the following arguments: + +* `-d serialize_precision=-1` for stable float formatting of `serialize()`/`unserialize()` +* `-d phar.require_hash=0` (see [docs/dev/composer-runtime-bundle.md](./composer-runtime-bundle.md)) +* `-d xdebug.mode=off` (see [docs/dev/xdebug.md](./xdebug.md)) ## Transport -- cgit v1.3.1-4-g156e