PHP Installer for Extensions (PIE): What to Know Before General Release

One of the most powerful benefits of the PHP language is its extensibility. In fact, almost every part of the language is implemented as a PHP extension, including some of the most used aspects of the language: DateTime, Random, cURL, PDO (and all RDBMS compatibility!), and many others. However, this versatility comes at a price, and managing extensions is often named as one of the top challenges of working in PHP. While this task has been traditionally handled with PHP PECL, the ecosystem is evolving with new tools to simplify PHP extension management.

In this article, we'll talk about how PHP sysadmins have traditionally managed PHP extensions, and then introduce the upcoming PHP Installer for Extensions (PIE), a new utility being developed under the umbrella of The PHP Foundation.

Traditional PHP Extension Management With PHP PECL

PHP extensions are written in C or C++, and then compiled against the version of PHP you want to use. However, in order to use an extension, it must be enabled at the system level; this is to ensure that symbols are present to the engine at startup. Most binary PHP distributions — such as the one that comes with a Linux distribution — will also provide pre-compiled binaries for the most commonly used extensions. But if you write your own extension, need to use a specific, older version of an extension, or need an extension not provided by the distribution, you will need to compile it.

PHP provides several low-level utilities for preparing an extension for compilation:

• phpize prepares the build environment for a PHP extension
• php-config is a utility used in conjunction with phpize to get information about the selected PHP being built against, including things such as shared library directories.

After downloading and extracting extension source code, you run phpize for the version of PHP you are using, telling it the location of the associated php-config utility. From there, you follow a standard C toolchain of ./configure, make, and make install.

There are several issues with this approach:

• You have to locate the source code for the extension yourself.
• You have to know where phpize and php-config live, and the steps to preparing and compiling the extension.

The solution to these issues since PHP 3 has been the PHP Extension Community Library, more commonly known as PHP PECL. PECL is both a repository of PHP extensions, as well as a command-line tool bundled with PHP. The tooling will identify where a particular extension's source code (and specific version of it) lives, download it, run the various commands to prepare it for compilation against your selected PHP version, compile it, and install it.

The problem is that that starting with PHP 8, PHP PECL largely fails, emitting a ton of deprecation notices, and, in later PHP 8 versions, a number of fatals.

The reason for this is because the tool itself is built on top of pear ("PHP Extension and Application Repository," which unlike PECL, deals only with userland PHP libraries and not extensions), and the pear utility has not kept up-to-date with PHP 8. The code base is significantly large and complex enough that nobody has stepped up to make it compatible, which in turn has made extension compilation more difficult for many.

Note: ZendPHP's zendphpctl acknowledges this gap, and has tooling for most of what the pecl utility has traditionally provided for end-users via the zendphpctl ext install subcommand. See our extension compilation documentation for further details.

The PHP Installer for Extensions: Overview and Key Features

