charm / composer-pie
PIE (the PHP Foundation's extension installer), per project: install PHP extensions into vendor/ and run PHP with them loaded.
Requires
- php: ^8.3
Requires (Dev)
- phpunit/phpunit: ^11.0 || ^12.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Install PHP extensions into your project instead of into the system PHP. No root, no php.ini changes, and each project gets its own extensions.
composer require charm/composer-pie
vendor/bin/pie install xdebug/xdebug
vendor/bin/php your-script.php # runs with xdebug loaded
It uses PIE, the PHP Foundation's extension installer, to find, download and build the extension. composer-pie is an unofficial companion to PIE, not part of it.
What it is for
composer-pie is for PHP that runs from the command line: long-running servers and workers, scripts, tests and tools.
- Application servers such as Swerve, and event-loop libraries such as phasync, ReactPHP or AMPHP.
- Workers and scripts: queue workers, cron jobs, CLI tools, test suites.
It cannot add extensions to php-fpm or Apache's mod_php: those start PHP on their own, not through your project. For a web application that needs an extension the system lacks, serve it with Swerve instead. Swerve runs WordPress, Laravel, Symfony, Drupal and other php-fpm applications unchanged, and its workers load the project's extensions:
composer require charm/composer-pie phasync/swerve
vendor/bin/pie install php-ds/ext-ds
composer exec -- swerve -S public --http=0.0.0.0:8080
(Verified with WordPress 7.1 on Swerve using an extension that only the project has.)
Running your code with the project's extensions
Start PHP through the project, in any of these ways:
| Command | |
|---|---|
vendor/bin/php script.php |
runs PHP with the project's extensions |
composer exec -- php script.php |
the same |
composer exec -- phpunit |
any tool installed in vendor/bin |
"scripts": {"test": "php vendor/bin/phpunit"} |
php in Composer scripts |
Programs started from there inherit the extensions: worker processes, proc_open(PHP_BINARY, ...), child scripts.
Composer's launchers in vendor/bin start the system PHP, so a tool run directly as vendor/bin/phpunit does not
see the project's extensions. Run it with composer exec -- phpunit or vendor/bin/php vendor/bin/phpunit.
Installing extensions: your situation
vendor/bin/pie install <package> takes any PIE package, e.g.
xdebug/xdebug, apcu/apcu, phpredis/phpredis, php-ds/ext-ds. It uses a pre-built binary when the extension
publishes one for your platform, and otherwise builds it from source. What you need depends on your system:
Your system can build PHP extensions
You have a C compiler, make, autoconf and the PHP development files (php-dev on Debian and Ubuntu,
php-devel on Fedora and RHEL). Nothing more to do:
vendor/bin/pie install xdebug/xdebug
The extension publishes pre-built binaries
Then no build tools are needed at all; vendor/bin/pie install downloads the binary for your PHP version and
platform.
Linux without build tools
composer-pie can download a C compiler and the other build tools for you, into your user's cache
(~/.cache/composer-pie/toolchain). Nothing is installed system-wide, and every project shares it. It is a one-time
download of about 170 MB.
vendor/bin/pie install xdebug/xdebug --install-toolchain
Run interactively, it asks before downloading. In CI or a Docker build, set COMPOSER_PIE_TOOLCHAIN=1 instead. This
works on Linux with glibc (Debian, Ubuntu, Fedora, RHEL and most others) on x86_64; arm64 is set up but not yet tested.
Alpine Linux or macOS without build tools
composer-pie tells you what to install:
apk add build-base autoconf php83-dev # Alpine (match your PHP version) xcode-select --install && brew install autoconf # macOS
The extension needs a system library
Some extensions use a library from your system: imagick needs ImageMagick, rdkafka needs librdkafka. Install the
library's development package (e.g. apt install libmagickwand-dev), then vendor/bin/pie install as usual.
The extension is already installed system-wide
Nothing to do. composer-pie notices and leaves it to the system PHP.
Declaring the extensions your project needs
List them in composer.json as usual, and install them all with one command:
{
"require": { "ext-apcu": "*" },
"require-dev": { "ext-xdebug": "*" }
}
vendor/bin/pie install # installs every missing ext-* requirement vendor/bin/pie install --no-dev # production: skip require-dev
If several packages provide an extension, PIE asks which one to use; pass --select ext=vendor/package once and
composer-pie remembers the choice in composer.json.
After an install, composer-pie also records the extension in composer.json (config.platform), so Composer
accepts packages that require it. If you have a composer.lock, run composer update --lock once after the first
install.
To remove an extension from the project: vendor/bin/pie uninstall xdebug/xdebug.
How it works
vendor/bin/pieruns the real PIE (a pinned, checksum-verified release) with the project as its target: the extension goes tovendor/php-ext/, and PIE's own records stay there too. PIE is never allowed to edit the systemphp.inior to use sudo.- composer-pie then writes an ini file for the extension in
vendor/php-ext/conf.d/, one directory per PHP binary, so a project used with PHP 8.4 and 8.5 keeps a build for each. vendor/bin/phpstarts your real PHP with that directory added toPHP_INI_SCAN_DIR. The system's own ini files still load, and programs it starts inherit the setting.- When
composer.jsonorcomposer.lockchanged since the lastvendor/bin/pie install,vendor/bin/phpprints a one-line reminder to run it again. - The build toolchain comes from conda-forge (gcc, make, autoconf), installed with micromamba from pinned, checksum-verified lock files. If your PHP has no development files, composer-pie builds them from the matching php-src release.
Limits
- Command-line PHP only; not php-fpm or Apache (see above).
- Linux and macOS. Windows is not supported yet.
vendor/bin/pie showandvendor/bin/pie upgradedo not understand project installs yet; to upgrade, runvendor/bin/pie install <package>again.
Development
composer install vendor/bin/phpunit # unit tests vendor/bin/phpunit --group integration # real installs: needs network and a compiler, a few minutes
License
MIT. PIE is BSD-3-Clause, by the PHP Foundation.