Docs update for 1.5.x so far

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:
@@ -99,11 +108,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
 

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,15 @@ 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
+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).

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.
@@ -113,7 +121,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 +130,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       |
 
@@ -218,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
@@ -421,6 +431,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