🥧 PIE (PHP Installer for Extensions)

⚠️ Warning

PIE is still in early development. We welcome you to try this out, but please exercise caution when using PIE, as things may go wrong! If you do encounter issues, please do report an issue!

You will need PHP 8.1 or newer to run PIE, but PIE can install an extension to any installed PHP version.

If you are an extension maintainer wanting to add PIE support to your extension, please read extension-maintainers.

Installing PIE

Manual installation

• Download pie.phar either:
  • latest stable release
  • latest unstable nightly
• Verify the PHAR's source with gh attestation verify pie.phar --repo php/pie
• You may then invoke PIE with php pie.phar <command>

Further installation details can be found in the usage docs. This documentation assumes you have moved pie.phar into your $PATH, e.g. /usr/local/bin/pie on non-Windows systems.

Extensions that support PIE

A list of extensions that support PIE can be found on https://packagist.org/extensions.

Installing an extension using PIE

You can install an extension using the install command. For example, to install the example_pie_extension extension, you would run:

$ pie install example/example-pie-extension
This command may need elevated privileges, and may prompt you for your password.
You are running PHP 8.3.10
Target PHP installation: 8.3.10 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.3)
Found package: example/example-pie-extension:1.0.1 which provides ext-example_pie_extension
phpize complete.
Configure complete.
Build complete: /tmp/pie_downloader_66e0b1de73cdb6.04069773/example-example-pie-extension-769f906/modules/example_pie_extension.so
Install complete: /usr/lib/php/20230831/example_pie_extension.so
You must now add "extension=example_pie_extension" to your php.ini
$

More documentation...

The full documentation for PIE can be found in usage docs.

PIE Usage

Installing PIE

Manual installation

• Download pie.phar from the latest releases
• Verify the PHAR's source with gh attestation verify pie.phar --repo php/pie
• You may then invoke PIE with php pie.phar <command>
• Optionally, copy pie.phar into your $PATH, e.g. cp pie.phar /usr/local/bin/pie
  • If you copy PIE into your $PATH, you may then invoke PIE with pie <command>

This documentation assumes you have moved pie.phar into your $PATH, e.g. /usr/local/bin/pie on non-Windows systems.

One-liner

Note that this does not verify any signatures, and you assume the risks in running this, but this will put PIE into /usr/local/bin/pie on a non-Windows system:

sudo curl -L --output /usr/local/bin/pie https://github.com/php/pie/releases/latest/download/pie.phar && sudo chmod +x /usr/local/bin/pie

Docker installation

PIE is published as binary-only Docker image, so you can install it easily during your Docker build:

COPY --from=ghcr.io/php/pie:bin /pie /usr/bin/pie

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 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.

Example of PIE working in a Dockerfile

This is an example of how PIE could be used to install an extension inside a Docker image. Note that, like Composer, you need something like unzip, the Zip extension, or git to be installed.

FROM php:8.4-cli

