PHP

PHP 8.6 ya no incluye PECL en Docker. El reemplazo es PIE: cambia pecl install redis por pie install phpredis/phpredis.

Lo que ya cambió y lo que aún se debate

Conviene separar dos hechos que suelen mezclarse. El primero es real y verificable: el pull request docker-library/php#1654 retiró PECL de las imágenes oficiales de PHP 8.6. Si tu FROM php:8.6-cli ejecuta pecl install, el build falla por comando no encontrado, sin importar lo que diga el calendario de la RFC.

El segundo es una propuesta. La RFC Sunset PECL, publicada el 5 de noviembre de 2026 y todavía en discusión, propone un banner el 4 de enero de 2027, pecl.php.net en solo lectura el 30 de junio de 2027, apagones breves progresivos y el cierre definitivo el 31 de diciembre de 2027. Son fechas propuestas, no un cronograma aprobado: úsalas para planear, no como una fecha de corte confirmada.

Lo que sí estaba decidido antes es la dirección. La propia RFC recuerda que en 2025 se aprobó adoptar PIE y deprecar PECL; esta nueva propuesta solo viene a fijar el calendario. En la práctica, esperar el resultado de la votación no compra nada: la migración es de comandos y de modelo mental, no de paciencia.

Qué reemplaza a cada comando de PECL

El cambio de fondo es este: PECL trabajaba con nombres de extensión y canales; PIE resuelve paquetes Composer vendor/package desde packagist.org/extensions, con restricciones de versión como las de composer require. Por eso pecl install redis no se convierte en pie install redis, sino en pie install phpredis/phpredis. Según el repositorio oficial de PIE, la correspondencia que importa en Dockerfiles y pipelines es esta:

  • pecl install xdebug → pie install xdebug/xdebug.
  • pecl upgrade xdebug → pie install xdebug/xdebug, que vuelve a resolver la versión compatible.
  • pecl upgrade-all → pie upgrade, que respeta la restricción con que se instaló cada paquete.
  • pecl list → pie show.
  • pecl search … → pie search …, disponible desde PIE 1.5.
  • pecl info xdebug → pie info xdebug/xdebug.
  • pecl download xdebug y pecl bundle xdebug → pie download xdebug/xdebug.
  • pecl build xdebug → pie build xdebug/xdebug.
  • pecl channel-discover → pie repository:add vcs https://....

Varios comandos no tienen equivalente: los channel-*, los config-* y pecl uninstall. No los sustituyas por un invento. Los canales desaparecen porque el catálogo pasa a ser Packagist, y la configuración vive en pie.json y pie.lock. Si tu script depende de pecl config-set, ahí hay que rediseñar, no solo cambiar una palabra.

Las restricciones de versión usan la sintaxis de Composer: pie install "xdebug/xdebug:^3.4.3 || 3.4.1" instala una versión dentro de ese rango y la deja registrada. Fijar la rama minor en lugar de aceptar "la última" es una de las ganadas silenciosas de este cambio.

Instalar PIE en el servidor o en la imagen

La vía PHAR, recomendada

El PHAR necesita PHP 8.1 o superior para ejecutarse, más la extensión zip o git para bajar el código y las herramientas de compilación autoconf, automake, libtool, m4, make, gcc y phpize/php-config. En Debian o Ubuntu:

sudo apt-get install git unzip autoconf automake libtool m4 make gcc

La instalación con verificación de procedencia:

curl -fL --output /tmp/pie.phar https://github.com/php/pie/releases/latest/download/pie.phar \
&& gh attestation verify --owner php /tmp/pie.phar \
&& sudo mv /tmp/pie.phar /usr/local/bin/pie \
&& sudo chmod +x /usr/local/bin/pie

Con pie -V confirmas la versión y con pie install xdebug/xdebug instalas y habilitas la extensión. Si tu política no admite gh, puedes invocar el PHAR con php pie.phar install xdebug/xdebug, aunque pierdes la verificación de origen.

Desde PIE 1.4.0 el instalador detecta herramientas faltantes y ofrece instalarlas de forma interactiva. En un pipeline no interactivo eso no sucede: pasa --auto-install-build-tools y --auto-install-system-dependencies, o comprueba antes con pie check-build-tools, disponible desde 1.5.0.

El ejecutable own-PHP

Cuando el PHP disponible es anterior a 8.1 o no hay toolchain, está el binario autocontenido basado en Static PHP, incluido desde 1.4.0. No requiere PHP instalado para correr y trae el PHAR dentro:

curl -fL -o /tmp/pie-Linux-X64 https://github.com/php/pie/releases/latest/download/pie-Linux-X64
gh attestation verify --owner php /tmp/pie-Linux-X64
chmod +x /tmp/pie-Linux-X64
/tmp/pie-Linux-X64 --version

