From fc12c4f1d02c89715a9dbde31412a9ba1c4449a4 Mon Sep 17 00:00:00 2001 From: James Titcumb Date: Thu, 2 Jul 2026 09:03:05 +0100 Subject: [PATCH 1/7] Docs for --select package selections --- README.md | 12 ++++++++---- docs/usage.md | 28 ++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 690e3ab2..8a721deb 100644 --- a/README.md +++ b/README.md @@ -99,11 +99,15 @@ The following packages may be suitable, which would you like to install: Finished checking extensions. ``` -> [!TIP] +> [!IMPORTANT] > If you are running PIE in a non-interactive shell (for example, CI, a -> container), pass the `--allow-non-interactive-project-install` flag to run -> this command. It may still fail if more than one PIE package provides a -> particular extension. +> container), the `--allow-non-interactive-project-install` is no longer +> functional. You must specify `--select` flags for each missing package, e.g.: +> ```bash +> pie install \ +> --select example_pie_extension=asgrim/example-pie-extension \ +> --select redis=phpredis/phpredis +> ``` ## Extensions that support PIE diff --git a/docs/usage.md b/docs/usage.md index b1ac5624..ce421ef5 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -421,6 +421,34 @@ The following packages may be suitable, which would you like to install: Finished checking extensions. ``` +### Telling PIE which packages to use for missing extensions + +You can provide PIE a map of which packages to use for each missing extension +using the new `--select` option in PIE 1.5+. For example, if your PHP project +has dependencies: + +```json +{ + "require": { + "ext-curl": "*", + "ext-example_pie_extension": "^2.0", + "ext-redis": "^6.3" + } +} +``` + +You can specify the missing extensions with: + +```bash +pie install \ + --select example_pie_extension=asgrim/example-pie-extension \ + --select redis=phpredis/phpredis +``` + +> [!IMPORTANT] +> The `--allow-non-interactive-project-install` will no longer work. You must +> provide package selections from PIE 1.5 onwards. + ## Comparison with PECL Since PIE is a replacement for PECL, here is a comparison of the commands that From a06b041b5783db6387f4f625ad80a35710048776 Mon Sep 17 00:00:00 2001 From: James Titcumb Date: Thu, 2 Jul 2026 09:07:36 +0100 Subject: [PATCH 2/7] Temporarily remove Windows pie.exe links until fixed --- docs/usage.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/usage.md b/docs/usage.md index ce421ef5..76de3fc4 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -113,7 +113,6 @@ stable releases can be downloaded from these links: |------------------|------------------|-------------------------------------------------------------------------| | Linux | amd64 / x86_64 | https://github.com/php/pie/releases/latest/download/pie-Linux-X64 | | OS X | ARM 64 / aarch64 | https://github.com/php/pie/releases/latest/download/pie-macOS-ARM64 | -| Windows | x86_64 | https://github.com/php/pie/releases/latest/download/pie-Windows-X64.exe | | Linux | ARM 64 / aarch64 | https://github.com/php/pie/releases/latest/download/pie-Linux-ARM64 | | OS X | Intel / x86_64 | https://github.com/php/pie/releases/latest/download/pie-macOS-X64 | @@ -123,7 +122,6 @@ The "nightly" versions of these can be found here: |------------------|------------------|-----------------------------------------------| | Linux | amd64 / x86_64 | https://php.github.io/pie/pie-Linux-X64 | | OS X | ARM 64 / aarch64 | https://php.github.io/pie/pie-macOS-ARM64 | -| Windows | x86_64 | https://php.github.io/pie/pie-Windows-X64.exe | | Linux | ARM 64 / aarch64 | https://php.github.io/pie/pie-Linux-ARM64 | | OS X | Intel / x86_64 | https://php.github.io/pie/pie-macOS-X64 | From 8bd223d483fc92da779c41a54369cd54b0db472f Mon Sep 17 00:00:00 2001 From: James Titcumb Date: Thu, 2 Jul 2026 09:11:07 +0100 Subject: [PATCH 3/7] Add multiple exts at once example --- README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README.md b/README.md index 8a721deb..56ff85b9 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,15 @@ Install complete: /usr/lib/php/20250925/example_pie_extension.so $ ``` +### Installing multiple extensions at once + +As of PIE 1.5 you can install multiple extensions at the same time. Note that +if multiple extensions share the same configure options, this command will fail. + +```shell +pie install foo/great-extension bar/another-extension +``` + ### Installing all extensions for a PHP project When in your PHP project, you can install any missing top-level extensions: From d7e1e2c91f3e6fcb1c2e5afed4aca7ee61a19b43 Mon Sep 17 00:00:00 2001 From: James Titcumb Date: Thu, 2 Jul 2026 09:17:19 +0100 Subject: [PATCH 4/7] Update docker tag options docs --- docs/usage.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/usage.md b/docs/usage.md index 76de3fc4..2c35dca3 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -55,7 +55,15 @@ RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin pie -V ``` -Instead of `bin` tag (which represents latest binary-only image) you can also use explicit version (in `x.y.z-bin` format). Use [GitHub registry](https://ghcr.io/php/pie) to find available tags. +The following tag styles (replace them with the real version you want!): are published from 1.5+: + + * `bin` (latest _stable_, **recommended**) + * `nightly-bin` (latest _unstable_) + * `x.y.z-bin` (e.g. `1.5.0-bin`) + * `x.y-bin` (e.g. `1.5-bin`) + * `x-bin` (e.g. `1-bin`) + +Use [GitHub registry](https://ghcr.io/php/pie) to find available tags. > [!IMPORTANT] > Binary-only images don't include PHP runtime so you can't use them for _running_ PIE. This is just an alternative way of distributing PHAR file, you still need to satisfy PIE's runtime requirements on your own. From b8ff62b6821c5957f0d46c278fbb6d21a7fe30fe Mon Sep 17 00:00:00 2001 From: James Titcumb Date: Thu, 2 Jul 2026 09:19:23 +0100 Subject: [PATCH 5/7] Note about re-install no-ops --- docs/usage.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/usage.md b/docs/usage.md index 2c35dca3..48bab4a4 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -224,6 +224,10 @@ This will install the Xdebug extension into the version of PHP that is used to invoke PIE, using whichever is the latest stable version of Xdebug compatible with that version of PHP. +> [!TIP] +> If PIE detects the extension of the same version with the same configure flags +> is already installed, as of PIE 1.5, it will no longer be re-installed. + ### Using PIE to install an extension for a different PHP version If you are trying to install an extension for a different version of PHP, you From bde52f991a627f83ddc2f619317e82e4b19f60db Mon Sep 17 00:00:00 2001 From: James Titcumb Date: Thu, 2 Jul 2026 09:21:30 +0100 Subject: [PATCH 6/7] Note about thecodingmachine/safe --- docs/pie-maintainers-handbook.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/pie-maintainers-handbook.md b/docs/pie-maintainers-handbook.md index 230afdb6..30963c8e 100644 --- a/docs/pie-maintainers-handbook.md +++ b/docs/pie-maintainers-handbook.md @@ -150,6 +150,11 @@ To attempt to auto-apply CS fixes: vendor/bin/phpcbf ``` +As of PIE branch 1.5.x and newer, we use the library +[thecodingmachine/safe](https://github.com/thecodingmachine/safe) to throw +exceptions instead of returning `false` when PHP functions are called. There is +a static analysis rule in place to enforce this. + ### Mutation Testing Install the `infection.phar` according to the [Infection PHP documentation](https://infection.github.io/guide/installation.html#Phar). From 0d7d24e76bbd3e8efdad42ef1ace603d30e82899 Mon Sep 17 00:00:00 2001 From: James Titcumb Date: Thu, 2 Jul 2026 09:39:29 +0100 Subject: [PATCH 7/7] Update maintainer docs with some more general info --- docs/pie-maintainers-handbook.md | 46 ++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/docs/pie-maintainers-handbook.md b/docs/pie-maintainers-handbook.md index 30963c8e..7123ec3d 100644 --- a/docs/pie-maintainers-handbook.md +++ b/docs/pie-maintainers-handbook.md @@ -63,6 +63,48 @@ developing on PIE, you will likely need to run some, or all, of these tests by h > [!TIP] > The development guide is primarily aimed at Linux systems, please adjust accordingly for your own platform. +### Architecture overview + +Some key concepts are used in PIE; + + - **Target PHP**: PIE can be invoked like `/path/to/php /path/to/pie ...` or with + `pie --with-php-config=/path/to/php/config`. This means that the PHP instance running PIE may not be the same PHP + instance we're installing the extensions for. For example, if you're using Ondrej Sury's DEB installer, you could + invoke `/usr/bin/php8.4 /usr/local/bin/pie --with-php-config=/usr/bin/php-config7.2` which would run PIE with + PHP 8.4, but compile and install the extension for the PHP 7.2 instance. In the code, this is represented by the + `\Php\Pie\Platform\TargetPhp\PhpBinaryPath` class. + - **Target Platform**: Along with the above **Target PHP**, the Target Platform describes other facets of the platform, + such as OS, thread safety option, architecture (`x86_64`, `x86`, `arm64`, etc.). This is represented by the + `\Php\Pie\Platform\TargetPlatform` class. + +#### Entry point and DI + +When running for development, `bin/pie` bootstraps a Symfony Console `Application` using `Container::factory()`, which +wires everything with the [Laravel/Illuminate Container](https://laravel.com/docs/container). + +This entrypoint is also used by the PHAR file when built. + +#### Typical extension installation flow + +The flow for resolving and installing an extension: + +1. **Resolve** – `DependencyResolver` (`src/DependencyResolver/`) uses Composer's solver via + `ResolveDependencyWithComposer` to find a compatible `ResolvedPackageRequest`. +2. **Download** – Composer's installer downloads/extracts the source. However, `OverrideDownloadUrlInstallListener` is + is a Composer plugin listener that potentially changes the download URL, for example when using Windows, or the + pre-built source or pre-built binary options are used. +3. **Build** – `Build` (`src/Building/`) runs `phpize` + `./configure` + `make` (`UnixBuild`) or uses the pre-built DLL + on Windows (`WindowsBuild`), unless the pre-built binary option is used. +4. **Install** – `Install` (`src/Installing/`) copies the `.so`/`.dll` and enables the extension in the INI via + `Ini\SetupIniApproach` (picks the best strategy: `phpenmod`, `docker-php-ext-enable`, or direct INI edit). + +This pipeline is coordinated by `InstallAndBuildProcess` (`src/ComposerIntegration/InstallAndBuildProcess.php`) called +from Composer event listeners in `src/ComposerIntegration/Listeners/`. + +The operation mode is tracked by the `PieOperation` enum (`src/ComposerIntegration/PieOperation.php`): `Resolve`, +`Download`, `Build`, `Install`, `Uninstall`. `PieComposerRequest` carries this value plus target platform and configure +options into the Composer run. + ### Unit & Integration Tests > [!CAUTION] @@ -150,6 +192,10 @@ To attempt to auto-apply CS fixes: vendor/bin/phpcbf ``` +Classes marked `@internal` are not part of PIE's public API. Almost everything in the codebase should be marked as +`@internal`, except things like exceptions. At this time PIE does not provide any extensibility or API surface to +interact with. + As of PIE branch 1.5.x and newer, we use the library [thecodingmachine/safe](https://github.com/thecodingmachine/safe) to throw exceptions instead of returning `false` when PHP functions are called. There is