php/archived-pie
1
0
Fork 0
mirror of https://github.com/php/pie.git synced 2026-03-23 23:12:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

435: documentation improvements for 1.4.0 features

Browse Source
This commit is contained in:
James Titcumb
2026-03-06 09:23:36 +00:00
parent 3fb0c2443b
commit e7053cb3e6
3 changed files with 94 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
README.md
View File

@@ -2,11 +2,12 @@
## What is PIE?
PIE is a new installer for PHP extensions, intended to eventually replace PECL.
It is distributed as a [PHAR](https://www.php.net/manual/en/intro.phar.php),
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.
PIE is the official installer for PHP extensions, which replaces
[PECL](https://pecl.php.net/) (which is now deprecated). PIE is distributed as a
[PHAR](https://www.php.net/manual/en/intro.phar.php), 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?
@@ -15,12 +16,8 @@ than pulling PHP packages into your project or library.
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, you will need a build toolchain installed. On Debian/Ubuntu type
systems, you could run something like:
```shell
sudo apt install gcc make autoconf libtool bison re2c pkg-config php-dev
```
On Linux/OSX, if any build tools needed are missing, PIE will ask if you would
like to automatically install them first (this is a new feature in 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
@@ -38,7 +35,9 @@ Further installation details can be found in the [usage](./docs/usage.md) 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.
## Installing a single extension using 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:
@@ -57,7 +56,7 @@ You must now add "extension=example_pie_extension" to your php.ini
$
```
## Installing all extensions for a PHP project
### Installing all extensions for a PHP project
When in your PHP project, you can install any missing top-level extensions:
@@ -87,6 +86,12 @@ The following packages may be suitable, which would you like to install:
Finished checking extensions.
```
> [!TIP]
> If you are running PIE in a non-interactive shell (for example, CI, a
> container), pass the `--allow-non-interactive-project-install` flag to run
> this command. It may still fail if more than one PIE package provides a
> particular extension.
## Extensions that support PIE
A list of extensions that support PIE can be found on
@@ -105,6 +110,6 @@ A list of extensions that support PIE can be found on
If you are an extension maintainer wanting to add PIE support to your extension,
please read [extension-maintainers](./docs/extension-maintainers.md).
## More documentation...
# More documentation...
The full documentation for PIE can be found in [usage](./docs/usage.md) docs.

54
docs/extension-maintainers.md
View File

@@ -345,11 +345,16 @@ The list of accepted OS families: "windows", "bsd", "darwin", "solaris", "linux"
#### Extension dependencies
Extension authors may define some dependencies in `require`, but practically,
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. Dependencies on other extensions may be
defined, for example `ext-json`. However, dependencies on a regular PHP package
(such as `monolog/monolog`) SHOULD NOT be specified in your `require` section.
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
@@ -360,6 +365,47 @@ 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](https://github.com/php/pie/discussions)
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](https://github.com/php/pie/issues).
| Library | Checked by PIE | Auto-installs in |
|---------------|----------------|--------------------|
| lib-curl | ✅ | apt, apk, dnf, yum |
| lib-enchant | ✅ | ❌ |
| lib-enchant-2 | ✅ | ❌ |
| lib-sodium | ✅ | apt, apk, dnf, yum |
| lib-ffi | ✅ | apt, apk, dnf, yum |
| lib-xslt | ✅ | apt, apk, dnf, yum |
| lib-zip | ✅ | apt, apk, dnf, yum |
| lib-png | ✅ | ❌ |
| lib-avif | ✅ | ❌ |
| lib-webp | ✅ | ❌ |
| lib-jpeg | ✅ | apt, apk, dnf, yum |
| lib-xpm | ✅ | ❌ |
| lib-freetype2 | ✅ | ❌ |
| lib-gdlib | ✅ | ❌ |
| lib-gmp | ✅ | ❌ |
| lib-sasl | ✅ | ❌ |
| lib-onig | ✅ | ❌ |
| lib-odbc | ✅ | ❌ |
| lib-capstone | ✅ | ❌ |
| lib-pcre | ✅ | ❌ |
| lib-edit | ✅ | ❌ |
| lib-snmp | ✅ | ❌ |
| lib-argon2 | ✅ | ❌ |
| lib-uriparser | ✅ | ❌ |
| lib-exslt | ✅ | ❌ |
#### Checking the extension will work
First up, you can use `composer validate` to check your `composer.json` is

25
docs/usage.md
View File

@@ -281,6 +281,31 @@ 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
```
### 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