Que el PHAR corra en PHP 8.1+ no limita la versión de destino. Con pie install --with-php-config=/usr/bin/php-config7.2 phpredis/phpredis instalas para otro PHP; en Windows el equivalente es --with-php-path.

El Dockerfile: PIE solo en tiempo de build

La forma preconizada antes:

FROM php:8.4-cli
RUN pecl install redis \
&& docker-php-ext-enable redis

La forma con PIE:

# syntax=docker/dockerfile:1
FROM php:8.4-cli
RUN --mount=type=bind,from=ghcr.io/php/pie:bin,source=/pie,target=/usr/local/bin/pie \
export DEBIAN_FRONTEND=noninteractive; \
set -eux; \
apt-get update; \
apt-get install -y --no-install-recommends unzip; \
pie install --no-cache phpredis/phpredis; \
apt-get purge -y --auto-remove unzip; \
rm -rf /var/lib/apt/lists/*;

Tres detalles deciden si esto funciona. ghcr.io/php/pie:bin es una imagen solo binario: no trae PHP y por sí sola no puede ejecutar PIE; el FROM aporta el runtime que corre el PHAR montado. Las etiquetas bin, nightly-bin y x.y.z-bin existen desde PIE 1.5. El --mount deja el instalador fuera de la capa final, así que no queda nada que actualizar en producción. Y en la imagen oficial de Docker, pie install ya habilita la extensión con docker-php-ext-enable, por lo que sobra la segunda línea del ejemplo anterior; si quieres manejar los .ini a mano, usa --skip-enable-extension.

Si la extensión necesita librerías del sistema, agrégalas en el mismo apt-get install, antes de pie install, y retíralas en el purge. Desde PIE 1.5 se pueden instalar varias extensiones en un solo comando, pero el instalador falla si comparten opciones de configuración: en ese caso, sepáralas en dos líneas.

CI reproducible: pie.json, pie.lock y --select

pie install sin argumentos, dentro de un proyecto con composer.json, revisa los requisitos ext-* e intenta instalar los que falten. En CI, sin terminal interactiva, el flag antiguo --allow-non-interactive-project-install ya no funciona: desde PIE 1.5 hay que mapear cada extensión con --select.

pie install --no-dev --select redis=phpredis/phpredis

--no-dev evita instalar extensiones que solo están en require-dev, como Xdebug en una imagen de producción. Para conservar versiones, PIE escribe pie.json y pie.lock por instalación de PHP y pie show -v indica la ruta exacta. Copia ambos archivos a esa ruta en tu pipeline y ejecuta pie install --from-lock para repetir lo que instalaste. pie upgrade respeta la restricción original: un ^3.4 no salta a una versión mayor sin que tú lo pidas.

El siguiente paso es concreto: corre git grep -n "pecl install" en tu repositorio, revisa para cada extensión si figura en packagist.org/extensions y convierte primero el Dockerfile que construye producción, antes de que PHP 8.6 pase a estable. Los scripts de desarrollo pueden migrarse después, mientras PECL siga respondiendo.

Preguntas frecuentes

¿PECL dejó de funcionar?

No. La RFC de apagón sigue en discusión y pecl.php.net continúa operativo mientras tanto. Lo que ya ocurrió es que las imágenes oficiales de PHP 8.6 no lo incluyen, así que el impacto inmediato está en los Dockerfiles, no en el sitio de PECL.

¿PIE exige PHP 8.6?

No. El PHAR corre desde PHP 8.1 y puede instalar extensiones para otra versión con --with-php-config. Si no hay ningún PHP 8.1 disponible para ejecutarlo, el binario con Static PHP cubre ese caso.

¿Todas las extensiones de PECL ya están en PIE?

No. El catálogo es packagist.org/extensions y una extensión aparece solo si su mantenedor publicó el paquete. Comprueba eso antes de borrar el pecl install: si no está, no será instalable con PIE hasta que alguien la migre.

¿Hay que instalar PIE en la imagen final?

No. Con el mount desde ghcr.io/php/pie:bin, PIE existe únicamente durante el build. En el runtime quedan el .so compilado y su entrada en el INI.

¿Qué hago con un pipeline que usa pecl upgrade-all?

Sustitúyelo por pie upgrade, que actualiza dentro de la restricción con que se instaló cada extensión. Si además quieres reproducibilidad, versiona pie.json y pie.lock y usa pie install --from-lock. Empieza por el job que publica la imagen de producción, fija la versión en pie.json y deja los scripts de desarrollo para el final.

Compartir