title | order |
---|---|
Using PIE |
2 |
- Download
pie.phar
from the latest releases - Validate the signature in
pie.phar.asc
- 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 withpie <command>
- If you copy PIE into your
This documentation assumes you have moved pie.phar
into your $PATH
, e.g.
/usr/local/bin/pie
on non-Windows systems.
Note that this does not verify any signatures, and you assume the risks in
running this, but this will put PIE into /usr/local/bin/pie
on a non-Windows
system:
sudo curl -L --output /usr/local/bin/pie https://github.com/php/pie/releases/latest/download/pie.phar && sudo chmod +x /usr/local/bin/pie
Running PIE requires PHP 8.1 or newer. However, you may still use PIE to install an extension for an older version of PHP.
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.
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.3.6\php.exe C:\pie.phar install --with-php-path=C:\php-8.1.7\php.exe example/example-pie-extension
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 with1.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 with2.3.0
and above (for example,2.3.0-beta.3
).dev-main
will install the latest commit on themain
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 commit07f454ad797c30651be8356466685b15331f72ff
would be installed. This would not work with Windows, as there is no release with Windows binaries.
If no version-constraint
is given, try to install any compatible latest and
stable version. PIE will always prefer stable versions.
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
At the moment, PIE does not configure the INI file, although this improvement
is planned soon. In the meantime, you must enable the extension after installing
by adding a line such as extension=foo
to your php.ini
.