🥧 PIE (PHP Installer for Extensions)

What is PIE?

PIE is the official installer for PHP extensions, which replaces PECL (which is now deprecated). PIE is distributed as a PHAR, just like Composer, and works in a similar way to Composer, but it installs PHP extensions (PHP Modules or Zend Extensions) to your PHP installation, rather than pulling PHP packages into your project or library.

Using PIE - what do I need to get started?

Prerequisites

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

On Linux/OSX, if any build tools needed are missing, PIE will ask if you would like to automatically install them first (as of PIE 1.4.0).

On Windows, you do not need any build toolchain installed, since PHP extensions for Windows are distributed as pre-compiled packages containing the extension DLL.

Installing PIE

• Download pie.phar either:
  • latest stable release
  • latest unstable nightly
• Verify the PHAR's source with gh attestation verify --owner php pie.phar
• 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 or created an alias in your shell RC file.

One-liner

This will install PIE into /usr/local/bin/pie on a non-Windows system:

curl -fL --output /tmp/pie.phar https://github.com/php/pie/releases/latest/download/pie.phar \
  && gh attestation verify --owner php /tmp/pie.phar \
  && sudo mv /tmp/pie.phar /usr/local/bin/pie \
  && sudo chmod +x /usr/local/bin/pie

Using PIE

Installing a single 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 asgrim/example-pie-extension
🥧 PHP Installer for Extensions (PIE) 1.4.0, from The PHP Foundation
This command may need elevated privileges, and may prompt you for your password.
You are running PHP 8.5.3
Target PHP installation: 8.5.3 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.5)
Found package: asgrim/example-pie-extension:2.0.9 which provides ext-example_pie_extension
Extracted asgrim/example-pie-extension:2.0.9 source to: /path/to/example-pie-extension
phpize complete.
Configure complete with options: --with-php-config=/usr/bin/php-config8.5
Build complete: /path/to/example-pie-extension/modules/example_pie_extension.so
Install complete: /usr/lib/php/20250925/example_pie_extension.so
✅ Extension is enabled and loaded in /usr/bin/php8.5
$

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.

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:

$ pie install
🥧 PHP Installer for Extensions (PIE) 1.4.0, from The PHP Foundation
You are running PHP 8.5.0
Target PHP installation: 8.5.0 nts, on Linux/OSX/etc x86_64 (from /usr/local/bin/php)
Checking extensions for your project asgrim/demo-php-project (path: /demos/demo-php-project)
requires: ext-curl:* ✅ Already installed
requires: ext-example_pie_extension:^2.0 🚫 Missing

The following packages may be suitable, which would you like to install: 
  [0] None
  [1] asgrim/example-pie-extension: Example PIE extension
 > 1
  example_pie_extension> You are running PHP 8.5.0
  example_pie_extension> Target PHP installation: 8.5.0 nts, on Linux/OSX/etc x86_64 (from /usr/local/bin/php)
  example_pie_extension> Found package: asgrim/example-pie-extension:2.0.9 which provides ext-example_pie_extension
  example_pie_extension> Extracted asgrim/example-pie-extension:2.0.9 source to: /path/to/example-pie-extension
  example_pie_extension> phpize complete.
  example_pie_extension> Configure complete with options: --with-php-config=/usr/local/bin/php-config
  example_pie_extension> Build complete: /path/to/example-pie-extension/modules/example_pie_extension.so
  example_pie_extension> Install complete: /usr/local/lib/php/extensions/no-debug-non-zts-20250925/example_pie_extension.so
  example_pie_extension> ✅ Extension is enabled and loaded in /usr/local/bin/php

Finished checking extensions.

⁉️ Important

If you are running PIE in a non-interactive shell (for example, CI, a container), the --allow-non-interactive-project-install is no longer functional. You must specify --select flags for each missing package, e.g.:

pie install \
  --select example_pie_extension=asgrim/example-pie-extension \
  --select redis=phpredis/phpredis

Extensions that support PIE

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

I have a bug, feature idea, question, need help, etc.

• If you have an idea, question, or need help, please use the Discussions.
  • Please check with us first before contributing new features - it may be something we're already working on, as the PHP Foundation is actively developing this too, and there are new features already in the pipeline...
• If you have a bug to report, please use the Issues.

I'm an extension maintainer - how do I add PIE support?

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

More documentation...

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

⚠️ Warning

This translation may not be based on the latest version, please ensure you check the original English version for discrepancies.

PIE 使用ガイド

PIE のインストール

手動インストール

• 最新リリースから pie.phar をダウンロード
• gh attestation verify --owner php pie.phar で PHAR のソースを検証
  • このステップには gh CLI コマンドが必要です。
• php pie.phar <command> で PIE を呼び出すことができます
• オプション：pie.phar を $PATH にコピー、例：cp pie.phar /usr/local/bin/pie
  • PIE を $PATH にコピーした場合、pie <command> で PIE を呼び出すことができます

このドキュメントでは、pie.phar を $PATH に移動したと仮定しています。例えば、非 Windows システムでは /usr/local/bin/pie です。

ワンライナー

これは署名を検証しないため、実行するリスクはご自身で負担することになりますが、非 Windows システムで PIE を /usr/local/bin/pie に配置します：

curl -fL --output /tmp/pie.phar https://github.com/php/pie/releases/latest/download/pie.phar \
  && gh attestation verify --owner php /tmp/pie.phar \
  && sudo mv /tmp/pie.phar /usr/local/bin/pie \
  && sudo chmod +x /usr/local/bin/pie

Docker インストール

PIE はバイナリのみの Docker イメージとして公開されているため、Docker ビルド中に簡単にインストールできます：

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

bin タグ（最新のバイナリのみのイメージを表す）の代わりに、明示的なバージョン（x.y.z-bin 形式）を使用することもできます。利用可能なタグを見つけるには GitHub registry を使用してください。

⁉️ Important

バイナリのみのイメージには PHP ランタイムが含まれていないため、PIE を実行することはできません。これは PHAR ファイルを配布する別の方法に過ぎず、PIE のランタイム要件は自分で満たす必要があります。

Dockerfile での PIE の動作例

これは Docker イメージ内で PIE を使用して拡張機能をインストールする方法の例です。Composer と同様に、unzip、Zip 拡張機能、または git のようなものが必要です。

FROM php:8.4-cli