A little over a year ago, The PHP Foundation acknowledged this gap in the pecl utility, and sponsored James Titcumb to develop a new utility to fulfill these purposes. I (Matthew Weier O'Phinney, Principal Product Manager at Zend) made the original suggestion of "PIE" as the name for the utility, and the suggestion stuck.

The design document states a few significant goals:

• The utility will continue to be written in PHP, and use the version of PHP invoking it to determine the phpize and php-config versions to utilize.
• The utility will use popular PHP libraries (e.g. symfony/console) to provide important CLI usability features.
• While the utility can manage extensions at a global system level, the goal will be to interact with a project's Composer configuration to identify what extensions are required and manage their installation. As such, extensions can now be located via common version control systems and expose themselves via a Composer definition, providing more and better options for discovery. While extensions can still be registered with pecl.php.net, it's no longer necessary to work with PIE.
• The utility will handle extension dependencies. Some extensions, such as the Relay extension, depend on others (e.g. Relay requires the igbinary, JSON, and msgpack extensions). PECL didn't handle these situations well, but PIE does.

Essentially, PIE takes PECL into modern PHP, providing a number of improvements and new capabilities.

PHP Installer for Extensions General Availability Release Date

As of the writing of this post, the general availability date for the PHP Installer for Extensions is unknown.

As with many open source projects, PIE will reach general availability when it's ready. Development of the utility has been active with regular commits and releases. At the time of writing, the most recent version is 0.12.0, and most indications are that it will likely reach a stable release by the time PHP 8.5 releases in November, 2025.

How to Get Started With PHP PIE

PIE itself is shipped as a PHAR file, which can then be executed from a PHP binary. However, PIE has a number of prerequisites in order to work.

First, it requires PHP 8.1 or newer.

Next, it requires one or more of the following in order to expand extension source packages:

• The unzip system utility
• The Zip PHP extension
• The git utility

Because you will be using PIE to compile extensions, you also will need:

• The development package for your PHP version (e.g. php-dev on DEB systems; php8.3-dev when using the Sury repo; php-devel on RPM systems; php83-devel when using the Remi repo; php8.3-dev on Alpine). This will install phpize and php-config.
• The make utility
• A C compiler (e.g. gcc)

Depending on the extension you compile, you may ALSO need more development libraries. As an example, if you are trying to compile the Relay extension (cachewerk/ext-relay), you will need the hiredis development libraries installed on your system to successfully compile.

How to Download the PHP Installer for Extensions

You can get PIE via its official source repository. Download the pie.phar for a given release, and then make it executable by running chmod +x pie.phar. You may want to alias it to pie via your shell.

By default, it will run using the system PHP; if you have multiple versions of PHP, and want to invoke it for a non-default version, invoke it using {PHP_BINARY} pie.phar.

There is a Docker image containing PIE as well, which you can import into your own Dockerfile; please see the documentation for how to use PIE in Dockerfiles. 

Now that you've installed the PHP Installer for Extensions, you can use it. Please note that all examples in this post use ZendPHP within a virtual machine.

Stay Secure and Compliant With Fully Supported PHP Runtimes

ZendPHP runtimes keep mission-critical applications protected against the latest threats and performing at a high level. Upgrade on your schedule, get new PHP versions faster, and maintain compliance standards.

Discover ZendPHP

How to Use the PHP Installer for Extensions

To get a list of subcommands, run pie.phar without arguments:

You can find a list of extensions that are compatible with PIE on Packagist. Let's try installing XDebug using PIE (package xdebug/xdebug):

./pie.phar install xdebug/xdebug

Assuming that you have installed all the necessary prerequisites, you should see something like the following:

Using PIE Within a PHP Application Managed With Composer

One of the huge benefits of PIE is that you can have it manage the extension dependencies of your application if you use Composer to manage dependencies.

You've been able to specify required PHP extensions for some time, using the ext- prefix for a package:

{
    "require": {
        "php": "8.3",
        "ext-inotify": "*"
    }
}

When you run composer install, if the PHP version does not match, or any extension listed in this way is not installed, it will raise an error and refuse to install (unless you also use one of the --ignore-platform-reqs or --ignore-platform-req flags).

PIE takes this a step further, and will try and install the extensions listed, so long as it can find a potential match via Packagist. For PIE to work in this scenario, you MUST have a composer.lock file, meaning you must run composer install or composer update before invoking PIE.

Run the following:

./pie.phar install

PIE will look for any extension requirements, and:

• Identify if the module is already installed and enabled
• If not, then it will:
  • Try and find a match via Packagist
  • Prompt you to ask which, if any, matching extensions to install
  • Retrieve the extension source, compile, and install the extension(s)

The great part about this is that provisioning your application is now largely a matter of:

• Having PHP installed on your system, with its development libraries
• Having PIE installed on the system, and running pie install in the application directory to install required extensions.
• Having Composer installed on the system, and running composer install to install application dependencies.

If you do this within a Dockerfile, you can remove PIE, Composer, and the PHP development libraries after usage to slim down the image for production, as well as remove potentially dangerous development requirements that could be used to install or compile other programs.

Final Thoughts

PIE is quickly shaping up to be not only a capable replacement for PHP PECL, but an improvement on it. The integration with Composer means you can have a single definition in your application for both extension and library dependencies, and even use familiar semantic versioning constraints with your extensions to be explicit about what you have tested your application against.

While system or distribution packages are likely a more expedient way to install extensions, having a first-class tool supported within the PHP ecosystem will be quite welcome, and we look forward to its stable release!

Try ZendPHP + ZendHQ Free for 21 Days

Try ZendPHP secure and supported runtimes alongside ZendHQ observability and orchestration free for 21 days, no commitment required. Learn more about how to secure, scale, and monitor with Zend via the buttons below.

Free Trial Details  Learn More About ZendHQ 

Additional Resources

• PHP Application Security and Compliance Trends
• Headless CMS vs. Traditional CMS
• HTTP Verbs: PHP 8.4 Changes and Updates
• Asymmetric Visibility in PHP 8.4
• A Developer's Guide to Building PHP APIs