Ehsan Bagherzadegan
Back to articles
4 min read

PIE 1.5: Explicit Extension Selection for Reproducible PHP CI Builds

PIE 1.5 removes the risky auto-selection flag and requires explicit --select mappings in CI, plus adds pie upgrade, pie search, and multi-extension installs for deterministic extension management.

PIE 1.5, released by the PHP Foundation on October 7, 2026, is the first major update to the PHP Installer for Extensions since its 1.0 launch. If your CI pipeline installs PHP extensions — redis, xdebug, amqp, or any of the dozens PIE manages — this release changes how unattended installs work and adds several commands that make extension management more predictable.

The Breaking Change: Explicit Package Selection

PIE 1.0 allowed a flag called --allow-non-interactive-project-install that let CI runs pick a package automatically when multiple providers offered the same extension. That convenience came with risk: the resolver could pick a different provider between runs, silently changing what gets built and installed.

In 1.5, that flag is deprecated and ignored. You must now use --select to tell PIE exactly which package provides each extension:

# Before (no longer works)
pie install --allow-non-interactive-project-install

# After — explicit and deterministic
pie install --select=redis=phpredis/phpredis --select=xdebug=xdebug/xdebug

The --select flag takes extension=vendor/package pairs. Run pie search <extension> to see which packages provide a given extension, then pin your choice in CI. This eliminates the "works on my machine, fails in CI" class of surprises where a different package version or provider gets pulled.

Install Multiple Extensions in One Command

You no longer need a separate pie install call per extension. A single command accepts multiple arguments:

pie install phpredis/phpredis:^6.0 xdebug/xdebug:^3.3 girgias/csv:^1.0

Each argument can include a version constraint. PIE resolves all of them together, which is faster and avoids partial-state failures when one extension depends on another's headers.

New pie upgrade Command

Extensions installed via PIE now track the version constraint used at install time. pie upgrade reads those constraints and upgrades each extension within its allowed range:

pie upgrade
# Upgrades phpredis/phpredis within ^6.0, xdebug/xdebug within ^3.3, etc.

This is safer than re-running pie install with new constraints because it respects the boundaries your project originally accepted. Dev-only extensions (installed via require-dev) are skipped unless you pass --dev.

pie search: Discover Packages Before You Install

Instead of guessing package names, search the registry:

$ pie search redis
phpredis/phpredis       ^6.0   phpredis - PHP extension for Redis
predis/predis           ^2.0   Pure PHP Redis client (no extension)

The output shows the package name, latest version matching your PHP version, and a short description. Use this to find the exact --select value for your CI config.

pie check-build-tools: Fail Fast on Missing Toolchains

Before PIE 1.5, a missing make, autoconf, or pkg-config would surface halfway through a build with a cryptic compiler error. Now you can verify the toolchain upfront:

pie check-build-tools
# ✓ make found
# ✓ autoconf found
# ✓ pkg-config found
# ✓ gcc found

Add this as a preliminary step in CI to catch environment drift early.

--no-dev and --from-lock for Cleaner Installs

  • --no-dev skips extensions listed only in require-dev (like xdebug) during project installs. Useful for production Docker builds.
  • --from-lock installs exclusively from pie.lock, ignoring composer.json. This guarantees reproducible installs when you commit the lock file.

Sigstore Attestation Overhaul

Under the hood, PIE 1.5 rewrote its verification library. The new implementation passes 131 Sigstore conformance tests, decouples from GitHub-specific attestations, and adds SBOM (Software Bill of Materials) support. For teams with supply-chain policies, this means every installed extension now carries verifiable provenance without relying on a single platform's attestation format.

Upgrading Your CI Pipeline

A typical GitHub Actions workflow before and after:

# .github/workflows/test.yml (PIE 1.0 style — now broken)
- name: Install extensions
  run: pie install --allow-non-interactive-project-install

# .github/workflows/test.yml (PIE 1.5 style)
- name: Verify build tools
  run: pie check-build-tools

- name: Install extensions
  run: |
    pie install \
      --select=redis=phpredis/phpredis \
      --select=xdebug=xdebug/xdebug \
      --select=amqp=php-amqp/php-amqp

If you maintain a matrix across PHP versions, define the --select mapping once and reuse it — the package names don't change per PHP version, only the resolved extension version does.

When to Upgrade

  • Immediately if your CI uses --allow-non-interactive-project-install — it stops working.
  • Soon if you want pie upgrade for ongoing maintenance, or pie search to simplify adding new extensions.
  • Optional if you install extensions manually and don't use CI automation.

PIE 1.5.5 (October 30) also includes a security fix (GHSA-4538-pqqf-mv67), so pinning to ^1.5.5 is recommended.

Summary

PIE 1.5 trades implicit convenience for explicit control. The --select requirement is the headline change, but the new commands — upgrade, search, check-build-tools — and the ability to install multiple extensions at once make day-to-day extension management more reliable. Update your CI configs, commit your pie.lock, and you'll spend less time debugging environment differences.

Sources