# PIE が .zip ファイルを展開するために使用する `unzip` パッケージを追加
RUN export DEBIAN_FRONTEND="noninteractive"; \
    set -eux; \
    apt-get update; apt-get install -y --no-install-recommends unzip; \
    rm -rf /var/lib/apt/lists/*

# 最新の `:bin` リリースから pie.phar をコピー
COPY --from=ghcr.io/php/pie:bin /pie /usr/bin/pie

# PIE を使用して拡張機能をインストール...
RUN pie install asgrim/example-pie-extension

インストールしたい拡張機能に追加のライブラリや他の依存関係が必要な場合は、それらを事前にインストールする必要があります。

PIE の前提条件

PIE の実行には PHP 8.1 以降が必要です。ただし、古いバージョンの PHP 用の拡張機能をインストールするために PIE を使用することはできます。

PHP に加えて、PIE は拡張機能をダウンロード、ビルド、インストールするために、システムに以下のツールが必要です：

• PIE を実行する PHP バージョンで有効化された zip 拡張機能、または拡張機能のソースコードをダウンロードするための git
• 拡張機能をビルドするための autoconf、automake、libtool、m4、make、gcc
• 拡張機能のビルドを準備するための PHP 開発ツール（php-config や phpize など）

また、各拡張機能には独自の要件（追加のライブラリなど）がある場合があります。

💡 Tip

正しい前提条件がインストールされていない状態で PIE を実行すると、Box Requirements Checker からエラーが表示される場合があります。とにかく実行を試みたい場合は、環境変数 BOX_REQUIREMENT_CHECKER=0 を指定してください。

Linux での例：

$ BOX_REQUIREMENT_CHECKER=0 pie install foo/bar

Linux の使用

Debian ベースのシステムでは、以下のコマンドで必要なツールをインストールできます：

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

Red Hat ベースのシステムでは、以下のコマンドで必要なツールをインストールできます：

sudo yum install git autoconf automake libtool m4 make gcc

macOS の使用

macOS では、Homebrew を使用して必要なツールをインストールできます：

brew install git autoconf automake libtool m4 make gcc

Windows の使用

Windows では、拡張機能は通常、プリコンパイル済みのバイナリとして配布されます。拡張機能を自分でビルドする代わりに、DLL ファイルとしてダウンロードされ、PHP 拡張機能ディレクトリに配置されます。

拡張機能のダウンロード、ビルド、またはインストール

PIE には以下の機能があります：

• pie download ... で拡張機能のみをダウンロード
• pie build ... で拡張機能をダウンロードしてビルド
• または、最も一般的な、pie install ... で拡張機能をダウンロード、ビルド、インストール

PIE で拡張機能をインストールする場合、その Composer パッケージ名を使用する必要があります。PIE 互換パッケージのリストは https://packagist.org/extensions で確認できます。

拡張機能名がわかったら、以下のようにインストールできます：

pie install <vendor>/<package>

# 例：
pie install xdebug/xdebug

これにより、PIE を呼び出すために使用された PHP バージョンに Xdebug 拡張機能がインストールされ、その PHP バージョンと互換性のある Xdebug の最新安定版が使用されます。

異なる PHP バージョン用の拡張機能を PIE でインストール

異なるバージョンの PHP 用の拡張機能をインストールしようとしている場合、非 Windows システムでは --with-php-config オプションで指定できます：

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

Windows では、--with-php-path オプションを使用して php 実行可能ファイル自体のパスを指定できます。これは Windows での例で、PHP 8.1 を使用して PIE を実行していますが、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

ターゲット PHP バージョンに対応する phpize コマンドを使用する必要がある場合もあります。これは --with-phpize-path オプションで指定できます：

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

バージョン制約と安定性

PIE で拡張機能をインストールする際に、オプションでバージョン制約を指定できます：

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

version-constraint が指定された場合、許可されたバージョンと一致する場合、そのバージョンをインストールしようとします。バージョン制約は Composer と同じ形式で解決され、最小安定性も考慮されます。

• ^1.0 は、セマンティックバージョニングに従って、1.0.0 以上で後方互換性のある最新の安定版をインストールします。 詳細は Composer ドキュメントを参照。
• ^2.3@beta は、2.3.0 以上で後方互換性のある最新のベータ版をインストールします（例：2.3.0-beta.3）。
• dev-main は、コマンド実行時の main ブランチの最新コミットをインストールします。これは Windows バイナリを含むリリースがないため、Windows では機能しません。
• dev-main#07f454ad797c30651be8356466685b15331f72ff は、# の後のコミット sha で示される特定のコミットをインストールします。この場合、コミット 07f454ad797c30651be8356466685b15331f72ff がインストールされます。これは Windows バイナリを含むリリースがないため、Windows では機能しません。

version-constraint が指定されると、チェックされ、ターゲット PHP バージョンの pie.json に直接追加されます。例：

$ pie install "xdebug/xdebug:^3.4.3 || 3.4.1"

これにより、pie.json に以下が設定されます：

{
    "require": {
        "xdebug/xdebug": "^3.4.3 || 3.4.1"
    }
}

version-constraint が指定されていない場合、互換性のある最新の安定版をインストールしようとします。PIE は常に安定版を優先します。

設定オプションの指定

拡張機能をコンパイルする際、一部の拡張機能では ./configure コマンドに追加のパラメータを渡す必要があります。これらは通常、特定の機能を有効化または無効化するため、または自動検出されないライブラリのパスを提供するために使用されます。

拡張機能で利用可能な設定オプションを確認するには、pie info <vendor>/<package> を使用します。これにより、次のようなリストが返されます：

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

上記の例の拡張機能は、指定された設定オプションなし、一部、またはすべてを使用してインストールできます。いくつかの例：

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

INI ファイルの設定

PIE は、適切な INI ファイルに extension=... または zend_extension=... を追加することで、拡張機能を自動的に有効化しようとします。この動作を無効にしたい場合は、pie install コマンドに --skip-enable-extension フラグを渡してください。拡張機能を有効化しようとする際には、以下の技術が使用されます：

• deb.sury.org ディストリビューションを使用している場合は phpenmod
• Docker の PHP イメージを使用している場合は docker-php-ext-enable
• 「追加の .ini ファイル」パスが設定されている場合は、そのパスに新しいファイルを追加
• 標準の php.ini が設定されている場合は、php.ini に追記

これらの技術がいずれも機能しない場合、または --skip-enable-extension フラグを使用した場合、PIE は拡張機能が有効化されなかったことを警告し、拡張機能を自分で有効化する必要があることを通知します。

Packagist.org 以外のリポジトリの追加

Packagist.org 以外のパッケージリポジトリ（Private Packagist など）から拡張機能をインストールしたい場合や、ローカルディレクトリからインストールしたい場合があります。PIE は Composer をベースにしているため、他のリポジトリタイプを使用できます：

• 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

repository:* コマンドはすべて、オプションの --with-php-config フラグをサポートしており、使用する PHP インストールを指定できます（例えば、1 台のマシンに複数の PHP インストールがある場合）。追加されたリポジトリは、逆の repository:remove コマンドを使用して削除することもできます：

• 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

repository:remove ではリポジトリタイプを指定する必要はなく、URL だけを指定します。

ターゲット PHP インストールのリポジトリをリストするには：

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

プロジェクトに不足している拡張機能の確認とインストール

PHP プロジェクトの作業ディレクトリにいる場合、pie install を使用してプロジェクトが必要とする拡張機能が存在するかどうかを確認できます。拡張機能が不足している場合、PIE はインストール候補を見つけて、インストールするかどうかをインタラクティブに尋ねます。例：

$ pie install
🥧 PHP Installer for Extensions (PIE), 0.9.0, from The PHP Foundation
You are running PHP 8.3.19
Target PHP installation: 8.3.19 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.3)
Checking extensions for your project your-vendor/your-project
requires: curl ✅ Already installed
requires: intl ✅ Already installed
requires: json ✅ Already installed
requires: example_pie_extension ⚠️  Missing

The following packages may be suitable, which would you like to install:
  [0] None
  [1] asgrim/example-pie-extension: Example PIE extension
 > 1
   > 🥧 PHP Installer for Extensions (PIE), 0.9.0, from The PHP Foundation
   > This command may need elevated privileges, and may prompt you for your password.
   > You are running PHP 8.3.19
   > Target PHP installation: 8.3.19 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.3)
   > Found package: asgrim/example-pie-extension:2.0.2 which provides ext-example_pie_extension
   ... (snip) ...
   > ✅ Extension is enabled and loaded in /usr/bin/php8.3

Finished checking extensions.

PECL との比較

PIE は PECL の代替品であるため、PECL でよく知られているコマンドと PIE での同等のコマンドの比較を以下に示します。一部の概念は PIE では異なるか省略されている場合があります。これは新しいツールには適用されない可能性があるためです。

PIE Usage

Installing PIE

Manual installation

• Download pie.phar from the latest releases
• Verify the PHAR's source with gh attestation verify --owner php pie.phar
  • Note that this step requires the gh CLI command.
• 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.

Distribution packages

⚠️ Warning

Distribution packages are not maintained by PIE, so may not have the latest version, may have patches applied, or the instructions here may be out of date. You should verify the distribution packages before using them.

Fedora and Enterprise Linux 10

On Enterprise Linux (CentOS, RHEL, AlmaLinux, RockyLinux, and other clones) you need to enable the EPEL repository.

sudo dnf install pie

Package information: pie

Homebrew

PIE can be installed with Homebrew with:

brew install pie

# If you have `gh`, you can verify PIE is authentic:
gh attestation verify --owner=php $(which pie)

Docker installation

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

RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin/pie \
    pie -V

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

RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin/pie \
    export DEBIAN_FRONTEND="noninteractive"; \
    set -eux; \
    # Add the `unzip` package which PIE uses to extract .zip files.
    apt-get update; \
    apt-get install -y --no-install-recommends unzip; \
    # Use PIE to install an extension...
    pie install --no-cache \
        asgrim/example-pie-extension; \
    # Clean up `unzip`.
    apt-get purge -y --auto-remove -o APT::AutoRemove::RecommendsImportant=false unzip; \
    rm -rf /var/lib/apt/lists/*;

CMD ["php", "-r", "example_pie_extension_test();"]

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

Executable PIE (Experimental)

As of 1.4.0 an experimental executable (binary) version of PIE is included. The PIE is built using Static PHP, which builds a self-contained PHP executable with the extensions that PIE needs to run, and bundles the PHAR as a single distributable executable. Please keep in mind that this is experimental, and we do not recommend this for production use for the time being. Please also note there are some limitations:

• php/pie#460 - all the binary versions have the pie self-update feature disabled for now.

If you find the binary releases useful, please leave feedback or upvote on the relevant discussions, so we can gauge interest in improving this functionality.

The stable versions of the executables can be found by navigating to the relevant release, and finding the appropriate executable for your platform. For your convenience, the "latest" stable releases can be downloaded from these links:

The "nightly" versions of these can be found here:

We highly recommend you verify the file came from the PHP GitHub repository before running it, for example:

$ gh attestation verify --owner php pie-Linux-X64
$ chmod +x pie-Linux-X64
$ ./pie-Linux-X64 --version

Prerequisites for PIE (PHAR distribution)

Running PIE requires PHP 8.1 or newer. However, you may still use PIE to install an extension for an older version of PHP. You also need the zip extension enabled for the PHP version running PIE, or git to download the extension source code.

Additionally to PHP, PIE requires the following build tools to be available on your system in order to download, build and install extensions. Note that as of PIE 1.4.0, PIE will attempt to detect and install the missing build tools:

• 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. As of PIE 1.4.0, for some extensions, PIE will attempt to detect and install the missing system libraries.

💡 Tip

If you run PIE without the correct prerequisites installed, you may receive an error from the Box Requirements Checker. If you want to try running anyway, specify the environment variable BOX_REQUIREMENT_CHECKER=0.

Example on Linux:

$ BOX_REQUIREMENT_CHECKER=0 pie install foo/bar

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.

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

When a version-constraint is given, it is checked, and added directly to the pie.json for the target PHP version, e.g.:

$ pie install "xdebug/xdebug:^3.4.3 || 3.4.1"

will set the following in pie.json:

{
    "require": {
        "xdebug/xdebug": "^3.4.3 || 3.4.1"
    }
}

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

💡 Tip

If you specify configure options for a package that uses the pre-packaged-binary download method, PIE will fall back to compiling the extension using the configure options you have specified.

Build tools check

PIE will attempt to check the presence of build tools (such as gcc, make, etc.) before running. If any are missing, an interactive prompt will ask if you would like to install the missing tools. If you are running in non-interactive mode (for example, in a CI pipeline, container build, etc), PIE will not install these tools automatically. If you would like to install the build tools in a non-interactive terminal, pass the --auto-install-build-tools and the prompt will be skipped.

To skip the build tools check entirely, pass the --no-build-tools-check flag.

System library dependencies check

PIE will attempt to check the presence of system library dependencies before installing an extension. If any are missing, an interactive prompt will ask if you would like to install the missing tools. If you are running in non-interactive mode (for example, in a CI pipeline, container build, etc), PIE will not install these dependencies automatically. If you would like to install the system dependencies in a non-interactive terminal, pass the --auto-install-system-dependencies and the prompt will be skipped.

To skip the dependencies check entirely, pass the --no-system-dependencies-check flag.

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

Check and install missing extensions for your project

You can use pie install when in a PHP project working directory to check the extensions the project requires are present. If an extension is missing, PIE will try to find an installation candidate and interactively ask if you would like to install one. For example:

$ pie install
🥧 PHP Installer for Extensions (PIE) 1.4.0, from The PHP Foundation
You are running PHP 8.5.0
Target PHP installation: 8.5.0 nts, on Linux/OSX/etc x86_64 (from /usr/local/bin/php)
Checking extensions for your project asgrim/demo-php-project (path: /demos/demo-php-project)
requires: ext-curl:* ✅ Already installed
requires: ext-example_pie_extension:^2.0 🚫 Missing

The following packages may be suitable, which would you like to install: 
  [0] None
  [1] asgrim/example-pie-extension: Example PIE extension
 > 1
  example_pie_extension> You are running PHP 8.5.0
  example_pie_extension> Target PHP installation: 8.5.0 nts, on Linux/OSX/etc x86_64 (from /usr/local/bin/php)
  example_pie_extension> Found package: asgrim/example-pie-extension:2.0.9 which provides ext-example_pie_extension
  example_pie_extension> Extracted asgrim/example-pie-extension:2.0.9 source to: /path/to/example-pie-extension
  example_pie_extension> phpize complete.
  example_pie_extension> Configure complete with options: --with-php-config=/usr/local/bin/php-config
  example_pie_extension> Build complete: /path/to/example-pie-extension/modules/example_pie_extension.so
  example_pie_extension> Install complete: /usr/local/lib/php/extensions/no-debug-non-zts-20250925/example_pie_extension.so
  example_pie_extension> ✅ Extension is enabled and loaded in /usr/local/bin/php

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:

{
    "require": {
        "ext-curl": "*",
        "ext-example_pie_extension": "^2.0",
        "ext-redis": "^6.3"
    }
}

You can specify the missing extensions with:

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.

Install extensions from pie.lock

If you have an existing pie.json and pie.lock for a given PHP install, place these files in the directory indicated by the pie show -v path for Using pie.json, e.g.:

$ php8.2 /usr/local/bin/pie show -v
🥧 PHP Installer for Extensions (PIE) 1.5.0, from The PHP Foundation
You are running PHP 8.2.31
Target PHP installation: 8.2.31 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.2)
Using pie.json: /home/blah/.config/pie/php8.2_7cfa96d5dfc1df10afeb65851159197b/pie.json
...

Move your pie.json and pie.lock into this path, then you can run pie install --from-lock which will install the locked extension dependencies specified in that pie.lock.

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.

⚠️ Warning

This translation may not be based on the latest version, please ensure you check the original English version for discrepancies.

PIE 使用指南

安装 PIE

手动安装

• 从最新发布版本下载 pie.phar
• 使用 gh attestation verify --owner php pie.phar 验证 PHAR 的来源
  • 注意此步骤需要安装 gh CLI 命令。
• 然后可以使用 php pie.phar <command> 调用 PIE
• 可选：将 pie.phar 复制到您的 $PATH，例如 cp pie.phar /usr/local/bin/pie
  • 如果将 PIE 复制到 $PATH，则可以使用 pie <command> 调用 PIE

本文档假设您已将 pie.phar 移动到 $PATH，例如非 Windows 系统上的 /usr/local/bin/pie。

一键安装

注意这不会验证任何签名，您需要自行承担运行风险，但这会将 PIE 放入非 Windows 系统的 /usr/local/bin/pie：

curl -fL --output /tmp/pie.phar https://github.com/php/pie/releases/latest/download/pie.phar \
  && gh attestation verify --owner php /tmp/pie.phar \
  && sudo mv /tmp/pie.phar /usr/local/bin/pie \
  && sudo chmod +x /usr/local/bin/pie

Docker 安装

PIE 以纯二进制 Docker 镜像发布，因此您可以在 Docker 构建期间轻松安装：

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

除了 bin 标签（代表最新的纯二进制镜像）外，您还可以使用明确的版本（格式为 x.y.z-bin）。使用 GitHub registry 查找可用标签。

⁉️ Important

纯二进制镜像不包含 PHP 运行时，因此您不能使用它们来运行 PIE。这只是分发 PHAR 文件的另一种方式，您仍然需要自己满足 PIE 的运行时要求。

在 Dockerfile 中使用 PIE 的示例

这是如何在 Docker 镜像中使用 PIE 安装扩展的示例。注意，与 Composer 类似，您需要安装 unzip、Zip 扩展或 git。

FROM php:8.4-cli

# 添加 PIE 用于解压 .zip 文件的 `unzip` 包
RUN export DEBIAN_FRONTEND="noninteractive"; \
    set -eux; \
    apt-get update; apt-get install -y --no-install-recommends unzip; \
    rm -rf /var/lib/apt/lists/*

# 从最新的 `:bin` 发布版本复制 pie.phar
COPY --from=ghcr.io/php/pie:bin /pie /usr/bin/pie

# 使用 PIE 安装扩展...
RUN pie install asgrim/example-pie-extension

如果您想安装的扩展需要额外的库或其他依赖项，则必须事先安装这些依赖项。

PIE 的先决条件

运行 PIE 需要 PHP 8.1 或更高版本。但是，您仍然可以使用 PIE 为较旧版本的 PHP 安装扩展。

除了 PHP，PIE 还需要系统上有以下工具才能下载、构建和安装扩展：

• 为运行 PIE 的 PHP 版本启用 zip 扩展，或使用 git 下载扩展源代码
• autoconf、automake、libtool、m4、make 和 gcc 来构建扩展
• PHP 开发工具（如 php-config 和 phpize）以准备构建扩展。

此外，每个扩展可能有自己的要求，例如额外的库。

💡 Tip

如果在未安装正确先决条件的情况下运行 PIE，您可能会收到来自 Box Requirements Checker 的错误。如果您想尝试运行，请指定环境变量 BOX_REQUIREMENT_CHECKER=0。

Linux 上的示例：

$ BOX_REQUIREMENT_CHECKER=0 pie install foo/bar

使用 Linux

在基于 Debian 的系统上，您可以使用以下命令安装所需工具：

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

在基于 Red Hat 的系统上，您可以使用以下命令安装所需工具：

sudo yum install git autoconf automake libtool m4 make gcc

使用 macOS

在 macOS 上，您可以使用 Homebrew 安装所需工具：

brew install git autoconf automake libtool m4 make gcc

使用 Windows

在 Windows 上，扩展通常作为预编译的二进制文件分发。您无需自己构建扩展，而是将其作为 DLL 文件下载并放置在 PHP 扩展目录中。

下载、构建或安装扩展

PIE 能够：

• 仅下载扩展，使用 pie download ...，
• 下载并构建扩展，使用 pie build ...，
• 或最常见的，下载、构建和安装扩展，使用 pie install ...

使用 PIE 安装扩展时，必须使用其 Composer 包名称。您可以在 https://packagist.org/extensions 上找到 PIE 兼容包的列表。

知道扩展名称后，您可以使用以下命令安装：

pie install <vendor>/<package>

# 例如：
pie install xdebug/xdebug

这将把 Xdebug 扩展安装到用于调用 PIE 的 PHP 版本中，使用与该 PHP 版本兼容的最新稳定版本的 Xdebug。

使用 PIE 为不同的 PHP 版本安装扩展

如果您试图为不同版本的 PHP 安装扩展，在非 Windows 系统上可以使用 --with-php-config 选项指定：

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

在 Windows 上，您可以使用 --with-php-path 选项提供 php 可执行文件本身的路径。这是 Windows 上的一个示例，其中使用 PHP 8.1 运行 PIE，但我们想为 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

您可能还需要为目标 PHP 版本使用相应的 phpize 命令，可以使用 --with-phpize-path 选项指定：

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

版本约束和稳定性

使用 PIE 安装扩展时，可以选择指定版本约束：

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

如果给出 version-constraint，则尝试安装与允许版本匹配的该版本。版本约束使用与 Composer 相同的格式解析，以及最小稳定性。

• ^1.0 将安装与 1.0.0 及以上版本向后兼容的最新稳定版本，根据语义化版本。 详见 Composer 文档。
• ^2.3@beta 将安装与 2.3.0 及以上版本向后兼容的最新 beta 版本（例如 2.3.0-beta.3）。
• dev-main 将安装命令执行时 main 分支上的最新提交。这不适用于 Windows，因为没有带 Windows 二进制文件的发布版本。
• dev-main#07f454ad797c30651be8356466685b15331f72ff 将安装 # 后的提交 sha 表示的特定提交，在这种情况下将安装提交 07f454ad797c30651be8356466685b15331f72ff。这不适用于 Windows，因为没有带 Windows 二进制文件的发布版本。

当给出 version-constraint 时，它会被检查并直接添加到目标 PHP 版本的 pie.json 中，例如：

$ pie install "xdebug/xdebug:^3.4.3 || 3.4.1"

将在 pie.json 中设置以下内容：

{
    "require": {
        "xdebug/xdebug": "^3.4.3 || 3.4.1"
    }
}

如果未给出 version-constraint，则尝试安装任何兼容的最新稳定版本。PIE 始终优先选择稳定版本。

指定配置选项

编译扩展时，某些扩展需要向 ./configure 命令传递额外参数。这些参数通常用于启用或禁用某些功能，或提供未自动检测到的库路径。

要确定扩展可用的配置选项，可以使用 pie info <vendor>/<package>，它将返回一个列表，例如：

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

然后可以使用无、部分或全部指定的配置选项安装上述示例扩展，一些示例：

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

配置 INI 文件

PIE 会自动尝试通过在适当的 INI 文件中添加 extension=... 或 zend_extension=... 来启用扩展。如果您想禁用此行为，请在 pie install 命令中传递 --skip-enable-extension 标志。尝试启用扩展时使用以下技术：

• 如果使用 deb.sury.org 发行版，使用 phpenmod
• 如果使用 Docker 的 PHP 镜像，使用 docker-php-ext-enable
• 如果配置了"附加 .ini 文件"路径，则添加新文件到该路径
• 如果配置了标准 php.ini，则追加到 php.ini

如果这些技术都不起作用，或者您使用了 --skip-enable-extension 标志，PIE 将警告您扩展未启用，并注意您必须自己启用扩展。

添加非 Packagist.org 仓库

有时您可能想从 Packagist.org 以外的包仓库（如 Private Packagist）安装扩展，或从本地目录安装。由于 PIE 很大程度上基于 Composer，可以使用其他一些仓库类型：

• 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

repository:* 命令都支持可选的 --with-php-config 标志，允许您指定要使用的 PHP 安装（例如，如果一台机器上有多个 PHP 安装）。上述添加的仓库也可以使用相反的 repository:remove 命令删除：

• 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

注意，在 repository:remove 中不需要指定仓库类型，只需提供 URL。

您可以使用以下命令列出目标 PHP 安装的仓库：

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

检查并安装项目缺失的扩展

当在 PHP 项目工作目录中时，可以使用 pie install 来检查项目所需的扩展是否存在。如果缺少扩展，PIE 将尝试找到安装候选并以交互方式询问您是否要安装。例如：

$ pie install
🥧 PHP Installer for Extensions (PIE), 0.9.0, from The PHP Foundation
You are running PHP 8.3.19
Target PHP installation: 8.3.19 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.3)
Checking extensions for your project your-vendor/your-project
requires: curl ✅ Already installed
requires: intl ✅ Already installed
requires: json ✅ Already installed
requires: example_pie_extension ⚠️  Missing

The following packages may be suitable, which would you like to install:
  [0] None
  [1] asgrim/example-pie-extension: Example PIE extension
 > 1
   > 🥧 PHP Installer for Extensions (PIE), 0.9.0, from The PHP Foundation
   > This command may need elevated privileges, and may prompt you for your password.
   > You are running PHP 8.3.19
   > Target PHP installation: 8.3.19 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.3)
   > Found package: asgrim/example-pie-extension:2.0.2 which provides ext-example_pie_extension
   ... (snip) ...
   > ✅ Extension is enabled and loaded in /usr/bin/php8.3

Finished checking extensions.

与 PECL 的比较

由于 PIE 是 PECL 的替代品，这里是您可能熟悉的 PECL 命令与 PIE 中近似等效命令的比较。请注意，某些概念在 PIE 中有所不同或被省略，因为它们可能不适用于新工具。

PIE for Extension Maintainers

The PIE build & install steps

Non-Windows (e.g. Linux, OSX, etc.)

PIE follows the usual PHP extension build and install process, namely:

• phpize to set up the PHP API parameters. The person installing the extension may specify --with-phpize-path if phpize is not in the path.
• ./configure to configure the build parameters and libraries for the specific system. The person installing the extension may specify the configure options that you have specified in composer.json. See the Configure Options documentation for how to do this.
• make to actually build the extension. This will try to detect the number of parallel processes to run automatically, but the person installing may override this with --make-parallel-jobs N or -jN options.
• make install to install the extension to the configured PHP installation. If PIE does not have permissions to write to the installation location, it will attempt to elevate privileges with sudo.

Note that this does mean the systems you are running PIE on need to have the appropriate build tools installed. A useful resource for building extensions and how PHP's internal works is the PHP Internals Book.

Windows

For Windows systems, extension maintainers must provide pre-built binaries. See the Windows Support section below for details on how to do this in the right way for PIE.

How to add PIE support for your extension

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

Extensions already on PECL

If you are a maintainer of an existing PECL extension, here are a few helpful pieces of information for some context:

• For an extension already in PECL, the package.xml is no longer needed if you no longer want to publish to PECL. If you want to keep publishing to PECL for now, then you can keep package.xml maintained.
• The package.xml lists each release explicitly. With PIE, this is no longer necessary, as Packagist will pick up tags or branch aliases in the same way that regular Composer packages do. This means that to release your package, you need to push a tag and release.
• In the default setup, the contents of the package are determined by the Git archive for the tag or revision of the release. You can exclude files and paths from the archive with the export-ignore attribute.

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 as a regular Composer package, 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 (see below for the directives that can be within php-ext)
• The Composer package name (i.e. the top level name field) MUST follow the usual Composer package name format, i.e. <vendor>/<package>.
• However, please note that the Composer package name for a PIE extension MUST NOT 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 MAY 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.

⚠️ Warning

If your Composer package name would result in an invalid PHP extension name, you MUST specify the extension-name directive. For example a Composer package name myvendor/my-extension would result in an invalid PHP extension name, since hypens are not allowed, so you MUST specify a valid extension-name for this Composer package name.

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 forms part of the ini filename to control ordering of extensions, if the target platform uses the multiple INI files in a directory.

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 MUST 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 not be passed to ./configure. There is no way to specify a default value in the configure-options definition. Your config.m4 should handle this accordingly.

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"
    }
}

The build-path may contain some templated values which are replaced:

• {version} to be replaced with the package version. For example a package with version 1.2.3 with a build-path of myext-{version} the actual build path would become myext-1.2.3.

download-url-method

The download-url-method directive allows extension maintainers to change the behaviour of downloading the source package. This should be defined as a list of supported methods, but for backwards compatibility a single string may be used.

The possible values are:

• composer-default
• pre-packaged-source
• pre-packaged-binary

The default value, if nothing is specified is ["composer-default"].

composer-default

Setting this to composer-default, which is the default value if nothing is specified, will use the default behaviour implemented by Composer, which is to use the standard ZIP archive from the GitHub API (or other source control system). PIE will then build and install the extension from source.

pre-packaged-source

Using pre-packaged-source will locate a source code package in the release assets list based matching one of the following naming conventions:

• php_{ExtensionName}-{Version}-src.tgz (e.g. php_myext-1.20.1-src.tgz)
• php_{ExtensionName}-{Version}-src.zip (e.g. php_myext-1.20.1-src.zip)
• {ExtensionName}-{Version}.tgz (this is intended for backwards compatibility with PECL packages)

This is useful for scenarios where you might need additional dependencies pulled into the source build, which would not be available if you downloaded the ZIP archive from your repository. For example, if your extension uses Git Submodules to include third party libraries statically in the build.

pre-packaged-binary

🚨 Caution

If your extension depends on dynamically linked libraries, it is not recommended to use pre-packaged-binary option, as the correct version, or at least compatible linked libraries may not be available on the end user's system. Use with caution!

Using pre-packaged-binary will attempt to locate a Zip (or TGZ) archive in the release assets list based on matching one of the following naming conventions:

• php_{ExtensionName}-{Version}_php{PhpVersion}-{Arch}-{OS}-{Libc}-{Debug}-{TSMode}.{Format}

The replacements are:

• {ExtensionName} the name of your extension, e.g. yourext (hint: this is not your Composer package name!)
• {PhpVersion} the major and minor version of PHP, e.g. 8.5
• {Version} the version of your extension, e.g. 1.20.1
• {Arch} the architecture of the binary, one of x86, x86_64, arm64
• {OS} the operating system, one of windows, darwin, linux, bsd, solaris, unknown
• {Libc} the libc flavour, one of glibc, musl, bsdlibc
• {Debug} the debug mode, one of debug, nodebug (or omitted)
• {TSMode} the thread safety mode, one of zts, nts (or omitted)
• {Format} the archive format, one of zip, tgz - note that ZIP is preferred as it means there are fewer dependencies for the end user

💡 Tip

In order to generate pre-built binaries for PIE, you could use the php/pie-ext-binary-builder GitHub Action. This will build and name the assets correctly for you.

Some examples of valid asset names:

• php_yourext-4.1_php8.4-x86_64-linux-glibc.zip (or php_yourext-4.1_php8.4-x86_64-glibc-nts.zip)
• php_yourext-4.1_php8.4-x86_64-linux-musl.zip (or php_yourext-4.1_php8.4-x86_64-musl-nts.zip)
• php_yourext-4.1_php8.4-arm64-linux-glibc.zip (or php_yourext-4.1_php8.4-arm64-glibc-nts.zip)
• php_yourext-4.1_php8.4-arm64-linux-musl.zip (or php_yourext-4.1_php8.4-arm64-musl-nts.zip)
• php_yourext-4.1_php8.4-x86_64-linux-glibc-zts.zip
• php_yourext-4.1_php8.4-x86_64-linux-musl-zts.zip
• php_yourext-4.1_php8.4-arm64-linux-glibc-zts.zip
• php_yourext-4.1_php8.4-arm64-linux-musl-zts.zip
• php_yourext-4.1_php8.4-x86_64-linux-glibc-debug.zip
• php_yourext-4.1_php8.4-x86_64-linux-musl-debug.zip
• php_yourext-4.1_php8.4-arm64-linux-glibc-debug.zip
• php_yourext-4.1_php8.4-arm64-linux-musl-debug.zip

It is recommended that pre-packaged-binary is combined with composer-default as a fallback mechanism, if a particular combination is supported, but not pre-packaged on the release, e.g. "download-url-method": ["pre-packaged-binary", "composer-default"]. PIE will try to find a pre-packaged binary asset first, but if it cannot find an appropriate binary, it will download the source code and build it in the traditional manner.

{
    "name": "myvendor/myext",
    "php-ext": {
        "download-url-method": ["pre-packaged-binary", "composer-default"]
    }
}

os-families restrictions

The os-families and os-families-exclude directive allow extention maintainers to restrict the Operating System compatibility.

• os-families An array of OS families to mark as compatible with the extension. (e.g. "os-families": ["windows"] for an extension only available on Windows)
• os-families-exclude An array of OS families to mark as incompatible with the extension. (e.g. "os-families-exclude": ["windows"] for an extension that cannot be installed available on Windows)

The list of accepted OS families: "windows", "bsd", "darwin", "solaris", "linux", "unknown"

⚠️ Warning

Only one of os-families and os-families-exclude can be defined.

Extension dependencies

Extension authors may define some dependencies in require, but typically, most extensions would not need to define dependencies, except for the PHP versions supported by the extension, and system libraries.

Dependencies on a regular PHP package (such as monolog/monolog) SHOULD NOT be specified in your extension's require section.

Dependencies on other extensions

Dependencies on other extensions may be defined, for example ext-json.

It is worth noting that if your extension does define a dependency on another dependency, and this is not available, someone installing your extension would receive a message such as:

Cannot use myvendor/myextension's latest version 1.2.3 as it requires
ext-something * which is missing from your platform.

System Library Dependencies

In PIE 1.4.0, the ability for extension authors to define system library dependencies was added, and in some cases, automatically install them.

The following libraries are supported at the moment. If you would like to add a library, please open a discussion in the first instance. Don't just open a PR without discussing first please!

We are adding libraries and improving this feature over time. If the automatic install of a system dependency that is supported below in your package manager is NOT working, then please report a bug.

Checking the extension will work

First up, you can use composer validate to check your composer.json is formatted correctly, e.g.:

$ composer validate
./composer.json is valid

You may then use pie install to install your extension while in its directory:

$ cd /path/to/my/extension
$ pie install
🥧 PHP Installer for Extensions (PIE) 1.0.0, from The PHP Foundation
Installing PIE extension from /home/james/workspace/phpf/example-pie-extension
This command may need elevated privileges, and may prompt you for your password.
You are running PHP 8.4.8
Target PHP installation: 8.4.8 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.4)
Found package: asgrim/example-pie-extension:dev-main which provides ext-example_pie_extension
Extracted asgrim/example-pie-extension:dev-main source to: /home/james/.config/pie/php8.4_572ee73609adb95bf0b8539fecdc5c0e/vendor/asgrim/example-pie-extension
Build files cleaned up.
phpize complete.
Configure complete.
Build complete: /home/james/.config/pie/php8.4_572ee73609adb95bf0b8539fecdc5c0e/vendor/asgrim/example-pie-extension/modules/example_pie_extension.so
Cannot write to /usr/lib/php/20240924, so using sudo to elevate privileges.
Install complete: /usr/lib/php/20240924/example_pie_extension.so
✅ Extension is enabled and loaded in /usr/bin/php8.4

Building without installing

If you want to just test the build of your application, without installling it to your target PHP version, you will first need to your extension directory as a "path" type repository:

$ cd /path/to/my/extension
$ pie repository:add path .
🥧 PHP Installer for Extensions (PIE) 1.0.0, from The PHP Foundation
You are running PHP 8.4.8
Target PHP installation: 8.4.8 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.4)
The following repositories are in use for this Target PHP:
  - Path Repository (/home/james/workspace/phpf/example-pie-extension)
  - Packagist

Then you may test that it builds with:

$ pie build asgrim/example-pie-extension:*@dev

💡 Tip

Since your extension is not yet published to Packagist, you should specify *@dev as the version constraint, otherwise PIE will not find your extension as the default stability is stable.

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: use a hint from Architecture from php -i (see below)
  • non-Windows: check PHP_INT_SIZE - 4 for 32-bit, 8 for 64-bit.

Note the architecture name will likely need normalising, since different platforms name architectures differently. PIE expects the following normalised architectures:

• x86_64 (normalised from x64, x86_64, AMD64)
• arm64 (normalised from arm64)
• x86 (any other value)

For the latest map (in case documentation is not up to date), check out \Php\Pie\Platform\Architecture::parseArchitecture.

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#examples

Other features

Placeholder Replacement

To help backwards compatibility with PECL extensions, PIE supports some automatic placeholder replacements within all .c and .h files found within the downloaded source directory. These placeholders are replaced after the download step, and before the build step. PIE will automatically replace the following placeholders:

⚠️ Warning

This translation may not be based on the latest version, please ensure you check the original English version for discrepancies.

PIE 拡張機能メンテナーガイド

PIE のビルドとインストール手順

非 Windows（例：Linux、OSX など）

PIE は通常の PHP 拡張機能のビルドとインストールプロセスに従います：

• phpize で PHP API パラメータを設定します。拡張機能をインストールする人は、phpize がパスにない場合 --with-phpize-path を指定できます。
• ./configure で特定のシステムのビルドパラメータとライブラリを設定します。拡張機能をインストールする人は、composer.json で指定した設定オプションを指定できます。これを行う方法については、設定オプションドキュメントを参照してください。
• make で実際に拡張機能をビルドします。これは実行する並列プロセスの数を自動的に検出しようとしますが、インストールする人は --make-parallel-jobs N または -jN オプションでこれをオーバーライドできます。
• make install で設定された PHP インストールに拡張機能をインストールします。PIE がインストール場所への書き込み権限を持っていない場合、sudo で権限を昇格しようとします。

これは、PIE を実行しているシステムに適切なビルドツールがインストールされている必要があることを意味します。拡張機能のビルドと PHP の内部動作に関する有用なリソースは PHP Internals Book です。

Windows

Windows システムの場合、拡張機能メンテナーはプリビルドされたバイナリを提供する必要があります。PIE 用に正しい方法でこれを行う方法の詳細については、以下の Windows サポートセクションを参照してください。

拡張機能に PIE サポートを追加する方法

拡張機能に PIE サポートを追加することは比較的簡単で、通常の PHP パッケージを Packagist に追加するのと非常に似ています。

すでに PECL にある拡張機能

既存の PECL 拡張機能のメンテナーの場合、以下はコンテキストのための有用な情報です：

• すでに PECL にある拡張機能の場合、PECL への公開を続けたくない場合、package.xml は不要です。今すぐ PECL への公開を続けたい場合は、package.xml を維持し続けることができます。
• package.xml は各リリースを明示的にリストします。PIE では、Packagist が通常の Composer パッケージと同じ方法でタグまたはブランチエイリアスを取得するため、これは不要になりました。これは、パッケージをリリースするには、タグとリリースをプッシュする必要があることを意味します。
• デフォルトの設定では、パッケージの内容はリリースのタグまたはリビジョンの Git archive によって決定されます。export-ignore 属性を使用して、アーカイブからファイルとパスを除外できます。

拡張機能に composer.json を追加

PIE サポートを追加する最初のステップは、拡張機能リポジトリに composer.json を追加することです。ほとんどの典型的なフィールドは通常の Composer パッケージと同じですが、いくつかの注目すべき例外があります：

• type は PHP モジュールの場合は php-ext（これがほとんどの拡張機能になります）、または Zend 拡張機能の場合は php-ext-zend である必要があります。
• 追加の php-ext セクションが存在する可能性があります（php-ext 内に含めることができるディレクティブについては以下を参照）
• Composer パッケージ名（つまりトップレベルの name フィールド）は、通常の Composer パッケージ名形式に従う必要があります。つまり <vendor>/<package> です。
• ただし、PIE 拡張機能の Composer パッケージ名は、type フィールドが異なる場合でも、通常の PHP パッケージと同じ Composer パッケージ名を共有してはなりません。

php-ext 定義

extension-name

extension-name を指定することができ、\Php\Pie\ExtensionName::VALID_PACKAGE_NAME_REGEX で定義されている通常の拡張機能名正規表現に準拠する必要があります。extension-name が指定されていない場合、extension-name は Composer パッケージ名から派生し、ベンダープレフィックスが削除されます。例えば、次の composer.json の場合：

{
    "name": "myvendor/myextension"
}

拡張機能名は myextension として派生されます。myvendor/ ベンダープレフィックスは削除されます。

⚠️ Warning

Composer パッケージ名が無効な PHP 拡張機能名になる場合、extension-name ディレクティブを指定する必要があります。例えば、Composer パッケージ名 myvendor/my-extension はハイフンが許可されていないため無効な PHP 拡張機能名になるため、この Composer パッケージ名には有効な extension-name を指定する必要があります。

extension-name は、Composer で require を使用する際の慣例である ext- でプレフィックスを付けるべきではありません。

extension-name の使用例：

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

priority

priority は ini ファイル名の一部を形成し、ターゲットプラットフォームがディレクトリ内の複数の INI ファイルを使用する場合、拡張機能の順序を制御します。

support-zts と support-nts

拡張機能が Zend Thread-Safe（ZTS）および非スレッドセーフ（NTS）モードをサポートするかどうかを示します。これらのフラグは指定されていない場合、両方ともデフォルトで true ですが、拡張機能がいずれかのモードをサポートしていない場合は指定する必要があり、ターゲットプラットフォームに拡張機能をインストールできないことを意味します。

理論的には、support-zts と support-nts の両方に false を指定することは可能ですが、これはパッケージをどこにもインストールできないことを意味するため、推奨されません。

configure-options

これは ./configure コマンドに渡すことができるパラメータのリストです。リストの各項目は次の JSON オブジェクトです：

• name、パラメータ名自体
• description、パラメータが何をするかの役立つ説明
• オプションで needs-value、PIE にパラメータが単純なフラグ（通常 --enable-this-flag タイプのパラメータに使用）か、パラメータに値を指定する必要があるか（通常 --with-library-path=... タイプのパラメータに使用され、エンドユーザーが値を指定する必要がある）を伝えるブール値

エンドユーザーが PIE で拡張機能をインストールする場合、./configure に渡される定義済みの configure-options を指定できます。例えば、拡張機能が次の 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
            }
        ]
    }
}

次のように pie build または pie install コマンドを呼び出して、目的の設定を実現できます：

• pie install myvendor/myext
  • これは単にパラメータなしで ./configure を呼び出します
• pie install myvendor/myext --enable-my-flag
  • これは ./configure --enable-my-flag を呼び出します
• pie install myvendor/myext --with-some-lib=/path/to/somelib
  • これは ./configure --with-some-lib=/path/to/somelib を呼び出します
• pie install myvendor/myext --enable-my-flag --with-some-lib=/path/to/somelib
  • これは ./configure --enable-my-flag --with-some-lib=/path/to/somelib を呼び出します

PIE のエンドユーザーは、拡張機能の configure-options 定義で定義されていない設定オプションを指定することはできません。上記と同じ composer.json の例を使用して、無効なオプションで PIE を呼び出す場合、例えば pie install myvendor/myext --something-else はエラー The "--something-else" option does not exist. になります。

エンドユーザーが configure-options 定義で定義されたフラグを指定しない場合、それは ./configure に渡されません。configure-options 定義でデフォルト値を指定する方法はありません。config.m4 でこれに応じて処理する必要があります。

build-path

ソースコードがリポジトリのルートにない場合、build-path 設定を使用できます。例えば、リポジトリ構造が次のような場合：

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

この場合、実際の拡張機能ソースコードは src/ でビルドされるため、build-path でこのパスを指定する必要があります：

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

build-path には、置き換えられるテンプレート値を含めることができます：

• {version} はパッケージバージョンに置き換えられます。例えば、バージョン 1.2.3 のパッケージで build-path が myext-{version} の場合、実際のビルドパスは myext-1.2.3 になります。

download-url-method

download-url-method ディレクティブにより、拡張機能メンテナーはソースパッケージのダウンロード動作を変更できます。

• これを composer-default に設定すると（指定されていない場合のデフォルト値）、Composer によって実装されたデフォルトの動作が使用されます。これは、GitHub API（または他のソースコントロールシステム）からの標準 ZIP アーカイブを使用することです。
• pre-packaged-source を使用すると、次の命名規則のいずれかに一致するリリースアセットリストでソースコードパッケージを見つけます：
  • php_{ExtensionName}-{Version}-src.tgz（例：php_myext-1.20.1-src.tgz）
  • php_{ExtensionName}-{Version}-src.zip（例：php_myext-1.20.1-src.zip）
  • {ExtensionName}-{Version}.tgz（これは PECL パッケージとの後方互換性のため）

os-families 制限

os-families および os-families-exclude ディレクティブにより、拡張機能メンテナーはオペレーティングシステムの互換性を制限できます。

• os-families 拡張機能と互換性があるとマークする OS ファミリーの配列。（例："os-families": ["windows"] は Windows でのみ利用可能な拡張機能）
• os-families-exclude 拡張機能と互換性がないとマークする OS ファミリーの配列。（例："os-families-exclude": ["windows"] は Windows にインストールできない拡張機能）

受け入れられる OS ファミリーのリスト："windows"、"bsd"、"darwin"、"solaris"、"linux"、"unknown"

⚠️ Warning

os-families と os-families-exclude のうち 1 つだけを定義できます。

拡張機能の依存関係

拡張機能作成者は require でいくつかの依存関係を定義できますが、実際には、ほとんどの拡張機能は、拡張機能がサポートする PHP バージョンを除いて、依存関係を定義する必要はありません。他の拡張機能への依存関係（例：ext-json）を定義できます。ただし、通常の PHP パッケージ（例：monolog/monolog）への依存関係は require セクションで指定すべきではありません。

拡張機能が別の依存関係への依存関係を定義し、これが利用できない場合、拡張機能をインストールする人は次のようなメッセージを受け取ります：

Cannot use myvendor/myextension's latest version 1.2.3 as it requires
ext-something * which is missing from your platform.

拡張機能が動作するかどうかの確認

まず、composer validate を使用して composer.json が正しくフォーマットされているか確認できます：

$ composer validate
./composer.json is valid

次に、拡張機能のディレクトリで pie install を使用して拡張機能をインストールできます：

$ cd /path/to/my/extension
$ pie install
🥧 PHP Installer for Extensions (PIE) 1.0.0, from The PHP Foundation
Installing PIE extension from /home/james/workspace/phpf/example-pie-extension
This command may need elevated privileges, and may prompt you for your password.
You are running PHP 8.4.8
Target PHP installation: 8.4.8 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.4)
Found package: asgrim/example-pie-extension:dev-main which provides ext-example_pie_extension
Extracted asgrim/example-pie-extension:dev-main source to: /home/james/.config/pie/php8.4_572ee73609adb95bf0b8539fecdc5c0e/vendor/asgrim/example-pie-extension
Build files cleaned up.
phpize complete.
Configure complete.
Build complete: /home/james/.config/pie/php8.4_572ee73609adb95bf0b8539fecdc5c0e/vendor/asgrim/example-pie-extension/modules/example_pie_extension.so
Cannot write to /usr/lib/php/20240924, so using sudo to elevate privileges.
Install complete: /usr/lib/php/20240924/example_pie_extension.so
✅ Extension is enabled and loaded in /usr/bin/php8.4

インストールせずにビルドのみ

アプリケーションのビルドをテストするだけで、ターゲット PHP バージョンにインストールしない場合、まず拡張機能ディレクトリを「path」タイプのリポジトリとして追加する必要があります：

$ cd /path/to/my/extension
$ pie repository:add path .
🥧 PHP Installer for Extensions (PIE) 1.0.0, from The PHP Foundation
You are running PHP 8.4.8
Target PHP installation: 8.4.8 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.4)
The following repositories are in use for this Target PHP:
  - Path Repository (/home/james/workspace/phpf/example-pie-extension)
  - Packagist

次に、ビルドをテストできます：

$ pie build asgrim/example-pie-extension:*@dev

💡 Tip

拡張機能がまだ Packagist に公開されていないため、バージョン制約として *@dev を指定する必要があります。そうしないと、デフォルトの安定性が stable であるため、PIE は拡張機能を見つけられません。

Packagist に拡張機能を提出

composer.json をリポジトリにコミットしたら、他のパッケージと同じように Packagist に提出できます。

• https://packagist.org/packages/submit にアクセス
• リポジトリの URL を入力し、指示に従ってください。

Windows サポート

Windows ユーザーをサポートするには、PIE は現在 DLL をオンザフライでビルドすることをサポートしていないため、プリビルドされた DLL を公開する必要があります。Windows 互換リリースの予想されるワークフローは次のとおりです：

• GitHub でリリースが行われます（現時点では GitHub のみサポート）
• CI パイプラインが実行され、リリースアセットをビルドします（例：GitHub Action）
• 結果のビルドアセットが ZIP ファイルとして GitHub リリースに公開されます

ZIP ファイルの名前とその中に含まれる DLL は次のようにする必要があります：

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

これらの項目の説明：

• extension-name 拡張機能名、例：xdebug
• tag 例：3.3.0alpha3 - 作成したタグ/リリースで定義
• php-maj/min - 例：PHP 8.3.* の場合は 8.3
• compiler - 通常 vc6、vs16 のようなもの - php -i の 'PHP Extension Build' フラグから取得
• ts|nts - スレッドセーフまたは非スレッドセーフ
• arch - 例：x86_64
  • Windows：php -i の Architecture からヒントを使用（下記参照）
  • 非 Windows：PHP_INT_SIZE を確認 - 32 ビットの場合は 4、64 ビットの場合は 8

アーキテクチャ名は正規化が必要な場合があります。異なるプラットフォームでアーキテクチャの名前が異なるためです。PIE は次の正規化されたアーキテクチャを期待します：

• x86_64（x64、x86_64、AMD64 から正規化）
• arm64（arm64 から正規化）
• x86（その他の値）

最新のマップ（ドキュメントが最新でない場合）については、\Php\Pie\Platform\Architecture::parseArchitecture を確認してください。

Windows ZIP の内容

プリビルドされた ZIP には、ZIP 自体と同じ名前の DLL が少なくとも含まれている必要があります。例：php_{extension-name}-{tag}-{php-maj/min}-{ts|nts}-{compiler}-{arch}.dll。.dll は PHP 拡張機能パスに移動され、名前が変更されます。例：C:\path\to\php\ext\php_{extension-name}.dll に移動されます。ZIP ファイルには次のような追加のリソースが含まれる場合があります：

• php_{extension-name}-{tag}-{php-maj/min}-{ts|nts}-{compiler}-{arch}.pdb - これは C:\path\to\php\ext\php_{extension-name}.dll の隣に移動されます
• *.dll - 他の .dll は C:\path\to\php\php.exe の隣に移動されます
• その他のファイルは C:\path\to\php\extras\{extension-name}\. に移動されます

Windows 公開の自動化

PHP は、拡張機能メンテナーが Windows 互換アセットをビルドおよびリリースできるようにする 一連の GitHub 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 }}

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

⚠️ Warning

This translation may not be based on the latest version, please ensure you check the original English version for discrepancies.

PIE メンテナーハンドブック

ブランチ戦略

現在、単一の main ブランチと機能ブランチを運用しています。将来、パッチバージョンをより適切にサポートするために、バージョン管理されたブランチ戦略に切り替える可能性があります。

リリースプロセス

リリースする最新バージョンを持っていることを確認してください。例：

# git reset を使用（注意：`main` 上のローカルコミットは破棄されます）
git checkout main && git fetch upstream && git reset --hard upstream/main
# または、git pull を使用（マージコミットを避けるために `--ff-only` を使用）
git checkout main && git pull --ff-only upstream main

変更履歴を準備し、リリースするバージョンとマイルストーンを設定します。例：

PIE_VERSION=1.3.0
PIE_MILESTONE=$PIE_VERSION

💡 Tip

プレリリースの場合、バージョン/マイルストーンを異なる値に設定できます。例：

PIE_VERSION=1.3.0-alpha.2
PIE_MILESTONE=1.3.0

これにより、1.3.0-alpha.2 バージョンでタグ付け/リリースされますが、変更履歴は GitHub の 1.3.0 マイルストーンに基づいて生成されます。

次に、変更履歴ファイルを生成します：

composer require --dev -W jwage/changelog-generator --no-interaction
vendor/bin/changelog-generator generate --user=php --repository=pie --milestone=$PIE_MILESTONE > CHANGELOG-$PIE_VERSION.md
git checkout -- composer.*
composer install

変更履歴の内容に満足しているか確認してください。署名付きタグを作成します：

git tag -s $PIE_VERSION -F CHANGELOG-$PIE_VERSION.md
git push upstream $PIE_VERSION

リリースパイプラインが実行され、ドラフトリリースが作成され、PHAR ファイルがビルドされて添付されます。その後、GitHub のドラフトリリースに移動し、すべてが正しいことを確認してから、リリースを公開する必要があります。

rm CHANGELOG-$PIE_VERSION.md

⚠️ Warning

This translation may not be based on the latest version, please ensure you check the original English version for discrepancies.

PIE 扩展维护者指南

PIE 构建和安装步骤

非 Windows（例如 Linux、OSX 等）

PIE 遵循通常的 PHP 扩展构建和安装过程，即：

• phpize 用于设置 PHP API 参数。如果 phpize 不在路径中，安装扩展的人可以指定 --with-phpize-path。
• ./configure 用于为特定系统配置构建参数和库。安装扩展的人可以指定您在 composer.json 中指定的配置选项。有关如何执行此操作，请参阅配置选项文档。
• make 实际构建扩展。这将尝试自动检测要运行的并行进程数，但安装的人可以使用 --make-parallel-jobs N 或 -jN 选项覆盖此设置。
• make install 将扩展安装到配置的 PHP 安装中。如果 PIE 没有写入安装位置的权限，它将尝试使用 sudo 提升权限。

请注意，这意味着运行 PIE 的系统需要安装适当的构建工具。有关构建扩展和 PHP 内部工作原理的有用资源是 PHP Internals Book。

Windows

对于 Windows 系统，扩展维护者必须提供预构建的二进制文件。有关如何以正确的方式为 PIE 执行此操作的详细信息，请参阅下面的 Windows 支持部分。

如何为您的扩展添加 PIE 支持

为您的扩展添加 PIE 支持相对简单，流程与将常规 PHP 包添加到 Packagist 非常相似。

已在 PECL 上的扩展

如果您是现有 PECL 扩展的维护者，以下是一些有用的上下文信息：

• 对于已在 PECL 中的扩展，如果您不再想发布到 PECL，则不再需要 package.xml。如果您现在想继续发布到 PECL，则可以继续维护 package.xml。
• package.xml 明确列出每个版本。使用 PIE，这不再需要，因为 Packagist 会像常规 Composer 包一样获取标签或分支别名。这意味着要发布您的包，您需要推送标签和发布版本。
• 在默认设置中，包的内容由标签或发布版本的 Git archive 确定。您可以使用 export-ignore 属性从存档中排除文件和路径。

向扩展添加 composer.json

添加 PIE 支持的第一步是向扩展仓库添加 composer.json。大多数典型字段与常规 Composer 包相同，但有几个值得注意的例外：

• type 必须是 php-ext（用于 PHP 模块，这将是大多数扩展）或 php-ext-zend（用于 Zend 扩展）。
• 可以存在额外的 php-ext 部分（请参阅下面有关 php-ext 中可以包含的指令）
• Composer 包名称（即顶级 name 字段）必须遵循通常的 Composer 包名称格式，即 <vendor>/<package>。
• 但是，请注意，PIE 扩展的 Composer 包名称不得与常规 PHP 包共享相同的 Composer 包名称，即使它们具有不同的 type 字段。

php-ext 定义

extension-name

可以指定 extension-name，并且必须符合通常的扩展名称正则表达式，该表达式在 \Php\Pie\ExtensionName::VALID_PACKAGE_NAME_REGEX 中定义。如果未指定 extension-name，则 extension-name 将从 Composer 包名称派生，删除供应商前缀。例如，给定一个 composer.json：

{
    "name": "myvendor/myextension"
}

扩展名称将派生为 myextension。myvendor/ 供应商前缀被删除。

⚠️ Warning

如果您的 Composer 包名称会导致无效的 PHP 扩展名称，您必须指定 extension-name 指令。例如，Composer 包名称 myvendor/my-extension 会导致无效的 PHP 扩展名称，因为不允许使用连字符，因此您必须为此 Composer 包名称指定有效的 extension-name。

extension-name 不应以 ext- 为前缀，这是 Composer 在使用 require 时的约定。

使用 extension-name 的示例：

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

priority

priority 构成 ini 文件名的一部分，用于控制扩展的顺序，如果目标平台使用目录中的多个 INI 文件。

support-zts 和 support-nts

指示扩展是否支持 Zend Thread-Safe（ZTS）和非线程安全（NTS）模式。如果未指定，这两个标志都默认为 true，但如果您的扩展不支持任一模式，则必须指定，这将意味着扩展无法在目标平台上安装。

理论上，可以为 support-zts 和 support-nts 都指定 false，但这将意味着您的包无法在任何地方安装，因此不建议这样做。

configure-options

这是可以传递给 ./configure 命令的参数列表。列表的每个项目都是一个 JSON 对象，包含：

• name，参数名称本身
• description，参数作用的有用描述
• 可选的 needs-value，一个布尔值，告诉 PIE 参数是简单标志（通常用于 --enable-this-flag 类型参数），还是参数应该有一个指定的值（通常用于 --with-library-path=... 类型参数，其中最终用户必须提供一个值）

当最终用户使用 PIE 安装扩展时，他们可以指定传递给 ./configure 的任何已定义的 configure-options。例如，如果扩展定义了以下 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
            }
        ]
    }
}

然后可以以以下方式调用 pie build 或 pie install 命令以实现所需的配置：

• pie install myvendor/myext
  • 这将简单地调用 ./configure 而不带任何参数
• pie install myvendor/myext --enable-my-flag
  • 这将调用 ./configure --enable-my-flag
• pie install myvendor/myext --with-some-lib=/path/to/somelib
  • 这将调用 ./configure --with-some-lib=/path/to/somelib
• pie install myvendor/myext --enable-my-flag --with-some-lib=/path/to/somelib
  • 这将调用 ./configure --enable-my-flag --with-some-lib=/path/to/somelib

请注意，PIE 的最终用户无法指定未在您的扩展的 configure-options 定义中定义的配置选项。使用上面相同的 composer.json 示例，使用无效选项调用 PIE，例如 pie install myvendor/myext --something-else 将导致错误 The "--something-else" option does not exist.。

如果最终用户未指定 configure-options 定义中定义的标志，则不会将其传递给 ./configure。无法在 configure-options 定义中指定默认值。您的 config.m4 应相应地处理此问题。

build-path

如果源代码不在仓库的根目录中，可以使用 build-path 设置。例如，如果您的仓库结构如下：

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

在这种情况下，实际的扩展源代码将在 src/ 中构建，因此您应该在 build-path 中指定此路径，例如：

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

build-path 可以包含一些被替换的模板值：

• {version} 将被替换为包版本。例如，版本为 1.2.3 的包，build-path 为 myext-{version}，实际构建路径将变为 myext-1.2.3。

download-url-method

download-url-method 指令允许扩展维护者更改下载源包的行为。

• 将其设置为 composer-default（如果未指定则为默认值），将使用 Composer 实现的默认行为，即使用来自 GitHub API（或其他源代码控制系统）的标准 ZIP 存档。
• 使用 pre-packaged-source 将在发布资源列表中定位源代码包，该包基于以下命名约定之一：
  • php_{ExtensionName}-{Version}-src.tgz（例如 php_myext-1.20.1-src.tgz）
  • php_{ExtensionName}-{Version}-src.zip（例如 php_myext-1.20.1-src.zip）
  • {ExtensionName}-{Version}.tgz（这是为了与 PECL 包向后兼容）

os-families 限制

os-families 和 os-families-exclude 指令允许扩展维护者限制操作系统兼容性。

• os-families 一个操作系统家族的数组，用于标记与扩展兼容。（例如 "os-families": ["windows"] 表示仅在 Windows 上可用的扩展）
• os-families-exclude 一个操作系统家族的数组，用于标记与扩展不兼容。（例如 "os-families-exclude": ["windows"] 表示无法在 Windows 上安装的扩展）

接受的操作系统家族列表："windows"、"bsd"、"darwin"、"solaris"、"linux"、"unknown"

⚠️ Warning

只能定义 os-families 和 os-families-exclude 之一。

扩展依赖项

扩展作者可以在 require 中定义一些依赖项，但实际上，大多数扩展不需要定义依赖项，除了扩展支持的 PHP 版本。可以定义对其他扩展的依赖项，例如 ext-json。但是，不应在 require 部分指定对常规 PHP 包（如 monolog/monolog）的依赖项。

值得注意的是，如果您的扩展确实定义了对另一个依赖项的依赖，并且此依赖项不可用，则安装您的扩展的人将收到如下消息：

Cannot use myvendor/myextension's latest version 1.2.3 as it requires
ext-something * which is missing from your platform.

检查扩展是否能工作

首先，您可以使用 composer validate 检查您的 composer.json 格式是否正确，例如：

$ composer validate
./composer.json is valid

然后，您可以在扩展目录中使用 pie install 安装扩展：

$ cd /path/to/my/extension
$ pie install
🥧 PHP Installer for Extensions (PIE) 1.0.0, from The PHP Foundation
Installing PIE extension from /home/james/workspace/phpf/example-pie-extension
This command may need elevated privileges, and may prompt you for your password.
You are running PHP 8.4.8
Target PHP installation: 8.4.8 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.4)
Found package: asgrim/example-pie-extension:dev-main which provides ext-example_pie_extension
Extracted asgrim/example-pie-extension:dev-main source to: /home/james/.config/pie/php8.4_572ee73609adb95bf0b8539fecdc5c0e/vendor/asgrim/example-pie-extension
Build files cleaned up.
phpize complete.
Configure complete.
Build complete: /home/james/.config/pie/php8.4_572ee73609adb95bf0b8539fecdc5c0e/vendor/asgrim/example-pie-extension/modules/example_pie_extension.so
Cannot write to /usr/lib/php/20240924, so using sudo to elevate privileges.
Install complete: /usr/lib/php/20240924/example_pie_extension.so
✅ Extension is enabled and loaded in /usr/bin/php8.4

仅构建不安装

如果您只想测试应用程序的构建而不将其安装到目标 PHP 版本，您首先需要将扩展目录添加为"path"类型仓库：

$ cd /path/to/my/extension
$ pie repository:add path .
🥧 PHP Installer for Extensions (PIE) 1.0.0, from The PHP Foundation
You are running PHP 8.4.8
Target PHP installation: 8.4.8 nts, on Linux/OSX/etc x86_64 (from /usr/bin/php8.4)
The following repositories are in use for this Target PHP:
  - Path Repository (/home/james/workspace/phpf/example-pie-extension)
  - Packagist

然后，您可以测试它是否构建：

$ pie build asgrim/example-pie-extension:*@dev

💡 Tip

由于您的扩展尚未发布到 Packagist，因此应指定 *@dev 作为版本约束，否则 PIE 将找不到您的扩展，因为默认稳定性为 stable。

将扩展提交到 Packagist

将 composer.json 提交到仓库后，您可以像提交任何其他包一样将其提交到 Packagist。

• 前往 https://packagist.org/packages/submit
• 输入您的仓库的 URL 并按照说明操作。

Windows 支持

为了支持 Windows 用户，您必须发布预构建的 DLL，因为 PIE 目前不支持即时构建 DLL。Windows 兼容版本的预期工作流程是：

• 在 GitHub 上进行发布（目前仅支持 GitHub）
• CI 流水线运行以构建发布资源，例如在 GitHub Action 中
• 生成的构建资源以 ZIP 文件形式发布到 GitHub 发布版本

ZIP 文件的名称以及其中包含的 DLL 必须是：

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

这些项目的描述：

• extension-name 扩展名称，例如 xdebug
• tag 例如 3.3.0alpha3 - 由您制作的标签/发布版本定义
• php-maj/min - 例如 8.3 表示 PHP 8.3.*
• compiler - 通常是像 vc6、vs16 这样的东西 - 从 php -i 中的 'PHP Extension Build' 标志获取
• ts|nts - 线程安全或非线程安全。
• arch - 例如 x86_64。
  • Windows：使用 php -i 中 Architecture 的提示（见下文）
  • 非 Windows：检查 PHP_INT_SIZE - 32 位为 4，64 位为 8。

请注意，架构名称可能需要规范化，因为不同平台对架构的命名不同。PIE 期望以下规范化的架构：

• x86_64（从 x64、x86_64、AMD64 规范化）
• arm64（从 arm64 规范化）
• x86（任何其他值）

有关最新映射（如果文档不是最新的），请查看 \Php\Pie\Platform\Architecture::parseArchitecture。

Windows ZIP 的内容

预构建的 ZIP 应至少包含一个与 ZIP 本身命名相同的 DLL，例如 php_{extension-name}-{tag}-{php-maj/min}-{ts|nts}-{compiler}-{arch}.dll。.dll 将被移动到 PHP 扩展路径并重命名，例如移动到 C:\path\to\php\ext\php_{extension-name}.dll。ZIP 文件可能包含额外的资源，例如：

• php_{extension-name}-{tag}-{php-maj/min}-{ts|nts}-{compiler}-{arch}.pdb - 这将被移动到 C:\path\to\php\ext\php_{extension-name}.dll 旁边
• *.dll - 任何其他 .dll 都将被移动到 C:\path\to\php\php.exe 旁边
• 任何其他文件，将被移动到 C:\path\to\php\extras\{extension-name}\.

Windows 发布的自动化

PHP 提供了一组 GitHub Actions，使扩展维护者能够构建和发布 Windows 兼容资源。使用这些操作的示例工作流程：

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

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

⚠️ Warning

This translation may not be based on the latest version, please ensure you check the original English version for discrepancies.

PIE 维护者手册

分支策略

目前，我们使用单一的 main 分支和功能分支。未来，为了更好地支持补丁版本，我们可能会切换到版本化分支策略。

发布流程

确保您拥有要发布的最新版本，例如：

# 使用 git reset（注意：会丢弃 `main` 上的任何本地提交）
git checkout main && git fetch upstream && git reset --hard upstream/main
# 或者，使用 git pull（使用 `--ff-only` 避免创建合并提交）
git checkout main && git pull --ff-only upstream main

准备变更日志，设置要发布的版本和里程碑，例如：

PIE_VERSION=1.3.0
PIE_MILESTONE=$PIE_VERSION

💡 Tip

对于预发布版本，您可以将版本/里程碑设置为不同的值，例如：

PIE_VERSION=1.3.0-alpha.2
PIE_MILESTONE=1.3.0

这将使用 1.3.0-alpha.2 版本进行标记/发布，但会基于 GitHub 中的 1.3.0 里程碑生成变更日志。

然后生成变更日志文件：

composer require --dev -W jwage/changelog-generator --no-interaction
vendor/bin/changelog-generator generate --user=php --repository=pie --milestone=$PIE_MILESTONE > CHANGELOG-$PIE_VERSION.md
git checkout -- composer.*
composer install

检查您是否对变更日志的内容满意。创建一个签名标签：

git tag -s $PIE_VERSION -F CHANGELOG-$PIE_VERSION.md
git push upstream $PIE_VERSION

发布流水线将运行，它将创建一个草稿发布版本，构建 PHAR 文件并附加它。然后，您必须转到 GitHub 上的草稿发布版本，验证一切正确，然后发布该发布版本。

rm CHANGELOG-$PIE_VERSION.md

⚠️ Warning

This translation may not be based on the latest version, please ensure you check the original English version for discrepancies.

サポートされている拡張機能

Packagist が PIE パッケージの新しいホームであるため、サポートされている PIE 互換拡張機能の完全なリストは以下で確認できます：

• https://packagist.org/extensions

PIE サポートを追加するプロセスは、拡張機能メンテナードキュメントに記載されています。

PECL 拡張機能の移行

PECL リポジトリには、まだ PIE サポートを追加していない多数の拡張機能があります。これは PECL でホストされている拡張機能のリストと、PIE サポートを追加するためのステータスです。ここに古い情報を見つけた場合は、Pull Request を提出してください。

サポート済み

以下の拡張機能はすでに PIE サポートを追加しています：

進行中

以下の拡張機能は PIE サポートを追加する取り組みが始まっています：

未開始 / 不明

以下の拡張機能は PECL に存在していますが、PIE サポートをまだ追加していないか、そのステータスが不明です。

• ahocorasick
• AOP
• ApacheAccessor
• apcu_bc
• APM
• augeas
• awscrt
• bloomy
• bsdiff
• bz2_filter
• cairo_wrapper
• cassandra
• cld
• clips
• clucene
• cmark
• componere
• couchbase
• courierauth
• crack_dll
• CUBRID
• cvsclient
• cybermut
• datadog_trace
• dazuko
• docblock
• doublemetaphone
• Druid
• ecasound
• ecma_intl
• eio
• env
• esmtp
• excimer
• expect
• fann
• framegrab
• functional
• gearman
• gender
• geoip
• gmagick
• gnupg
• graphdat
• gRPC
• handlebars
• hprose
• http_message
• ibm_db2
• ice
• idn
• igbinary
• imap
• immutable_cache
• IMS
• intercept
• ion
• ip2location
• ip2proxy
• isis
• jsmin
• json_post
• jsonc
• jsonnet
• krb5
• leveldb
• libsodium
• lua
• LuaSandbox
• lzf
• markdown
• maxminddb
• mcrypt_filter
• memoize
• meta
• mogilefs
• Molten
• Mosquitto
• mqseries
• msgpack
• mustache
• mysql_xdevapi
• mysqlnd_azure
• mysqlnd_krb
• namazu
• nsq
• oauth
• ocal
• oci8
• openal
• opencensus
• opengl
• openswoole
• PAM
• params
• parle
• pcs
• pcsc
• PDO_CUBRID
• PDO_IBM
• PDO_OCI
• PDO_SQLANYWHERE
• pdo_sqlsrv
• PDO_TAOS
• pecl_http
• perforce
• Phalcon
• php_trie
• phpy
• pinpoint_php
• PKCS11
• pledge
• pq
• propro
• protobuf
• ps
• pspell
• psr
• qqwry
• quickhash
• radius
• raphf
• rar
• ref
• request
• rnp
• rrd
• runkit7
• sandbox
• sasl
• scoutapm
• scrypt
• sdl
• sdl_image
• sdl_mixer
• sdl_ttf
• SeasClick
• SeasLog
• SeasSnowflake
• shape
• simple_kafka_client
• skywalking
• skywalking_agent
• smbclient
• solr
• spplus
• spread
• sqlsrv
• ssdeep
• ssh2
• stackdriver_debugger
• statgrab
• stem
• stomp
• svm
• svn
• swoole_serialize
• syck
• sync
• taint
• tcc
• TCLink
• tcpwrap
• tdb
• teds
• Tensor
• termbox
• TextCat
• timecop
• trace
• trader
• tvision
• ui
• uopz
• uploadprogress
• uv
• v8
• v8js
• var_representation
• varnish
• vips
• wasm
• weakreference_bc
• WinBinder
• WinCache
• xdiff
• xhprof
• xmldiff
• XMLRPCi
• xxtea
• yac
• yaconf
• Yaf
• yar
• yaz
• yp
• zephir_parser
• zeroconf
• zlib_filter
• zookeeper

廃止

以下の拡張機能は廃止されていると考えられています：

• amfext
• APC
• apd
• apn
• archive
• ares
• automap
• axis2
• bbcode
• bcompiler
• big_int
• binpack
• BLENC
• cairo
• chdb
• classkit
• coin_acceptor
• colorer
• crack
• cybercash
• cyrus
• DBDO
• dbplus
• DBus
• dbx
• dom_varimport
• drizzle
• enchant
• fam
• ffi
• FreeImage
• fribidi
• funcall
• fuse
• GDChart
• gupnp
• haru
• hidef
• html_parse
• htscanner
• huffman
• id3
• imlib2
• inclued
• ingres
• ircclient
• Judy
• kadm5
• KTaglib
• lapack
• lchash
• libevent
• maxdb
• mcve
• mdbtools
• memsession
• memtrack
• mnogosearch
• mongo
• mono
• mysqlnd_memcache
• mysqlnd_ms
• mysqlnd_ngen
• mysqlnd_qc
• mysqlnd_uh
• ncurses
• Net_Gopher
• netools
• newt
• odbtp
• oggvorbis
• opendirectory
• operator
• optimizer
• orng
• panda
• Paradox
• Parse_Tree
• parsekit
• pdflib
• PDO_4D
• PDO_IDS
• pdo_user
• PECL_Gen
• perl
• phdfs
• PHK
• POP3
• proctitle
• protocolbuffers
• pthreads
• python
• qb
• re2
• riak
• rpmreader
• rsvg
• rsync
• runkit
• sam
• scream
• sdo
• sphinx
• spidermonkey
• SPL_Types
• stats
• strict
• sundown
• swish
• tidy
• tk
• tokyo_tyrant
• txforward
• udis86
• uri_template
• Valkyrie
• vpopmail
• wbxml
• Weakref
• win32ps
• win32ps_dll
• win32std
• wxwidgets
• xcommerce
• xmlrpc
• xmms
• xmp
• xrange
• xslcache
• yami
• ZendOptimizerPlus
• zmq

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.

Supported

The following extensions have already added support for PIE:

Work in progress

The following extensions have had efforts started to add support for PIE:

Not started / Unknown

The following extensions exist on PECL, but either have not added support for PIE yet, or their status is unknown.

• ahocorasick
• AOP
• ApacheAccessor
• apcu_bc
• APM
• augeas
• awscrt
• bloomy
• bsdiff
• bz2_filter
• cairo_wrapper
• cassandra
• cld
• clips
• clucene
• cmark
• componere
• couchbase
• courierauth
• crack_dll
• CUBRID
• cvsclient
• cybermut
• datadog_trace
• dazuko
• docblock
• doublemetaphone
• Druid
• ecasound
• ecma_intl
• eio
• env
• esmtp
• excimer
• expect
• fann
• framegrab
• functional
• gearman
• gender
• geoip
• gmagick
• gnupg
• graphdat
• handlebars
• hprose
• http_message
• ibm_db2
• ice
• idn
• igbinary
• imap
• immutable_cache
• IMS
• intercept
• ion
• ip2location
• ip2proxy
• isis
• jsmin
• json_post
• jsonc
• jsonnet
• krb5
• leveldb
• libsodium
• lua
• LuaSandbox
• markdown
• maxminddb
• mcrypt_filter
• memoize
• meta
• mogilefs
• Molten
• Mosquitto
• mqseries
• msgpack
• mustache
• mysql_xdevapi
• mysqlnd_azure
• mysqlnd_krb
• namazu
• nsq
• oauth
• ocal
• oci8
• openal
• opencensus
• opengl
• openswoole
• PAM
• params
• parle
• pcs
• pcsc
• PDO_CUBRID
• PDO_IBM
• PDO_OCI
• PDO_SQLANYWHERE
• pdo_sqlsrv
• PDO_TAOS
• pecl_http
• perforce
• Phalcon
• php_trie
• phpy
• pinpoint_php
• PKCS11
• pledge
• pq
• propro
• protobuf
• ps
• pspell
• psr
• qqwry
• quickhash
• radius
• raphf
• ref
• request
• rnp
• rrd
• runkit7
• sandbox
• sasl
• scoutapm
• scrypt
• sdl
• sdl_image
• sdl_mixer
• sdl_ttf
• SeasClick
• SeasLog
• SeasSnowflake
• shape
• simple_kafka_client
• skywalking
• skywalking_agent
• smbclient
• solr
• spplus
• spread
• sqlsrv
• ssdeep
• ssh2
• stackdriver_debugger
• statgrab
• stem
• stomp
• svm
• svn
• swoole_serialize
• syck
• taint
• tcc
• TCLink
• tcpwrap
• tdb
• teds
• Tensor
• termbox
• TextCat
• timecop
• trace
• trader
• tvision
• ui
• uopz
• uploadprogress
• uv
• v8
• v8js
• var_representation
• vips
• wasm
• weakreference_bc
• WinBinder
• WinCache
• xdiff
• xhprof
• xmldiff
• XMLRPCi
• xxtea
• yac
• yaconf
• Yaf
• yar
• yaz
• yp
• zephir_parser
• zeroconf
• zlib_filter
• zookeeper

Abandoned

The following extensions are believed to be abandoned:

• amfext
• APC
• apd
• apn
• archive
• ares
• automap
• axis2
• bbcode
• bcompiler
• big_int
• binpack
• BLENC
• cairo
• chdb
• classkit
• coin_acceptor
• colorer
• crack
• cybercash
• cyrus
• DBDO
• dbplus
• DBus
• dbx
• dom_varimport
• drizzle
• enchant
• fam
• ffi
• FreeImage
• fribidi
• funcall
• fuse
• GDChart
• gupnp
• haru
• hidef
• html_parse
• htscanner
• huffman
• id3
• imlib2
• inclued
• ingres
• ircclient
• Judy
• kadm5
• KTaglib
• lapack
• lchash
• libevent
• maxdb
• mcve
• mdbtools
• memsession
• memtrack
• mnogosearch
• mongo
• mono
• mysqlnd_memcache
• mysqlnd_ms
• mysqlnd_ngen
• mysqlnd_qc
• mysqlnd_uh
• ncurses
• Net_Gopher
• netools
• newt
• odbtp
• oggvorbis
• opendirectory
• optimizer
• orng
• panda
• Paradox
• Parse_Tree
• parsekit
• pdflib
• PDO_4D
• PDO_IDS
• pdo_user
• PECL_Gen
• perl
• phdfs
• PHK
• POP3
• proctitle
• protocolbuffers
• pthreads
• python
• qb
• re2
• riak
• rpmreader
• rsvg
• rsync
• runkit
• sam
• scream
• sdo
• sphinx
• spidermonkey
• SPL_Types
• stats
• strict
• sundown
• swish
• tidy
• tk
• tokyo_tyrant
• txforward
• udis86
• uri_template
• Valkyrie
• vpopmail
• wbxml
• Weakref
• win32ps
• win32ps_dll
• win32std
• wxwidgets
• xcommerce
• xmlrpc
• xmms
• xmp
• xrange
• xslcache
• yami
• ZendOptimizerPlus
• zmq

⚠️ Warning

This translation may not be based on the latest version, please ensure you check the original English version for discrepancies.

支持的扩展

由于 Packagist 是 PIE 包的新家，完整的支持、兼容 PIE 的扩展列表可以在以下位置找到：

• https://packagist.org/extensions

添加 PIE 支持的过程在扩展维护者文档中有记录。

PECL 扩展迁移

PECL 仓库仍然有大量尚未添加 PIE 支持的扩展。这是 PECL 上托管的扩展列表，以及它们添加 PIE 支持的状态。如果您发现此处有过时的信息，请提交 Pull Request。

已支持

以下扩展已经添加了 PIE 支持：

进行中

以下扩展已开始努力添加 PIE 支持：

未开始 / 未知

以下扩展存在于 PECL 上，但尚未添加 PIE 支持，或其状态未知。

• ahocorasick
• AOP
• ApacheAccessor
• apcu_bc
• APM
• augeas
• awscrt
• bloomy
• bsdiff
• bz2_filter
• cairo_wrapper
• cassandra
• cld
• clips
• clucene
• cmark
• componere
• couchbase
• courierauth
• crack_dll
• CUBRID
• cvsclient
• cybermut
• datadog_trace
• dazuko
• docblock
• doublemetaphone
• Druid
• ecasound
• ecma_intl
• eio
• env
• esmtp
• excimer
• expect
• fann
• framegrab
• functional
• gearman
• gender
• geoip
• gmagick
• gnupg
• graphdat
• gRPC
• handlebars
• hprose
• http_message
• ibm_db2
• ice
• idn
• igbinary
• imap
• immutable_cache
• IMS
• intercept
• ion
• ip2location
• ip2proxy
• isis
• jsmin
• json_post
• jsonc
• jsonnet
• krb5
• leveldb
• libsodium
• lua
• LuaSandbox
• lzf
• markdown
• maxminddb
• mcrypt_filter
• memoize
• meta
• mogilefs
• Molten
• Mosquitto
• mqseries
• msgpack
• mustache
• mysql_xdevapi
• mysqlnd_azure
• mysqlnd_krb
• namazu
• nsq
• oauth
• ocal
• oci8
• openal
• opencensus
• opengl
• openswoole
• PAM
• params
• parle
• pcs
• pcsc
• PDO_CUBRID
• PDO_IBM
• PDO_OCI
• PDO_SQLANYWHERE
• pdo_sqlsrv
• PDO_TAOS
• pecl_http
• perforce
• Phalcon
• php_trie
• phpy
• pinpoint_php
• PKCS11
• pledge
• pq
• propro
• protobuf
• ps
• pspell
• psr
• qqwry
• quickhash
• radius
• raphf
• rar
• ref
• request
• rnp
• rrd
• runkit7
• sandbox
• sasl
• scoutapm
• scrypt
• sdl
• sdl_image
• sdl_mixer
• sdl_ttf
• SeasClick
• SeasLog
• SeasSnowflake
• shape
• simple_kafka_client
• skywalking
• skywalking_agent
• smbclient
• solr
• spplus
• spread
• sqlsrv
• ssdeep
• ssh2
• stackdriver_debugger
• statgrab
• stem
• stomp
• svm
• svn
• swoole_serialize
• syck
• sync
• taint
• tcc
• TCLink
• tcpwrap
• tdb
• teds
• Tensor
• termbox
• TextCat
• timecop
• trace
• trader
• tvision
• ui
• uopz
• uploadprogress
• uv
• v8
• v8js
• var_representation
• varnish
• vips
• wasm
• weakreference_bc
• WinBinder
• WinCache
• xdiff
• xhprof
• xmldiff
• XMLRPCi
• xxtea
• yac
• yaconf
• Yaf
• yar
• yaz
• yp
• zephir_parser
• zeroconf
• zlib_filter
• zookeeper

已废弃

以下扩展被认为已废弃：

• amfext
• APC
• apd
• apn
• archive
• ares
• automap
• axis2
• bbcode
• bcompiler
• big_int
• binpack
• BLENC
• cairo
• chdb
• classkit
• coin_acceptor
• colorer
• crack
• cybercash
• cyrus
• DBDO
• dbplus
• DBus
• dbx
• dom_varimport
• drizzle
• enchant
• fam
• ffi
• FreeImage
• fribidi
• funcall
• fuse
• GDChart
• gupnp
• haru
• hidef
• html_parse
• htscanner
• huffman
• id3
• imlib2
• inclued
• ingres
• ircclient
• Judy
• kadm5
• KTaglib
• lapack
• lchash
• libevent
• maxdb
• mcve
• mdbtools
• memsession
• memtrack
• mnogosearch
• mongo
• mono
• mysqlnd_memcache
• mysqlnd_ms
• mysqlnd_ngen
• mysqlnd_qc
• mysqlnd_uh
• ncurses
• Net_Gopher
• netools
• newt
• odbtp
• oggvorbis
• opendirectory
• operator
• optimizer
• orng
• panda
• Paradox
• Parse_Tree
• parsekit
• pdflib
• PDO_4D
• PDO_IDS
• pdo_user
• PECL_Gen
• perl
• phdfs
• PHK
• POP3
• proctitle
• protocolbuffers
• pthreads
• python
• qb
• re2
• riak
• rpmreader
• rsvg
• rsync
• runkit
• sam
• scream
• sdo
• sphinx
• spidermonkey
• SPL_Types
• stats
• strict
• sundown
• swish
• tidy
• tk
• tokyo_tyrant
• txforward
• udis86
• uri_template
• Valkyrie
• vpopmail
• wbxml
• Weakref
• win32ps
• win32ps_dll
• win32std
• wxwidgets
• xcommerce
• xmlrpc
• xmms
• xmp
• xrange
• xslcache
• yami
• ZendOptimizerPlus
• zmq

⚠️ Warning

This translation may not be based on the latest version, please ensure you check the original English version for discrepancies.

🥧 PIE (PHP 拡張機能インストーラー)

PIE とは？

PIE は PHP 拡張機能の新しいインストーラーで、最終的に PECL を置き換えることを目的としています。 PHAR として配布され、 Composer と同様に動作しますが、PHP パッケージをプロジェクトやライブラリに 取り込むのではなく、PHP 拡張機能（PHP モジュールまたは Zend 拡張機能）を PHP インストールにインストールします。

PIE の使用 - 始めるために何が必要ですか？

前提条件

PIE を実行するには PHP 8.1 以降が必要ですが、PIE は他のインストール済み PHP バージョンに 拡張機能をインストールできます。

Linux では、ビルドツールチェーンをインストールする必要があります。Debian/Ubuntu タイプの システムでは、次のようなコマンドを実行できます：

sudo apt install gcc make autoconf libtool bison re2c pkg-config php-dev

Windows では、ビルドツールチェーンをインストールする必要はありません。Windows の PHP 拡張機能は 拡張機能 DLL を含むプリコンパイル済みパッケージとして配布されるためです。

PIE のインストール

• pie.phar をダウンロードします：
  • 最新の安定版リリース
  • 最新の不安定なナイトリービルド
• gh attestation verify --owner php pie.phar で PHAR の出所を確認します
• その後、php pie.phar <command> で PIE を呼び出すことができます

インストールの詳細については、使用法 ドキュメントを参照してください。 このドキュメントでは、pie.phar を $PATH に移動したことを前提としています（例：非 Windows システムでは /usr/local/bin/pie）。

PIE を使用して単一の拡張機能をインストール

install コマンドを使用して拡張機能をインストールできます。例えば、example_pie_extension 拡張機能を インストールするには、次を実行します：

$ pie install example/example-pie-extension
このコマンドには管理者権限が必要な場合があり、パスワードの入力を求められることがあります。
実行中の PHP: 8.3.10
ターゲット PHP インストール: 8.3.10 nts、Linux/OSX/etc x86_64（/usr/bin/php8.3 から）
パッケージが見つかりました: example/example-pie-extension:1.0.1（ext-example_pie_extension を提供）
phpize 完了。
設定完了。
ビルド完了: /tmp/pie_downloader_66e0b1de73cdb6.04069773/example-example-pie-extension-769f906/modules/example_pie_extension.so
インストール完了: /usr/lib/php/20230831/example_pie_extension.so
php.ini に "extension=example_pie_extension" を追加する必要があります
$

PHP プロジェクトのすべての拡張機能をインストール

PHP プロジェクト内で、不足しているトップレベルの拡張機能をインストールできます：

$ pie install
🥧 PHP Installer for Extensions (PIE), 0.9.0, from The PHP Foundation
実行中の PHP: 8.3.19
ターゲット PHP インストール: 8.3.19 nts、Linux/OSX/etc x86_64（/usr/bin/php8.3 から）
プロジェクト your-vendor/your-project の拡張機能を確認中
requires: curl ✅ 既にインストール済み
requires: intl ✅ 既にインストール済み
requires: json ✅ 既にインストール済み
requires: example_pie_extension ⚠️  不足

以下のパッケージが適切です。どれをインストールしますか：
  [0] なし
  [1] asgrim/example-pie-extension: Example PIE extension
 > 1
   > 🥧 PHP Installer for Extensions (PIE), 0.9.0, from The PHP Foundation
   > このコマンドには管理者権限が必要な場合があり、パスワードの入力を求められることがあります。
   > 実行中の PHP: 8.3.19
   > ターゲット PHP インストール: 8.3.19 nts、Linux/OSX/etc x86_64（/usr/bin/php8.3 から）
   > パッケージが見つかりました: asgrim/example-pie-extension:2.0.2（ext-example_pie_extension を提供）
   ... (省略) ...
   > ✅ 拡張機能は /usr/bin/php8.3 で有効化され、読み込まれています

拡張機能の確認が完了しました。

PIE をサポートする拡張機能

PIE をサポートする拡張機能のリストは https://packagist.org/extensions で確認できます。

バグ、機能のアイデア、質問、ヘルプが必要など

• アイデア、質問、またはヘルプが必要な場合は、ディスカッション を使用してください。
  • 新機能を貢献する前に、まずご連絡ください - これは すでに開発中の可能性があります。PHP Foundation も積極的に これを開発しており、すでにパイプラインに新しい機能があります...
• 報告するバグがある場合は、Issues を使用してください。

拡張機能のメンテナーです - PIE サポートを追加するにはどうすればよいですか？

拡張機能のメンテナーで、拡張機能に PIE サポートを追加したい場合は、 拡張機能メンテナー を読んでください。

その他のドキュメント...

PIE の完全なドキュメントは 使用法 ドキュメントにあります。

⚠️ Warning

This translation may not be based on the latest version, please ensure you check the original English version for discrepancies.

🥧 PIE (PHP 扩展安装器)

什么是 PIE？

PIE 是一个新的 PHP 扩展安装器，旨在最终替代 PECL。 它以 PHAR 格式分发， 就像 Composer 一样，工作方式也类似，但它将 PHP 扩展（PHP 模块或 Zend 扩展） 安装到您的 PHP 安装中，而不是将 PHP 包拉入您的项目或库。

使用 PIE - 我需要什么才能开始？

先决条件

您需要 PHP 8.1 或更高版本来运行 PIE，但 PIE 可以将扩展安装到任何其他已安装的 PHP 版本。

在 Linux 上，您需要安装构建工具链。在 Debian/Ubuntu 类型的系统上，您可以运行：

sudo apt install gcc make autoconf libtool bison re2c pkg-config php-dev

在 Windows 上，您不需要安装任何构建工具链，因为 Windows 的 PHP 扩展 以预编译包的形式分发，包含扩展 DLL。

安装 PIE

• 下载 pie.phar，可以通过以下方式：
  • 最新稳定版本
  • 最新不稳定夜间构建版本
• 使用 gh attestation verify --owner php pie.phar 验证 PHAR 的来源
• 然后您可以使用 php pie.phar <command> 调用 PIE

更多安装详情可以在 使用文档 中找到。 本文档假设您已将 pie.phar 移动到您的 $PATH 中，例如在非 Windows 系统上为 /usr/local/bin/pie。

使用 PIE 安装单个扩展

您可以使用 install 命令安装扩展。例如，要安装 example_pie_extension 扩展，您可以运行：

$ pie install example/example-pie-extension
此命令可能需要提升权限，并可能提示您输入密码。
您正在运行 PHP 8.3.10
目标 PHP 安装：8.3.10 nts，在 Linux/OSX/etc x86_64 上（来自 /usr/bin/php8.3）
找到包：example/example-pie-extension:1.0.1，提供 ext-example_pie_extension
phpize 完成。
配置完成。
构建完成：/tmp/pie_downloader_66e0b1de73cdb6.04069773/example-example-pie-extension-769f906/modules/example_pie_extension.so
安装完成：/usr/lib/php/20230831/example_pie_extension.so
您现在必须在 php.ini 中添加 "extension=example_pie_extension"
$

为 PHP 项目安装所有扩展

在您的 PHP 项目中，您可以安装任何缺失的顶级扩展：

$ pie install
🥧 PHP Installer for Extensions (PIE), 0.9.0, from The PHP Foundation
您正在运行 PHP 8.3.19
目标 PHP 安装：8.3.19 nts，在 Linux/OSX/etc x86_64 上（来自 /usr/bin/php8.3）
检查您的项目 your-vendor/your-project 的扩展
requires: curl ✅ 已安装
requires: intl ✅ 已安装
requires: json ✅ 已安装
requires: example_pie_extension ⚠️  缺失

以下包可能合适，您想安装哪个：
  [0] 无
  [1] asgrim/example-pie-extension: Example PIE extension
 > 1
   > 🥧 PHP Installer for Extensions (PIE), 0.9.0, from The PHP Foundation
   > 此命令可能需要提升权限，并可能提示您输入密码。
   > 您正在运行 PHP 8.3.19
   > 目标 PHP 安装：8.3.19 nts，在 Linux/OSX/etc x86_64 上（来自 /usr/bin/php8.3）
   > 找到包：asgrim/example-pie-extension:2.0.2，提供 ext-example_pie_extension
   ... (省略) ...
   > ✅ 扩展已在 /usr/bin/php8.3 中启用并加载

完成扩展检查。

支持 PIE 的扩展

支持 PIE 的扩展列表可以在 https://packagist.org/extensions 上找到。

我有错误、功能想法、问题、需要帮助等。

• 如果您有想法、问题或需要帮助，请使用 讨论区。
  • 在贡献新功能之前，请先与我们联系 - 这可能是 我们已经正在开发的内容，因为 PHP Foundation 也在积极 开发这个项目，并且已经有一些新功能正在开发中...
• 如果您有错误要报告，请使用 问题。

我是扩展维护者 - 如何添加 PIE 支持？

如果您是想要为您的扩展添加 PIE 支持的扩展维护者， 请阅读 扩展维护者文档。

更多文档...

PIE 的完整文档可以在 使用文档 中找到。