PIE remplace PECL : migrer vos Dockerfiles PHP, concrètement

Votre Dockerfile contient probablement un pecl install redis apcu écrit il y a des années et jamais relu. Il fonctionne encore, et c’est bien le piège : le RFC qui adopte PIE et déprécie PECL est accepté, et pecl.php.net l’affiche en page d’accueil. Voici comment migrer sans casser vos builds — avec des Dockerfiles construits et vérifiés sur PHP 8.5.11 et PIE 1.5.2 — et ce que valent encore docker-php-ext-install et install-php-extensions.

PECL est déprécié : ce qui est acté, ce qui ne l’est pas

PECL est officiellement déprécié, mais aucune date de retrait n’est fixée, et PIE est son remplaçant officiel. Le RFC « Recommend PIE and deprecate PECL » a le statut Accepted depuis la clôture du vote, le 20 septembre 2025. Dans les faits, rien n’est coupé : la commande pecl est toujours présente dans l’image officielle php:8.5-cli. Déprécié ne veut pas dire cassé. Mais un outil déprécié ne reçoit plus d’évolutions, et chaque pecl install ajouté aujourd’hui est de la dette créée volontairement.

Le moment est bien choisi pour s’en occuper : une montée de version de PHP impose de toute façon de recompiler les extensions. Si vous préparez la sortie de PHP 8.2, notre checklist de migration vers PHP 8.5 et 8.6 donne le calendrier ; basculer sur PIE peut se faire dans le même chantier.

PIE, c’est quoi ?

PIE (PHP Installer for Extensions) est l’installeur officiel d’extensions PHP, publié sous l’organisation php sur GitHub. Il ne passe plus par le registre PECL : il installe des paquets Packagist de type php-ext. Versions, contraintes et découverte passent donc par le même écosystème que Composer. La version courante est la 1.5.2 (8 octobre). La 1.5.0 a apporté pie search, pie upgrade, l’installation de plusieurs extensions en une commande et des attestations SBOM sur les releases de PIE. PIE est un PHAR qui exige PHP 8.1 ou plus pour s’exécuter.

Premier point qui surprend : le nom du paquet n’est pas celui de l’extension. Vérifiés sur Packagist, tous de type php-ext :

• pecl install redis devient pie install phpredis/phpredis (6.3.0 au moment du test) ;
• pecl install apcu devient pie install apcu/apcu (5.1.28) ;
• pecl install xdebug devient pie install xdebug/xdebug (3.5.3 ; PIE choisit la stable et ignore la 3.6.0alpha1 publiée).

Les commandes à connaître, toutes vérifiées sur la 1.5.2 :

# Trouver le paquet qui fournit une extension
pie search redis
# -> phpredis/phpredis (provides extension: redis)

# Voir version, compatibilité et options de compilation
pie info phpredis/phpredis
# -> --enable-redis-igbinary, --enable-redis-lz4, --enable-redis-zstd…

# Installer, avec contrainte de version façon Composer
pie install xdebug/xdebug:^3.4

# Passer une option de compilation (au lieu des questions interactives de pecl)
pie install phpredis/phpredis --enable-redis-igbinary

# Lister et mettre à jour les extensions gérées par PIE
pie show
pie upgrade

Une précision sur la supply chain : l’attestation SBOM concerne les releases de PIE lui-même, vérifiables avec gh attestation verify --owner php pie.phar. PIE ne génère pas de SBOM de vos extensions. Pour le reste de la chaîne, notre checklist supply chain PHP 2026 s’applique aussi aux paquets php-ext, puisqu’ils passent par Packagist.

Le Dockerfile PIE qui fonctionne

L’image ghcr.io/php/pie ne contient pas de runtime PHP, seulement le binaire. La documentation officielle ne le copie pas : elle le monte le temps d’un RUN, avec --mount=type=bind. PIE n’existe donc pas dans l’image finale, ce qui évite d’y laisser un outil de build. Ce montage exige BuildKit.

# syntax=docker/dockerfile:1
FROM php:8.5-fpm AS base