# Add the `unzip` package which PIE uses to extract .zip files
RUN export DEBIAN_FRONTEND="noninteractive"; \
    set -eux; \
    apt-get update; apt-get install -y --no-install-recommends unzip; \
    rm -rf /var/lib/apt/lists/*

# Copy the pie.phar from the latest `:bin` release
COPY --from=ghcr.io/php/pie:bin /pie /usr/bin/pie

# Use PIE to install an extension...
RUN pie install asgrim/example-pie-extension

If the extension you would like to install needs additional libraries or other dependencies, then these must be installed beforehand too.

Prerequisites for PIE

Running PIE requires PHP 8.1 or newer. However, you may still use PIE to install an extension for an older version of PHP.

Additionally to PHP, PIE requires the following tools to be available on your system in order to download, build and install extensions:

• The zip extension enabled for the PHP version running PIE, or git to download the extension source code
• autoconf, automake, libtool, m4, make, and gcc to build the extension
• PHP development tools (such as php-config and phpize) to prepare the extension for building.

Also, each extension may have its own requirements, such as additional libraries.

Using Linux

On a Debian-based system, you may install the required tools with:

sudo apt-get install git autoconf automake libtool m4 make gcc

On a Red Hat-based system, you may install the required tools with:

sudo yum install git autoconf automake libtool m4 make gcc

Using macOS

On macOS, you may install the required tools with Homebrew:

brew install git autoconf automake libtool m4 make gcc

Using Windows

On Windows, extensions are typically distributed as precompiled binaries. Instead of building the extension yourself, it will be downloaded as DLL files and placed in the PHP extensions directory.

Downloading, Building, or Installing an extension

PIE has the ability to:

• only download an extension, with pie download ...,
• download and build an extension, with pie build ...,
• or, most commonly, download, build, and install an extension, with pie install ...

When installing an extension with PIE, you must use its Composer package name. You can find a list of PIE-compatible packages on https://packagist.org/extensions.

Once you know the extension name, you can install it with:

pie install <vendor>/<package>

# for example:
pie install xdebug/xdebug

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.

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 may specify this on non-Windows systems with the --with-php-config option:

pie install --with-php-config=/usr/bin/php-config7.2 my/extension

On Windows, you may provide a path to the php executable itself using the --with-php-path option. This is an example on Windows where PHP 8.1 is used to run PIE, but we want to download the extension for PHP 8.3:

> C:\php-8.1.7\php.exe C:\pie.phar install --with-php-path=C:\php-8.3.6\php.exe example/example-pie-extension

You may also need to use the corresponding phpize command for the target PHP version, which can be specified with the --with-phpize-path option:

pie install --with-phpize-path=/usr/bin/phpize7.2 my/extension

Version constraints and stability

You may optionally specify a version constraint when using PIE to install an extension:

pie install <vendor>/<package>:<version-constraint>

If version-constraint is given, try to install that version if it matches the allowed versions. Version constraints are resolved using the same format as Composer, along with the minimum stability.

• ^1.0 will install the latest stable and backwards-compatible version with 1.0.0 and above, according to semantic versioning. See Composer docs for details.
• ^2.3@beta will install the latest beta and backwards-compatible version with 2.3.0 and above (for example, 2.3.0-beta.3).
• dev-main will install the latest commit on the main branch at the time of command execution. This would not work with Windows, as there is no release with Windows binaries.
• dev-main#07f454ad797c30651be8356466685b15331f72ff will install the specific commit denoted by the commit sha after #, in this case the commit 07f454ad797c30651be8356466685b15331f72ff would be installed. This would not work with Windows, as there is no release with Windows binaries.

If no version-constraint is given, try to install any compatible latest and stable version. PIE will always prefer stable versions.

Specifying configure options

When compiling extensions, some will need additional parameters passed to the ./configure command. These would typically be to enable or disable certain functionality, or to provide paths to libraries not automatically detected.

In order to determine what configure options are available for an extension, you may use pie info <vendor>/<package> which will return a list, such as:

Configure options:
    --enable-some-functionality  (whether to enable some additional functionality provided)
    --with-some-library-name=?  (Path for some-library)

The above example extension could then be installed with none, some, or all of the specified configure options, some examples:

pie install example/some-extension
pie install example/some-extension --enable-some-functionality
pie install example/some-extension --with-some-library-name=/path/to/the/lib
pie install example/some-extension --with-some-library-name=/path/to/the/lib --enable-some-functionality

Configuring the INI file

PIE will automatically try to enable the extension by adding extension=... or zend_extension=... in the appropriate INI file. If you want to disable this behaviour, pass the --skip-enable-extension flag to your pie install command. The following techniques are used to attempt to enable the extension:

• phpenmod, if using the deb.sury.org distribution
• docker-php-ext-enable if using Docker's PHP image
• Add a new file to the "additional .ini file" path, if configured
• Append to the standard php.ini, if configured

If none of these techniques work, or you used the --skip-enable-extension flag, PIE will warn you that the extension was not enabled, and will note that you must enable the extension yourself.

Adding non-Packagist.org repositories

Sometimes you may want to install an extension from a package repository other than Packagist.org (such as Private Packagist), or from a local directory. Since PIE is based heavily on Composer, it is possible to use some other repository types:

• pie repository:add [--with-php-config=...] path /path/to/your/local/extension
• pie repository:add [--with-php-config=...] vcs https://github.com/youruser/yourextension
• pie repository:add [--with-php-config=...] composer https://repo.packagist.com/your-private-packagist/
• pie repository:add [--with-php-config=...] composer packagist.org

The repository:* commands all support the optional --with-php-config flag to allow you to specify which PHP installation to use (for example, if you have multiple PHP installations on one machine). The above added repositories can be removed too, using the inverse repository:remove commands:

• pie repository:remove [--with-php-config=...] /path/to/your/local/extension
• pie repository:remove [--with-php-config=...] https://github.com/youruser/yourextension
• pie repository:remove [--with-php-config=...] https://repo.packagist.com/your-private-packagist/
• pie repository:remove [--with-php-config=...] packagist.org

Note you do not need to specify the repository type in repository:remove, just the URL.

You can list the repositories for the target PHP installation with:

• pie repository:list [--with-php-config=...]

Comparison with PECL

Since PIE is a replacement for PECL, here is a comparison of the commands that you may be familiar with in PECL, with an approximate equivalent in PIE. Note that some concepts are different or omitted from PIE as they may simply be not applicable to the new tooling.

PIE for Extension Maintainers

Adding PIE support for your extension is relatively straightforward, and the flow is quite similar to adding a regular PHP package into Packagist.

Add a composer.json to your extension

The first step to adding PIE support is adding a composer.json to your extension repository. Most of the typical fields are the same, with a few notable exceptions:

• The type MUST be either php-ext for a PHP Module (this will be most extensions), or php-ext-zend for a Zend Extension.
• An additional php-ext section MAY exist.
• The Composer package name (i.e. the top level name field) should follow the usual Composer package name format, i.e. <vendor>/<package>.
• However, please note that the Composer package name for a PIE extension cannot share the same Composer package name as a regular PHP package, even if they have different type fields.

The php-ext definition

extension-name

The extension-name SHOULD be specified, and must conform to the usual extension name regular expression, which is defined in \Php\Pie\ExtensionName::VALID_PACKAGE_NAME_REGEX. If the extension-name is not specified, the extension-name will be derived from the Composer package name, with the vendor prefix removed. For example, given a composer.json with:

{
    "name": "myvendor/myextension"
}

The extension name would be derived as myextension. The myvendor/ vendor prefix is removed.

The extension-name SHOULD NOT be prefixed with ext- as is a convention in Composer when using require.

An example of extension-name being used:

{
    "name": "xdebug/xdebug",
    "php-ext": {
        "extension-name": "xdebug"
    }
}

priority

priority is currently not used, but will form part of the ini filename to control ordering of extensions, if the target platform uses it.

support-zts and support-nts

Indicates whether the extension supports Zend Thread-Safe (ZTS) and non-Thread- Safe (NTS) modes. Both these flags default to true if not specified, but if your extension does not support either mode, it should be specified, and will mean the extension will not be installable on the target platform.

Theoretically, it is possible to specify false for both support-zts and support-nts, but this will mean your package cannot be installed anywhere, so is not advisable.

configure-options

This is a list of parameters that may be passed to the ./configure command. Each item of the list is a JSON object with:

• name, the parameter name itself
• description, a helpful description of what the parameter does
• optionally, needs-value, a boolean to tell PIE whether the parameter is a simple flag (typically used for --enable-this-flag type parameters), or if the parameter should have a value specified (typically used for --with-library-path=... type parameters, where a value must be given by the end user)

When an end user is installing an extension with PIE, they may specify any defined configure-options that are passed to ./configure. For example, if an extension defines the following composer.json:

{
    "name": "myvendor/myext",
    "php-ext": {
        "extension-name": "myext",
        "configure-options": [
            {
                "name": "enable-my-flag",
                "description": "Should my flag be enabled",
                "needs-value": false
            },
            {
                "name": "with-some-lib",
                "description": "Specify the path to some-lib",
                "needs-value": true
            }
        ]
    }
}

Then the pie build or pie install commands may be invoked in the following ways to achieve the desired configuration:

• pie install myvendor/myext
  • This will simply invoke ./configure without any parameters
• pie install myvendor/myext --enable-my-flag
  • This will invoke ./configure --enable-my-flag
• pie install myvendor/myext --with-some-lib=/path/to/somelib
  • This will invoke ./configure --with-some-lib=/path/to/somelib
• pie install myvendor/myext --enable-my-flag --with-some-lib=/path/to/somelib
  • This will invoke ./configure --enable-my-flag --with-some-lib=/path/to/somelib

Note that it is not possible for end users of PIE to specify configuration options that have not been defined in your extension's configure-options definition. Using the same example above composer.json, invoking PIE with an invalid option, such as pie install myvendor/myext --something-else will result in an error The "--something-else" option does not exist..

If an end user does not specify a flag defined in the configure-options definition, it will simply not be passed to ./configure. There is no way to specify a default value in the configure-options definition.

build-path

The build-path setting may be used if your source code is not in the root of your repository. For example, if your repository structure is like:

/
  docs/
  src/
    config.m4
    config.w32
    myext.c
    ...etc

In this case, the actual extension source code would be built in src/, so you should specify this path in build-path, for example:

{
    "name": "myvendor/myext",
    "php-ext": {
        "extension-name": "myext",
        "build-path": "src"
    }
}

Extension dependencies

Extension authors may define some dependencies in require, but practically, most extensions would not need to define dependencies. Dependencies on other extensions may be defined, for example ext-json. However, dependencies on a regular PHP package (such as monolog/monolog) are ignored when requesting an installation of an extension with PIE.

It is worth noting that if your extension does define a dependency on another dependency, this would prevent installation of the extension, and at the moment the messaging around this is not particularly clear.

Submit the extension to Packagist

Once you have committed your composer.json to your repository, you may then submit it to Packagist in the same way as any other package.

• Head to https://packagist.org/packages/submit
• Enter the URL of your repository, and follow the instructions.

Windows Support

In order to support Windows users, you must publish pre-built DLLs, as PIE does not currently support building DLLs on the fly. The expected workflow for Windows-compatible releases is:

• The release is made on GitHub (only GitHub is supported at the moment)
• A CI pipeline runs to build the release assets, e.g. in a GitHub Action
• The resulting build assets are published to the GitHub release in a ZIP file

The name of the ZIP file, and the DLL contained within must be:

• php_{extension-name}-{tag}-{php-maj/min}-{ts|nts}-{compiler}-{arch}.zip
• Example: php_xdebug-3.3.2-8.3-ts-vs16-x86_64.zip

The descriptions of these items:

• extension-name the name of the extension, e.g. xdebug
• tag for example 3.3.0alpha3 - defined by the tag/release you have made
• php-maj/min - for example 8.3 for PHP 8.3.*
• compiler - usually something like vc6, vs16 - fetch from 'PHP Extension Build' flags in php -i
• ts|nts - Thread-safe or non-thread safe.
• arch - for example x86_64.
  • Windows: Architecture from php -i
  • non-Windows: check PHP_INT_SIZE - 4 for 32-bit, 8 for 64-bit.

Contents of the Windows ZIP

The pre-built ZIP should contain at minimum a DLL named in the same way as the ZIP itself, for example php_{extension-name}-{tag}-{php-maj/min}-{ts|nts}-{compiler}-{arch}.dll. The .dll will be moved into the PHP extensions path, and renamed, e.g. to C:\path\to\php\ext\php_{extension-name}.dll. The ZIP file may include additional resources, such as:

• php_{extension-name}-{tag}-{php-maj/min}-{ts|nts}-{compiler}-{arch}.pdb - this will be moved alongside the C:\path\to\php\ext\php_{extension-name}.dll
• *.dll - any other .dll would be moved alongside C:\path\to\php\php.exe
• Any other file, which would be moved into C:\path\to\php\extras\{extension-name}\.

Automation of the Windows publishing

PHP provides a set of GitHub Actions that enable extension maintainers to build and release the Windows compatible assets. An example workflow that uses these actions:

name: Publish Windows Releases
on:
   release:
      types: [published]

permissions:
   contents: write

jobs:
   get-extension-matrix:
      runs-on: ubuntu-latest
      outputs:
         matrix: ${{ steps.extension-matrix.outputs.matrix }}
      steps:
         - name: Checkout
           uses: actions/checkout@v4
         - name: Get the extension matrix
           id: extension-matrix
           uses: php/php-windows-builder/extension-matrix@v1
   build:
      needs: get-extension-matrix
      runs-on: ${{ matrix.os }}
      strategy:
         matrix: ${{fromJson(needs.get-extension-matrix.outputs.matrix)}}
      steps:
         - name: Checkout
           uses: actions/checkout@v4
         - name: Build the extension
           uses: php/php-windows-builder/extension@v1
           with:
              php-version: ${{ matrix.php-version }}
              arch: ${{ matrix.arch }}
              ts: ${{ matrix.ts }}
   release:
      runs-on: ubuntu-latest
      needs: build
      if: ${{ github.event_name == 'release' }}
      steps:
         - name: Upload artifact to the release
           uses: php/php-windows-builder/release@v1
           with:
              release: ${{ github.event.release.tag_name }}
              token: ${{ secrets.GITHUB_TOKEN }}

Source: https://github.com/php/php-windows-builder?tab=readme-ov-file#example-workflow-to-build-and-release-an-extension

Supported Extensions

Since Packagist is the new home for PIE packages, the full list of supported, PIE-compatible extensions can be found on:

• https://packagist.org/extensions

The process for adding support for PIE is documented in the Extension Maintainers documentation.

PECL Extension Migration

The PECL repository still has a whole host of extensions that have not yet added support for PIE. This is a list of extensions hosted on PECL, and their status for adding PIE support. If you spot some out of date information here, please do submit a Pull Request.