wiediiregistry/php-extension-installer repository overview

⁠Wiedii PHP Extension Installer

A PHP extension is an add-on that gives PHP a new ability, such as talking to a Redis server or resizing images. Most extensions have to be compiled (turned from source code into a file PHP can load) and need the right system libraries around them.

install-php-extensions is one command that does all of that. You name the extensions you want, it installs each one and checks that PHP can load it. This image carries the command, its catalog of tested extensions and PIE (the PHP Foundation's official extension installer). It works on the official php images and on the wiediiregistry/php images, on Debian and on Alpine. Every tag works on Intel/AMD (linux/amd64) and on Apple Silicon or ARM servers (linux/arm64).

What it gives you:

• Pinned sources. Each extension in the catalog is built from an exact version and commit that was checked, so the same command gives the same result every time.
• No pecl. pecl is PHP's old extension tool. It is deprecated and its outages broke builds, so this command never uses it.
• The same name and usage as mlocati's installer, the community tool many PHP projects use, so a project changes one line.
• System packages handled for you. Build tools are installed for the build and removed afterwards; the libraries an extension uses at run time stay.

⁠Quick start

The image is FROM scratch: it has no shell and nothing to run on its own. You lend it to one RUN step of your Dockerfile with a bind mount (a way to use files from another image without copying them into yours), so nothing from it stays in your final image:

FROM wiediiregistry/php:8.5.12-laravel-debian

USER root
RUN --mount=type=bind,from=wiediiregistry/php-extension-installer:X.Y.Z@sha256:<digest>,source=/usr,target=/opt/wiedii-ext \
    sh /opt/wiedii-ext/bin/install-php-extensions exif pcov
USER app

The same line works on the official php images (php:8.5-fpm, php:8.5-cli-alpine). Only the FROM line changes. The command must run as root, so switch to root before the RUN and back to your normal user after it.

Replace X.Y.Z with a release from the Tags tab of this page ("Tags and versions" below explains which one to pick). A digest is the SHA256 fingerprint of an image's exact content. Pinning it means you get exactly the same bytes tomorrow. Replace <digest> with the output of this command: copy the first Digest: line, the one at the top.

docker buildx imagetools inspect wiediiregistry/php-extension-installer:X.Y.Z

The output also lists linux/amd64 and linux/arm64. If it shows only one, or answers not found, the tag is not complete or does not exist; pick another from the Tags tab of this page.

⁠Tags and versions

Releases are named X.Y.Z, three numbers such as 1.4.2. Three tags exist for each release:

Pin the full X.Y.Z together with the digest, and let Renovate (a bot that proposes dependency updates) offer the next release. A change of the first number means something can break: the command line, the image layout or the catalog format changed, so read the release notes before you accept it.

⁠Options

Put options before the extension names.

A name such as redis-6.3.0 asks for one specific version (see below for what that means).

To see the catalog from your own machine, build this one-line project with docker build --progress=plain --no-cache .; the list appears in the output:

FROM php:8.5-cli
RUN --mount=type=bind,from=wiediiregistry/php-extension-installer:X.Y.Z@sha256:<digest>,source=/usr,target=/opt/wiedii-ext \
    sh /opt/wiedii-ext/bin/install-php-extensions --list

⁠How it picks the source

For each extension you ask for, the command tries these sources in order and stops at the first one that works:

1. Already loaded: nothing to do.
2. PHP's own source, for extensions that come with PHP, such as gd or bcmath.
3. PIE, which builds the extension from a pinned source commit.
4. A pinned source build, for extensions that PIE cannot install.

"Pinned" means the exact version and commit are fixed and checked. At the end every extension you requested must load, or the command stops with an error.

⁠Names outside the catalog

If you ask for a name that is not in the catalog, the command does not give up. It looks the name up on Packagist⁠, the official index of PIE⁠ packages, and installs the latest stable release it finds. The same happens when you ask for a specific version of any extension, such as redis-6.3.0: that version comes from Packagist and is not checked against our pin. Some extensions cannot take a version: a built-in PHP extension such as gd has no version of its own, and an extension built only from its pinned source has no other version to fetch. For those, install-php-extensions gd-1.2.3 stops with an error that says so; ask for the plain name instead.

• Why it works this way: PIE is the PHP Foundation's official extension installer and Packagist is its official index, so an extension we do not know yet comes from the official source, not from an arbitrary download.
• The trade-off: nothing fixes the exact version or commit, so the build is not reproducible: next month the same command can install a newer release. The command prints a warning every time. Such an extension also gets no system packages, so one that needs libraries stops with a clear message.
• How to make it reproducible: ask the maintainers to add the extension to the catalog with a pin. From then on it is built from a pinned commit like the others.

This is a deliberate exception to the rule that everything is pinned, approved by the tech lead.

⁠Where it works and its limits

⁠GitHub rate limits

PIE downloads from GitHub, which limits anonymous requests. If a build hits the limit, give it a GitHub token as a BuildKit secret (a value that exists only while one build step runs). Never pass it as a build argument: arguments stay readable in the image history. Add --mount=type=secret,id=composer_auth to the RUN line above, put the token in a file, and pass the file to the build:

echo '{"github-oauth": {"github.com": "<token>"}}' > auth.json
docker build --secret id=composer_auth,src=auth.json .

Replace <token> with a GitHub token you created, and never commit auth.json. The command also reads COMPOSER_AUTH from the environment. This image holds no token of its own.

⁠Troubleshooting

⁠Migrating from mlocati's installer

install-php-extensions keeps the same name and the same install-php-extensions <ext> … usage as mlocati/docker-php-extension-installer⁠, which installs most extensions with pecl. Most project Dockerfiles only change the mount:

-RUN --mount=type=bind,from=ghcr.io/mlocati/php-extension-installer:2.12.3,source=/usr/bin/install-php-extensions,target=/usr/local/bin/install-php-extensions \
-    install-php-extensions pgsql
+RUN --mount=type=bind,from=wiediiregistry/php-extension-installer:X.Y.Z@sha256:<digest>,source=/usr,target=/opt/wiedii-ext \
+    sh /opt/wiedii-ext/bin/install-php-extensions pgsql

⁠More help

The project repository has the full guide (including the extension table, one row per extension) and the maintainer documentation, in English and Spanish, in its docs/ folder. It is internal to Wiedii, so this page repeats everything a visitor needs. General references: Docker documentation⁠, PHP manual⁠, PIE⁠, Packagist⁠.

⁠License

UNLICENSED. Internal Wiedii use only. The catalog data ported from mlocati's installer is MIT-licensed.