# PIE monté uniquement le temps du RUN : absent de l’image finale.
# unzip est indispensable ; $PHPIZE_DEPS est fourni par l’image officielle.
RUN --mount=type=bind,from=ghcr.io/php/pie:1.5-bin,source=/pie,target=/usr/local/bin/pie \
    set -eux; \
    apt-get update; \
    apt-get install -y --no-install-recommends unzip $PHPIZE_DEPS; \
    pie install --no-cache phpredis/phpredis apcu/apcu; \
    apt-get purge -y --auto-remove -o APT::AutoRemove::RecommendsImportant=false $PHPIZE_DEPS; \
    rm -rf /var/lib/apt/lists/*

FROM base AS dev
RUN --mount=type=bind,from=ghcr.io/php/pie:1.5-bin,source=/pie,target=/usr/local/bin/pie \
    set -eux; \
    apt-get update; \
    apt-get install -y --no-install-recommends unzip $PHPIZE_DEPS; \
    pie install --no-cache xdebug/xdebug; \
    apt-get purge -y --auto-remove -o APT::AutoRemove::RecommendsImportant=false $PHPIZE_DEPS; \
    rm -rf /var/lib/apt/lists/*

FROM base AS prod
# redis + apcu seulement : jamais Xdebug en production

Résultat mesuré sur l’image de base : php -m liste apcu et redis, php --ri redis affiche la version 6.3.0, et le stage dev ajoute Xdebug 3.5.3. PIE écrit lui-même les fichiers INI dans conf.d — extension=redis, extension=apcu, et surtout zend_extension=xdebug avec la bonne directive. Plus besoin de docker-php-ext-enable. Le stage multi-cible s’insère naturellement dans un Dockerfile PHP de production multi-stage, non-root et scanné par Trivy.

Avant/après : migrer pecl install vers pie install

# AVANT (PECL, déprécié)
RUN set -eux; \
    apt-get update; apt-get install -y --no-install-recommends $PHPIZE_DEPS; \
    pecl install redis apcu; \
    docker-php-ext-enable redis apcu; \
    apt-get purge -y --auto-remove -o APT::AutoRemove::RecommendsImportant=false $PHPIZE_DEPS; \
    rm -rf /var/lib/apt/lists/* /tmp/pear

# APRÈS (PIE)
RUN --mount=type=bind,from=ghcr.io/php/pie:1.5-bin,source=/pie,target=/usr/local/bin/pie \
    set -eux; \
    apt-get update; apt-get install -y --no-install-recommends unzip $PHPIZE_DEPS; \
    pie install --no-cache phpredis/phpredis apcu/apcu; \
    apt-get purge -y --auto-remove -o APT::AutoRemove::RecommendsImportant=false $PHPIZE_DEPS; \
    rm -rf /var/lib/apt/lists/*

• Le nom change : vendor/package au lieu du nom court.
• docker-php-ext-enable disparaît : PIE active l’extension lui-même.
• unzip devient obligatoire : PIE télécharge des archives.
• --no-cache remplace le nettoyage de /tmp/pear.

Nous avons construit les deux versions côte à côte : mêmes versions finales (redis 6.3.0, apcu 5.1.28), même sortie de php -m, même taille d’image à un mégaoctet près. La migration ne fait gagner ni place ni temps de build de façon significative. Son intérêt est ailleurs : la pérennité, l’épinglage de version explicite et la traçabilité par Packagist. Pour des builds reproductibles, épinglez : pie install phpredis/phpredis:6.3.0.

Les pièges rencontrés en vrai

• Sans unzip, échec immédiat : The zip extension and unzip/7z commands are both missing, skipping. PIE le signale d’ailleurs en amont, dans sa liste d’outils de build manquants.
• L’avertissement libtool n’est pas bloquant pour redis, apcu et Xdebug : PIE suggère apt-get install libtool, mais les trois builds ont abouti sans. D’autres extensions peuvent en avoir besoin ; ajoutez-le si la compilation échoue.
• OPcache est intégré depuis PHP 8.5 : php -m liste déjà Zend OPcache. Un docker-php-ext-install opcache fait échouer le build (cp: cannot stat 'modules/*'). Supprimez la ligne, ou rendez-la conditionnelle si vous construisez plusieurs versions de PHP. Configurez OPcache par INI : opcache.enable_cli reste à Off par défaut.
• BuildKit est requis pour le montage : mettez # syntax=docker/dockerfile:1 en tête et vérifiez que votre CI n’utilise pas l’ancien builder.
• Épinglez l’image PIE : le tag bin suit la dernière version. 1.5-bin et 1.5.2-bin existent ; en production, un digest est encore mieux.
• Pas de dépendances système automatiques : pour redis avec zstd ou lz4, installez libzstd-dev ou liblz4-dev et passez l’option correspondante. Gardez les bibliothèques d’exécution, pas les paquets -dev, dans l’image finale.

docker-php-ext-install, install-php-extensions ou PIE ?

• docker-php-ext-install compile les extensions du cœur fournies avec les sources de l’image officielle : pdo_mysql, intl, zip, gd, bcmath… Il ne sait pas télécharger une extension tierce et reste l’outil pour le cœur.
• PIE installe les extensions tierces depuis Packagist, avec contraintes de version et activation automatique. C’est le choix « standard officiel, explicite, sans script tiers ».
• install-php-extensions (mlocati) reste le confort multi-extension : il installe aussi les paquets système et les nettoie. Son README ne mentionne pas PIE. Pour une équipe qui ne veut pas gérer de dépendances système, il garde sa pertinence.

La règle de décision tient en trois lignes : extension du cœur, docker-php-ext-install ; extension tierce avec outils officiels et versions épinglées, PIE ; beaucoup d’extensions à dépendances système et peu d’envie de les gérer, install-php-extensions. Dans aucun cas pecl install n’a encore sa place dans un Dockerfile neuf.

Checklist de migration

• Inventorier : grep -rn "pecl install" . sur les Dockerfiles, images de CI et scripts de provisionnement.
• Associer chaque extension à son paquet avec pie search, et vérifier qu’il est bien de type php-ext ; sinon, garder une autre voie pour cette extension.
• Supprimer docker-php-ext-install opcache à partir de PHP 8.5.
• Ajouter unzip, monter ghcr.io/php/pie:1.5-bin, utiliser --no-cache et épingler les versions.
• Ajouter un test de build : php -m | grep -E "redis|apcu" et php --ri redis.
• Isoler Xdebug dans un stage dev, jamais en production.

À retenir : PECL est déprécié sans date de retrait, pie install vendor/package le remplace, et l’image PIE se monte en build plutôt que de se copier. PIE est prêt pour les extensions courantes d’une application Symfony et donne exactement le même résultat que PECL. Migrez au fil de l’eau, en commençant par le stage de développement, plutôt qu’en un grand chantier.

Passer de PECL à PIE se fait en un après-midi sur une image. Le répéter sur tout un parc de projets, et le tenir à jour à chaque version de PHP, est une autre affaire. C’est ce que couvre notre maintenance applicative : versions de PHP, extensions et dépendances suivies pour vous, pour que ces chantiers de fond n’attendent pas la prochaine panne de build.

Écrit par

Flavien Métivier

Expert PHP/Symfony indépendant depuis 2014, ancien CTO de Kartable et d'Extrabat. Plus de 80 projets menés, de l'audit à la migration.

Mon parcours