devTalk

Posted on Oct 18 Originally published at dev-talk.com

PHP PIE: Install PHP Extensions Now That PECL Is Deprecated

#php #pie #pecl #phpextensions

For years the answer to "how do I install a PHP extension?" was pecl install something. That answer has an expiry date. In September 2025 the PHP community voted to deprecate PECL as the recommended way to install extensions and to adopt a new tool in its place: PIE, the PHP Installer for Extensions. If you maintain servers, Dockerfiles or CI images, you will meet it soon. I installed PIE 1.5.2 (the current release when I wrote this), built a real extension with it, and uninstalled it again, so this covers what actually happens and a few details the docs do not spell out.

What PIE is, and what happened to PECL

PIE is distributed as a PHAR, like Composer, but instead of adding libraries to a project it installs extensions into your PHP installation. Extensions are found through Packagist rather than the PECL website. Under the hood it downloads the source, runs phpize, configure and make, copies the .so into your extension directory and adds the extension= line for you. On Windows it uses precompiled DLL packages, so no compiler is needed there.

The deprecation came from the RFC "Recommend PIE and deprecate PECL", which passed with 36 yes, 0 no and 5 abstentions. Two details are worth knowing. First, it is a messaging change only: the RFC says PECL keeps working, and it sets no removal date. Second, a separate RFC would be needed to propose a timeline for removing the PECL site and tool. Nothing breaks today, but new guidance and documentation will point to PIE.

Install PIE

You need PHP 8.1 or newer to run PIE itself, although it can install an extension into a different PHP version. Download pie.phar from the GitHub releases page. The README documents a one-liner for non-Windows systems and suggests verifying the download with gh attestation verify --owner php pie.phar. I downloaded the latest release PHAR directly and ran it:

curl -sSL -o pie.phar https://github.com/php/pie/releases/latest/download/pie.phar
php pie.phar --version
# PHP Installer for Extensions (PIE) 1.5.2

sudo mv pie.phar /usr/local/bin/pie     # optional: put it on your PATH
chmod +x /usr/local/bin/pie

Then check that the machine can compile extensions:

pie check-build-tools

On my test machine it listed make, autoconf, pkg-config, libtool, unzip and phpize as installed. The docs list git autoconf automake libtool m4 make gcc as the Linux and macOS requirements, and you also need your PHP version's development package (the one that provides phpize).

PECL commands and their PIE equivalents

Task	PECL	PIE
Install	`pecl install xdebug`	`pie install xdebug/xdebug`
Show extension info	`pecl info xdebug`	`pie info xdebug/xdebug`
List installed	`pecl list`	`pie show`
Download source only	`pecl download xdebug`	`pie download xdebug/xdebug`
Build without installing	`pecl build xdebug`	`pie build xdebug/xdebug`
Remove	`pecl uninstall xdebug`	`pie uninstall xdebug/xdebug`

The main change is the name: PIE uses a Composer-style vendor/package, so xdebug becomes xdebug/xdebug. Browse PIE-compatible packages on packagist.org/extensions. The 1.5.2 binary also lists search and upgrade commands; the docs I read still point to the Packagist list for searching and say to use pie install again to upgrade, so check pie list on your version.

A full install, start to finish

Packagist was not reachable from my test environment, so I could not install a public extension such as Xdebug. Instead I wrote a tiny extension with one function, added its composer.json with "type": "php-ext", and pointed PIE at the folder with a path repository. The flow is identical to a normal install except for where the source comes from:

pie repository:add path /path/to/pieh
pie info demo/pieh
pie install demo/pieh

The output of the install, trimmed:

Found package: demo/pieh:0.1.0 which provides ext-pieh
Extracted demo/pieh:0.1.0 source to: ~/.config/pie/php8.3_.../vendor/demo/pieh
phpize complete.
Configure complete with options: --with-php-config=/usr/bin/php-config
Build complete: .../modules/pieh.so
Install complete: /usr/lib/php/20230831/pieh.so
Extension demo/pieh:0.1.0 is enabled and loaded in /usr/bin/php8.3

Afterwards php -m listed the extension, the function worked, and PIE had created an INI file in the CLI conf.d folder containing a comment ("PIE automatically added this to enable the demo/pieh extension"), a priority=80 note and the line extension=pieh. pie show reported pieh:0.1.0 (from demo/pieh:0.1.0). Notice that PIE did one thing for you that PECL users used to do by hand: enabling the extension.

What uninstall leaves behind

Running pie uninstall demo/pieh removed the .so from the extension directory and the extension disappeared from php -m. But the INI file stayed. PIE had only commented out the line: ; extension=pieh ; removed by PIE. That is harmless, and it is a sensible way to avoid deleting config you may have edited, but if you manage servers with configuration tooling, expect to see these leftover files and clean them up if you want a tidy tree.

Using PIE in Docker and CI

In non-interactive environments you need to answer PIE's prompts up front. The docs list --auto-install-build-tools and --auto-install-system-dependencies for that, and the README says to use --select when installing project dependencies, for example --select redis=phpredis/phpredis. The docs also include a Dockerfile pattern that copies the PIE binary in from the ghcr.io/php/pie:bin image for one build step, so PIE never ends up in the final image:

FROM php:8.4-cli

RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin/pie \
    set -eux; \
    apt-get update; \
    apt-get install -y --no-install-recommends unzip; \
    pie install --no-cache asgrim/example-pie-extension; \
    apt-get purge -y --auto-remove unzip; \
    rm -rf /var/lib/apt/lists/*;

That snippet is condensed from the official docs, and I did not build it myself. Remember that compiling needs build tools in the image; use a multi-stage build if you want them out of the final layer.

Common problems

Missing build tools. Run pie check-build-tools. From PIE 1.4.0 it can offer to install them for you.
Several PHP versions. Pass --with-php-config=/usr/bin/php-config8.2 (and the matching --with-phpize-path if needed) to target another version. PIE prints the "Target PHP installation" at the top of every command, so read it before you confirm.
Permissions. The extension is copied into your PHP extension directory, such as /usr/lib/php/20230831 in my test. I ran as root, and the docs give no sudo guidance, so on a normal system plan for a privileged install.
Not every PECL package is on PIE yet. A package must be PIE-compatible (type php-ext) and published on Packagist. If it is missing, ask the maintainer or add a VCS repository with pie repository:add vcs <url>.
Configure options. Only the options an extension declares can be passed, and pie info vendor/package lists them.

For extension authors

Making your extension installable is mostly a composer.json. It needs "type": "php-ext" (or php-ext-zend for Zend extensions) and an optional php-ext block with keys such as extension-name, configure-options, build-path and os-families. My whole demo manifest was a name, a type, a license, a PHP requirement and "php-ext": {"extension-name": "pieh"}.

Frequently asked questions

Is PECL removed in PHP 8.5?

No. The RFC is a messaging change that sets no removal date, and PECL continues to work for now.

Can PIE install the bundled extensions like mysqli or gd?

PIE is for extensions that are not bundled with PHP. For bundled ones, keep using your usual method, such as your distribution's packages or the Docker image's docker-php-ext-install.

Does PIE replace Composer?

No. Composer manages PHP libraries for a project. PIE manages compiled extensions for a PHP installation. They share the package format and Packagist.

References

Originally published on DEV Talk.

DEV Community