From 56fca34663ebd6838eb7929660f172db5fd818f9 Mon Sep 17 00:00:00 2001
From: Joao Gilberto Magalhaes <joao@byjg.com.br>
Date: Wed, 21 Oct 2026 17:44:57 -0400
Subject: [PATCH 1/2] Install PHP extensions with PIE on 8.3+ and add
 php-disable-module

- Replace pecl: with pie: in the 8.3-8.6 configs; 8.6 builds imagick, memcached
  and yaml from pinned commits with PIE
- Ship pie and the pie-install helper in images with pie: in the config
- Add php-disable-module (also --all-except and --list) to the images
- Add PHP_DISABLE_MODULES and PHP_ENABLED_MODULES; deprecate DISABLEMODULE_<name>
- install-sqlsvr: use PIE when available, skip the extension when it does not
  build, and detect aarch64
- Keep '#' inside words when stripping template comments
---
 assets/entrypoint.sh                |  41 +++++---
 assets/index.html                   |  21 +++-
 assets/script/install-sqlsvr.sh     |  25 ++++-
 assets/script/php-disable-module.sh | 143 ++++++++++++++++++++++++++++
 assets/script/pie-install.sh        |  61 ++++++++++++
 config/php-8.3.yml                  |   5 +-
 config/php-8.4.yml                  |   5 +-
 config/php-8.5.yml                  |   5 +-
 config/php-8.6.yml                  |  24 ++---
 docs/building.md                    |  54 +++++++----
 docs/dockerfile.md                  | 134 +++++++++++++++++---------
 docs/environment.md                 |  34 ++++++-
 docs/security.md                    |   6 +-
 generator/__init__.py               |  10 +-
 templates/php-base.j2               |  28 +++++-
 15 files changed, 481 insertions(+), 115 deletions(-)
 create mode 100755 assets/script/php-disable-module.sh
 create mode 100755 assets/script/pie-install.sh

diff --git a/assets/entrypoint.sh b/assets/entrypoint.sh
index 5e49a2b..f27315f 100755
--- a/assets/entrypoint.sh
+++ b/assets/entrypoint.sh
@@ -28,22 +28,39 @@ then
   PHPMODULES=`php -i | grep "Scan this dir" |  awk -F" => " '{print $2}'`
   PHPCUSTOM=/etc/php/conf.d
 
-  # Disable modules
-  for VAR in `printenv | grep DISABLEMODULE | grep -E '(true|yes|1)' | cut -d= -f1 | cut -d_ -f2- | awk '{print tolower($0)}'`
-  do
-      if [[ -f "$PHPMODULES/*$VAR.ini" ]]
+  # Keep only these modules (and the ones they require): PHP_ENABLED_MODULES="pdo_mysql,mbstring"
+  ENABLED_MODULES=`echo "$PHP_ENABLED_MODULES" | tr ',' ' '`
+  if [[ -n "${ENABLED_MODULES// /}" ]]
+  then
+      if ${VERBOSE_MODE}
       then
-          ${VERBOSE_MODE} && echo "Disabling Module $VAR ..."
-          rm "$PHPMODULES/*$VAR.ini"
-      elif [[ -f "$PHPMODULES/$VAR.ini" ]]
+          /usr/local/bin/php-disable-module --all-except $ENABLED_MODULES
+      else
+          /usr/local/bin/php-disable-module --all-except $ENABLED_MODULES > /dev/null
+      fi
+  fi
+
+  # Disable modules: PHP_DISABLE_MODULES="yaml,memcached" (comma or space separated)
+  DISABLE_MODULES=`echo "$PHP_DISABLE_MODULES" | tr ',' ' '`
+
+  # Deprecated: DISABLEMODULE_<module>=true, will be removed in a future release
+  DEPRECATED_MODULES=`printenv | grep -E '^DISABLEMODULE_[^=]+=(true|yes|1)$' | cut -d= -f1 | cut -d_ -f2-`
+  if [[ -n "$DEPRECATED_MODULES" ]]
+  then
+      echo "DISABLEMODULE_<module> is deprecated, use PHP_DISABLE_MODULES=\"`echo $DEPRECATED_MODULES | tr '[:upper:] ' '[:lower:],'`\"" >&2
+      DISABLE_MODULES="$DISABLE_MODULES $DEPRECATED_MODULES"
+  fi
+
+  if [[ -n "${DISABLE_MODULES// /}" ]]
+  then
+      if ${VERBOSE_MODE}
       then
-          ${VERBOSE_MODE} && echo "Disabling Module $VAR ..."
-          rm "$PHPMODULES/$VAR.ini"
+          /usr/local/bin/php-disable-module $DISABLE_MODULES
+          echo
       else
-          ${VERBOSE_MODE} && echo "Module not found $VAR"
+          /usr/local/bin/php-disable-module $DISABLE_MODULES > /dev/null
       fi
-  done
-  ${VERBOSE_MODE} && echo
+  fi
 
   # List available modules
   if [[ "$VERBOSE" == "true" ]]
diff --git a/assets/index.html b/assets/index.html
index e74cad4..48cec0c 100644
--- a/assets/index.html
+++ b/assets/index.html
@@ -231,12 +231,27 @@ <h2 class="text-3xl font-bold tracking-tight sm:text-4xl">Environment Configurat
             </div>
 
             <div class="rounded-xl border border-slate-200 bg-white shadow p-6">
-                <div class="font-semibold font-mono text-base mb-3">DISABLEMODULE_[name]</div>
+                <div class="font-semibold font-mono text-base mb-3">PHP_DISABLE_MODULES</div>
                 <div class="space-y-2">
-                    <p class="text-slate-600">Disable specific PHP modules at runtime to optimize performance.</p>
+                    <p class="text-slate-600">Comma separated list of PHP modules to disable at runtime to optimize performance.</p>
                     <p class="text-sm"><span class="font-medium">Default:</span> <span class="text-slate-600">All modules enabled</span></p>
                     <div class="relative code-block mt-3">
-                        <pre class="overflow-x-auto rounded-xl border border-slate-200 bg-slate-100 p-4 pr-12 font-mono text-sm"><code>docker run -e DISABLEMODULE_DOM=true -e DISABLEMODULE_XSL=true @@DOCKER_IMAGE@@</code></pre>
+                        <pre class="overflow-x-auto rounded-xl border border-slate-200 bg-slate-100 p-4 pr-12 font-mono text-sm"><code>docker run -e PHP_DISABLE_MODULES="dom,xsl" @@DOCKER_IMAGE@@</code></pre>
+                        <button onclick="copyCode(this)" class="copy-btn absolute right-2 top-2 rounded-md border border-slate-200 bg-white p-2 text-slate-500 hover:text-slate-900" aria-label="Copy to clipboard">
+                            <svg class="copy-icon h-4 w-4" xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/></svg>
+                            <svg class="check-icon h-4 w-4 text-green-600" xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="20 6 9 17 4 12"/></svg>
+                        </button>
+                    </div>
+                </div>
+            </div>
+
+            <div class="rounded-xl border border-slate-200 bg-white shadow p-6">
+                <div class="font-semibold font-mono text-base mb-3">PHP_ENABLED_MODULES</div>
+                <div class="space-y-2">
+                    <p class="text-slate-600">Comma separated list of PHP modules to keep enabled at runtime; all the others are disabled. The modules they require are kept too.</p>
+                    <p class="text-sm"><span class="font-medium">Default:</span> <span class="text-slate-600">All modules enabled</span></p>
+                    <div class="relative code-block mt-3">
+                        <pre class="overflow-x-auto rounded-xl border border-slate-200 bg-slate-100 p-4 pr-12 font-mono text-sm"><code>docker run -e PHP_ENABLED_MODULES="pdo_mysql,mbstring" @@DOCKER_IMAGE@@</code></pre>
                         <button onclick="copyCode(this)" class="copy-btn absolute right-2 top-2 rounded-md border border-slate-200 bg-white p-2 text-slate-500 hover:text-slate-900" aria-label="Copy to clipboard">
                             <svg class="copy-icon h-4 w-4" xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/></svg>
                             <svg class="check-icon h-4 w-4 text-green-600" xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><polyline points="20 6 9 17 4 12"/></svg>
diff --git a/assets/script/install-sqlsvr.sh b/assets/script/install-sqlsvr.sh
index 5a1c9ae..f7aa271 100755
--- a/assets/script/install-sqlsvr.sh
+++ b/assets/script/install-sqlsvr.sh
@@ -1,3 +1,4 @@
+#!/usr/bin/env bash
 
 #
 # https://learn.microsoft.com/en-us/sql/connect/odbc/linux-mac/installing-the-microsoft-odbc-driver-for-sql-server?view=sql-server-ver15&tabs=alpine18-install%2Calpine17-install%2Cdebian8-install%2Credhat7-13-install%2Crhel7-offline#alpine-linux
@@ -8,7 +9,7 @@ set -x
 
 case $(uname -m) in
     x86_64)   ARCH="amd64" ;;
-    arm64)   ARCH="arm64" ;;
+    aarch64|arm64)   ARCH="arm64" ;;
     *) ARCH="unsupported" ;;
 esac
 if [[ "unsupported" == "$ARCH" ]];
@@ -28,10 +29,24 @@ wget ${BASE_URL}/msodbcsql${VERSION_ODBC}.apk
 wget ${BASE_URL}/mssql-tools${VERSION_TOOLS}.apk
 yes | apk add --allow-untrusted msodbcsql${VERSION_ODBC}.apk 
 yes | apk add --allow-untrusted mssql-tools${VERSION_TOOLS}.apk
-apk add --no-cache --virtual .phpize-deps ${PHP_VARIANT}-dev build-base unixodbc-dev
-pecl install pdo_sqlsrv
-echo extension=pdo_sqlsrv.so > /etc/${PHP_VARIANT}/conf.d/30_sqlsvr.ini
-apk del .phpize-deps
+# The extension is enabled only when it builds, so a failed build leaves no .ini behind.
+# pdo_sqlsrv does not build on every PHP version (e.g. 8.6, until Microsoft publishes a
+# compatible release): the extension is then skipped, and the ODBC driver stays installed.
+# Images with PIE (PHP 8.3+) use it; the older ones keep PECL.
+if command -v pie-install >/dev/null;
+then
+    pie-install --deps unixodbc --build-deps unixodbc-dev microsoft/pdo_sqlsrv
+    STATUS=$?
+else
+    apk add --no-cache --virtual .phpize-deps ${PHP_VARIANT}-dev build-base unixodbc-dev
+    pecl install pdo_sqlsrv && echo extension=pdo_sqlsrv.so > /etc/${PHP_VARIANT}/conf.d/30_sqlsvr.ini
+    STATUS=$?
+    apk del .phpize-deps
+fi
+if [[ $STATUS -ne 0 ]];
+then
+    echo "SKIPPED: pdo_sqlsrv does not build on PHP ${PHP_VERSION} (see the build log above). The Microsoft ODBC driver is installed, the PHP extension is not." >&2
+fi
 rm -f msodbcsql${VERSION_ODBC}.apk
 rm -f mssql-tools${VERSION_TOOLS}.apk
 rm -rf pear
diff --git a/assets/script/php-disable-module.sh b/assets/script/php-disable-module.sh
new file mode 100755
index 0000000..b2626a7
--- /dev/null
+++ b/assets/script/php-disable-module.sh
@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+#
+# Disable PHP modules by removing their ini file from the PHP scan directory.
+#
+# Usage:
+#   php-disable-module <module> [<module> ...]
+#   php-disable-module --all-except <module> [<module> ...]
+#   php-disable-module --list      list the modules that can be disabled
+#
+# Examples:
+#   php-disable-module yaml
+#   php-disable-module xdebug memcached
+#   php-disable-module --all-except pdo_mysql mbstring
+#
+# The ini file can be "<module>.ini" or have a numeric priority prefix: "70_yaml.ini" (apk),
+# "80-yaml.ini" (PIE). Exits with 1 if any module was not found.
+#
+# --all-except also keeps the modules the given ones require (e.g. pdo_mysql keeps pdo and
+# mysqlnd), and exits with 1 if PHP does not start cleanly afterwards.
+#
+
+if [[ -z "$1" ]]; then
+    sed -n '3,19p' "$0" | sed 's/^# \{0,1\}//'
+    exit 1
+fi
+
+PHPMODULES=`php -i | grep "Scan this dir" | awk -F" => " '{print $2}'`
+
+# A module can be disabled when an ini file in the scan directory loads it
+list_modules() {
+    (cd "$PHPMODULES" && grep -l -E '^\s*(zend_)?extension\s*=' *.ini 2>/dev/null) \
+        | sed -E 's/^[0-9]+[_-]//; s/\.ini$//' | sort -u
+}
+
+# The modules a module requires: the ones PHP declares, plus the apk package dependencies, which
+# also list libraries PHP does not declare (e.g. mysqlnd needs openssl). A module PIE built has no
+# apk package, so only what PHP declares is known for it.
+requires() {
+    php -r '
+        if (extension_loaded($argv[1])) {
+            foreach ((new ReflectionExtension($argv[1]))->getDependencies() as $dep => $type) {
+                if ($type === "Required") {
+                    echo strtolower($dep), "\n";
+                }
+            }
+        }
+    ' -- "$1" 2>/dev/null
+
+    local FILE PACKAGE DEP
+    for FILE in `ls "$PHPMODULES" | grep -E "^([0-9]+[_-])?${1}\.ini$"`
+    do
+        PACKAGE=`apk info -W "$PHPMODULES/$FILE" 2>/dev/null | awk '/is owned by/ {print $NF}' | sed -E 's/-[0-9][^-]*-r[0-9]+$//'`
+        [[ -z "$PACKAGE" ]] && continue
+        for DEP in `apk info -R "$PACKAGE" 2>/dev/null | grep -v 'depends on' | grep -E '^php[0-9]*-'`
+        do
+            apk info -L "$DEP" 2>/dev/null | grep -E "/conf\.d/[^/]+\.ini$" \
+                | sed -E 's|.*/||; s/^[0-9]+[_-]//; s/\.ini$//'
+        done
+    done
+}
+
+if [[ "$1" == "--list" ]]; then
+    list_modules
+    exit 0
+fi
+
+if [[ "$1" == "--all-except" ]]; then
+    shift
+    AVAILABLE=" `list_modules | tr '\n' ' '` "
+    LOADED=" `php -m 2>/dev/null | awk '{print tolower($0)}' | tr '\n' ' '` "
+
+    KEEP=""
+    for MODULE in "$@"
+    do
+        MODULE=`echo "$MODULE" | awk '{print tolower($0)}'`
+        # A module compiled into PHP (e.g. json, spl) has no ini file and is always enabled
+        if [[ "$AVAILABLE" != *" $MODULE "* && "$LOADED" != *" $MODULE "* ]]; then
+            echo "Module not found: $MODULE" >&2
+            exit 1
+        fi
+        KEEP="$KEEP $MODULE"
+    done
+
+    # Add the modules they require, until no new one shows up
+    QUEUE="$KEEP"
+    while [[ -n "${QUEUE// /}" ]]
+    do
+        NEXT=""
+        for MODULE in $QUEUE
+        do
+            for DEP in `requires "$MODULE"`
+            do
+                if [[ " $KEEP " != *" $DEP "* ]]; then
+                    KEEP="$KEEP $DEP"
+                    NEXT="$NEXT $DEP"
+                fi
+            done
+        done
+        QUEUE="$NEXT"
+    done
+    KEPT=""
+    DISABLE=""
+    for MODULE in $AVAILABLE
+    do
+        if [[ " $KEEP " == *" $MODULE "* ]]; then
+            KEPT="$KEPT $MODULE"
+        else
+            DISABLE="$DISABLE $MODULE"
+        fi
+    done
+    echo "Keeping modules:$KEPT"
+    [[ -n "$DISABLE" ]] && "$0" $DISABLE
+
+    # A module can need another one PHP does not declare; it then fails to load
+    ERRORS=`php -v 2>&1 | grep -E 'Warning|Fatal error'`
+    if [[ -n "$ERRORS" ]]; then
+        echo "PHP does not start cleanly after disabling the modules:" >&2
+        echo "$ERRORS" >&2
+        exit 1
+    fi
+    exit 0
+fi
+
+STATUS=0
+for MODULE in "$@"
+do
+    MODULE=`echo "$MODULE" | awk '{print tolower($0)}'`
+    MODULE_FILES=`ls "$PHPMODULES" | grep -E "^([0-9]+[_-])?${MODULE}\.ini$"`
+    if [[ -z "$MODULE_FILES" ]]
+    then
+        echo "Module not found: $MODULE" >&2
+        STATUS=1
+        continue
+    fi
+
+    echo "Disabling module $MODULE ..."
+    for FILE in $MODULE_FILES
+    do
+        rm -f "$PHPMODULES/$FILE"
+    done
+done
+
+exit $STATUS
diff --git a/assets/script/pie-install.sh b/assets/script/pie-install.sh
new file mode 100755
index 0000000..e61725c
--- /dev/null
+++ b/assets/script/pie-install.sh
@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+#
+# Install a PHP extension with PIE (https://github.com/php/pie) and leave no build tools behind.
+#
+# Usage (as root):
+#   pie-install [--build-deps "<apk packages>"] [--deps "<apk packages>"] <vendor/package>[:<constraint>] [pie options]
+#
+#   --build-deps  extra apk packages needed only to compile the extension (removed at the end)
+#   --deps        apk packages the extension needs at runtime (kept in the image)
+#
+# Examples:
+#   pie-install apcu/apcu
+#   pie-install --build-deps "imagemagick-dev" --deps "imagemagick" imagick/imagick
+#   pie-install xdebug/xdebug:^3.4 --skip-enable-extension
+#
+# PIE enables the extension by writing /etc/${PHP_VARIANT}/conf.d/<priority>-<extension>.ini
+#
+
+set -e
+
+if [[ "$(id -u)" != "0" ]]; then
+    echo "pie-install must run as root (add 'USER root' before it in your Dockerfile)." >&2
+    exit 1
+fi
+
+BUILD_DEPS=""
+DEPS=""
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --build-deps) BUILD_DEPS="$2"; shift 2 ;;
+        --deps)       DEPS="$2"; shift 2 ;;
+        *) break ;;
+    esac
+done
+
+if [[ -z "$1" ]]; then
+    sed -n '3,14p' "$0" | sed 's/^# \{0,1\}//'
+    exit 1
+fi
+
+# The edge/testing repository is where Alpine publishes the newest PHP (e.g. php86-dev)
+REPOSITORY="--repository https://dl-cdn.alpinelinux.org/alpine/edge/testing"
+
+if [[ -n "$DEPS" ]]; then
+    apk add --no-cache $REPOSITORY $DEPS
+fi
+apk add --no-cache $REPOSITORY --virtual .pie-build-deps \
+    ${PHP_VARIANT}-dev autoconf build-base libtool linux-headers pkgconf $BUILD_DEPS
+
+STATUS=0
+pie install -n "$@" || STATUS=$?
+
+# PIE saves long build output to /tmp/pie_*; show it before it is cleaned up
+if [[ $STATUS -ne 0 ]]; then
+    tail -n 40 /tmp/pie_* 2>/dev/null || true
+fi
+
+apk del --no-cache .pie-build-deps
+rm -rf /root/.pie /root/.composer/cache /tmp/pie_*
+
+exit $STATUS
diff --git a/config/php-8.3.yml b/config/php-8.3.yml
index ca68aa8..639b98a 100644
--- a/config/php-8.3.yml
+++ b/config/php-8.3.yml
@@ -58,7 +58,7 @@ extensions:
   - zip
   - zlib
 
-pecl:
+pie:
   - name: xdebug
     install: False
     zend: True
@@ -76,7 +76,7 @@ composer:
     - phpbcbf
     - phpmd
 
-peclBuildPackages:
+pieBuildPackages:
   - autoconf
   - build-base
   - cyrus-sasl-dev
@@ -84,6 +84,7 @@ peclBuildPackages:
   - libtool
   - make
   - openssl-dev
+  - pkgconf
   - zlib-dev
 
 additionalPackages:
diff --git a/config/php-8.4.yml b/config/php-8.4.yml
index f3ed116..8e3c8b2 100644
--- a/config/php-8.4.yml
+++ b/config/php-8.4.yml
@@ -58,7 +58,7 @@ extensions:
   - zip
   - zlib
 
-pecl:
+pie:
   - name: xdebug
     install: False
     zend: True
@@ -76,7 +76,7 @@ composer:
     - phpbcbf
     - phpmd
 
-peclBuildPackages:
+pieBuildPackages:
   - autoconf
   - build-base
   - cyrus-sasl-dev
@@ -84,6 +84,7 @@ peclBuildPackages:
   - libtool
   - make
   - openssl-dev
+  - pkgconf
   - zlib-dev
 
 additionalPackages:
diff --git a/config/php-8.5.yml b/config/php-8.5.yml
index 5e7a8d7..c7de4aa 100644
--- a/config/php-8.5.yml
+++ b/config/php-8.5.yml
@@ -58,7 +58,7 @@ extensions:
   - zip
   - zlib
 
-pecl:
+pie:
   - name: xdebug
     install: False
     zend: True
@@ -76,7 +76,7 @@ composer:
     - phpbcbf
     - phpmd
 
-peclBuildPackages:
+pieBuildPackages:
   - autoconf
   - build-base
   - cyrus-sasl-dev
@@ -84,6 +84,7 @@ peclBuildPackages:
   - libtool
   - make
   - openssl-dev
+  - pkgconf
   - zlib-dev
 
 additionalPackages:
diff --git a/config/php-8.6.yml b/config/php-8.6.yml
index 9950309..b69228f 100644
--- a/config/php-8.6.yml
+++ b/config/php-8.6.yml
@@ -36,7 +36,7 @@ extensions:
   - pdo_pgsql
   - pdo_sqlite
   - pear
-# imagick: see the `pecl` section below (compiled but not enabled)
+# imagick: see the `pie` section below (compiled but not enabled)
 #  - pecl-memcached
   - pecl-mongodb
   - pecl-xdebug
@@ -58,37 +58,32 @@ extensions:
   - zip
   - zlib
 
-pecl:
+pie:
   - name: xdebug
     install: False
     zend: True
     config:
       - xdebug.remote_port=9001
-  # The extensions below have no Alpine package for PHP 8.6 yet, and their latest pecl.php.net
-  # releases do not build on PHP 8.6 (XtOffsetOf / zval_dtor removed); the fix is only in git.
+  # The extensions below have no Alpine package for PHP 8.6 yet, and their latest releases
+  # do not build on PHP 8.6 (XtOffsetOf / zval_dtor removed); the fix is only in git, so PIE
+  # installs a pinned commit of the development branch.
   # Temporary: remove each entry and enable the matching `pecl-*` in `extensions` once Alpine
   # publishes php86-pecl-imagick, php86-pecl-memcached and php86-pecl-yaml.
   # imagick is only compiled, not enabled: the ImageMagick runtime is too large to ship by default.
   # To use it: apk add imagemagick && echo "extension=imagick.so" > /etc/php86/conf.d/imagick.ini
   - name: imagick
+    package: imagick/imagick:dev-master#55ed2e9fda264395636a2e27e51f31673f5566ab
     enable: False
-    source:
-      repository: https://github.com/Imagick/imagick.git
-      reference: 55ed2e9fda264395636a2e27e51f31673f5566ab
     buildPackages:
       - imagemagick-dev
   - name: memcached
-    source:
-      repository: https://github.com/php-memcached-dev/php-memcached.git
-      reference: 0b52d3657140750fa0eddd20cdbfc6edc8fbdadd
+    package: php-memcached/php-memcached:dev-master#0b52d3657140750fa0eddd20cdbfc6edc8fbdadd
     buildPackages:
       - libmemcached-dev
     packages:
       - libmemcached-libs
   - name: yaml
-    source:
-      repository: https://github.com/php/pecl-file_formats-yaml.git
-      reference: a7a3b8680b8fbf0895fd63371a0ffc1305b1a5b8
+    package: pecl/yaml:dev-php7#a7a3b8680b8fbf0895fd63371a0ffc1305b1a5b8
     buildPackages:
       - yaml-dev
     packages:
@@ -105,7 +100,7 @@ composer:
     - phpbcbf
     - phpmd
 
-peclBuildPackages:
+pieBuildPackages:
   - autoconf
   - build-base
   - cyrus-sasl-dev
@@ -113,6 +108,7 @@ peclBuildPackages:
   - libtool
   - make
   - openssl-dev
+  - pkgconf
   - zlib-dev
 
 additionalPackages:
diff --git a/docs/building.md b/docs/building.md
index 3303f75..75c32ca 100644
--- a/docs/building.md
+++ b/docs/building.md
@@ -136,19 +136,23 @@ extensions:
   - (NAME)
   - (NAME)
 
-# The PECL extensions to be installed
-pecl:
-  - name: xdebug                    # required
-    version: 2.5.5                  # optional - if not set, get the latest
-    install: False                  # optional - do not call pecl install
-    enable: False                   # optional - do not create the .ini file; the extension
-                                    #            is left in the image but not loaded
-    zend: True                      # optional - if true, add as zend extension
-    config:                         # optional - if set, add extra config to php.ini 
-      - xdebug.remote_port=9001     #            for this extension
-    source:                         # optional - build from a git repository instead of
-      repository: https://...git    #            downloading the release from pecl.php.net
-      reference: (COMMIT/TAG)       #            optional - if not set, use the default branch
+# The extensions installed with PIE (https://github.com/php/pie), the PHP Foundation's
+# replacement for PECL. Prefer the Alpine package in `extensions` when there is one.
+# PIE needs PHP 8.1 or later: the configs of PHP 5.6 to 7.3 keep `pecl:` (see below).
+pie:
+  - name: imagick                   # required - the extension name (used for the .ini file)
+    package: imagick/imagick        # required unless `install: False` - the PIE (Packagist) package,
+                                    #            optionally with a constraint: `vendor/pkg:^3.8`, or a
+                                    #            pinned commit: `vendor/pkg:dev-master#<commit>`
+    options:                        # optional - extra `pie install` options, e.g. configure flags
+      - --with-imagick=/usr
+    install: False                  # optional - do not call `pie install` (the extension comes from
+                                    #            an Alpine package); only the .ini file is written
+    enable: False                   # optional - do not enable it; the extension is left in the
+                                    #            image but not loaded (`pie install --skip-enable-extension`)
+    zend: True                      # optional - with `install: False`, add as zend_extension
+    config:                         # optional - extra ini settings for this extension, written to
+      - imagick.skip_version_check=1 #           /etc/phpXY/conf.d/<name>.ini
     buildPackages:                  # optional - temporary packages needed only to build
       - (NAME)                      #            this extension
     packages:                       # optional - permanent packages this extension needs
@@ -166,14 +170,30 @@ composer:
     - phpbcbf
     - phpmd
 
-# Temporary packages to be used to build the PECL packages (generic; packages needed
-# by a single extension go in `pecl[].buildPackages`)
-peclBuildPackages:
+# Temporary packages used to build the PIE extensions (generic; packages needed
+# by a single extension go in `pie[].buildPackages`). `phpXY-dev` is always added.
+pieBuildPackages:
   - autoconf
   - build-base
+  - libtool
+  - pkgconf
+
+# PHP versions where PIE cannot run (it needs PHP 8.1+) keep the PECL keys. They have the
+# same entries as `pie:`, with `version:` (the PECL release) instead of `package:`, and
+# `source:` (repository + reference) to build from a git repository:
+#
+# pecl:
+#   - name: mongodb
+#     version: 1.7.5
+# peclBuildPackages:
+#   - autoconf
+#   - build-base
+#
+# A config can have `pecl:`, `pie:`, or neither. PIE and `pie-install` are only installed
+# in an image whose config has `pie:`.
 
 # Permanent packages to be installed in the image (generic; packages needed
-# by a single extension go in `pecl[].packages`)
+# by a single extension go in `pie[].packages` or `pecl[].packages`)
 additionalPackages:
   - libssl1.1
   - libcrypto1.1
diff --git a/docs/dockerfile.md b/docs/dockerfile.md
index 99d36f8..a3da809 100644
--- a/docs/dockerfile.md
+++ b/docs/dockerfile.md
@@ -87,6 +87,50 @@ RUN composer install --no-dev --optimize-autoloader
 Always switch back to the `app` user after installing packages. Running your application as root negates security benefits.
 :::
 
+### Installing a PHP Extension with PIE
+
+If the extension has no Alpine package (`apk search phpXY-pecl-<name>`), install it with
+[PIE](https://github.com/php/pie), the PHP Foundation's replacement for PECL. The images ship
+`pie` and the `pie-install` helper; `pie-install` adds the compiler and the `phpXY-dev` package,
+runs `pie install`, enables the extension and removes the build tools again, so they do not stay
+in your image. It must run as `root`:
+
+```dockerfile title="Dockerfile"
+FROM byjg/php:8.5-cli
+
+USER root
+RUN pie-install apcu/apcu
+USER app
+```
+
+Options (before the package name):
+
+| Option                       | Description                                                          |
+|------------------------------|----------------------------------------------------------------------|
+| `--build-deps "<apk pkgs>"`  | Extra packages needed only to compile the extension (removed after)  |
+| `--deps "<apk pkgs>"`        | Packages the extension needs at runtime (kept in the image)          |
+
+Anything after the package name is passed to `pie install` (e.g. `--skip-enable-extension` or
+configure options). The package accepts a version constraint, e.g. `xdebug/xdebug:^3.4`.
+
+```dockerfile title="Dockerfile"
+FROM byjg/php:8.5-cli
+
+USER root
+RUN pie-install --build-deps "imagemagick-dev" --deps "imagemagick" imagick/imagick
+USER app
+```
+
+PIE enables the extension by writing `/etc/phpXY/conf.d/<priority>-<extension>.ini`; it can be
+disabled like any other module (see [Disabling modules](#disabling-modules)). Find the PIE
+package name of an extension on [Packagist](https://packagist.org/extensions).
+
+:::note
+PIE downloads the extension source from GitHub. When building many images from the same IP
+(e.g. in CI) you may hit the GitHub API rate limit; set `GITHUB_TOKEN` in the build environment
+to avoid it.
+:::
+
 #### Imagick on PHP 8.6
 
 The PHP 8.6 images already contain a compiled `imagick.so`, but it is not enabled and the
@@ -102,6 +146,47 @@ RUN apk add --no-cache imagemagick && \
 USER app
 ```
 
+### Disabling modules
+
+`php-disable-module` removes the ini file of one or more modules, so they are disabled in your image:
+
+```dockerfile title="Dockerfile"
+FROM byjg/php:8.5-cli
+
+RUN php-disable-module xdebug soap ftp
+```
+
+It finds the ini file whatever its name: `<module>.ini`, or with a priority prefix such as
+`70_yaml.ini` (apk) or `80-yaml.ini` (PIE). It exits with an error if a module is not found, so a
+typo fails the build.
+
+To keep only some modules and disable all the others, use `--all-except`:
+
+```dockerfile title="Dockerfile"
+FROM byjg/php:8.5-cli
+
+RUN php-disable-module --all-except pdo_mysql mbstring
+```
+
+The modules they require are kept too (here `pdo`, `mysqlnd` and `openssl`), from what PHP
+declares and from the Alpine package dependencies. Afterwards it starts PHP once and fails if a
+module does not load, so a missing dependency fails the build instead of the container.
+
+The modules that can be disabled vary a little by PHP version. List them with:
+
+```bash
+docker run --rm byjg/php:8.5-cli php-disable-module --list
+```
+
+:::note
+Some modules depend on others. Disabling `pdo` without the `pdo_*` drivers makes PHP print a
+startup warning for each driver: disable them together.
+:::
+
+To disable modules when the container starts instead, set
+[`PHP_DISABLE_MODULES`](environment.md#php_disable_modules) or
+[`PHP_ENABLED_MODULES`](environment.md#php_enabled_modules).
+
 ### Full Configuration Example
 
 ```dockerfile title="Dockerfile"
@@ -118,50 +203,9 @@ ENV PHP_CONTROLLER=/index.php
 # ENV NGINX_SSL_CERT=/path/to/ssl.crt
 # ENV NGINX_SSL_CERT_KEY=/path/to/ssl.key
 
-# Disable unnecessary modules for better performance
-# ENV DISABLEMODULE_bcmath=1
-# ENV DISABLEMODULE_ctype=1
-# ENV DISABLEMODULE_curl=1
-# ENV DISABLEMODULE_dba=1
-# ENV DISABLEMODULE_dom=1
-# ENV DISABLEMODULE_fileinfo=1
-# ENV DISABLEMODULE_ftp=1
-# ENV DISABLEMODULE_gd=1
-# ENV DISABLEMODULE_gettext=1
-# ENV DISABLEMODULE_iconv=1
-# ENV DISABLEMODULE_intl=1
-# ENV DISABLEMODULE_mbstring=1
-# ENV DISABLEMODULE_openssl=1
-# ENV DISABLEMODULE_pcntl=1
-# ENV DISABLEMODULE_pdo=1
-# ENV DISABLEMODULE_posix=1
-# ENV DISABLEMODULE_session=1
-# ENV DISABLEMODULE_shmop=1
-# ENV DISABLEMODULE_simplexml=1
-# ENV DISABLEMODULE_soap=1
-# ENV DISABLEMODULE_sockets=1
-# ENV DISABLEMODULE_sqlite3=1
-# ENV DISABLEMODULE_tokenizer=1
-# ENV DISABLEMODULE_xml=1
-# ENV DISABLEMODULE_xmlwriter=1
-# ENV DISABLEMODULE_zip=1
-# ENV DISABLEMODULE_exif=1
-# ENV DISABLEMODULE_mysqlnd=1
-# ENV DISABLEMODULE_pdo_dblib=1
-# ENV DISABLEMODULE_pdo_pgsql=1
-# ENV DISABLEMODULE_pdo_sqlite=1
-# ENV DISABLEMODULE_phar=1
-# ENV DISABLEMODULE_xmlreader=1
-# ENV DISABLEMODULE_xsl=1
-# ENV DISABLEMODULE_mysqli=1
-# ENV DISABLEMODULE_pdo_mysql=1
-# ENV DISABLEMODULE_igbinary=1
-# ENV DISABLEMODULE_memcached=1
-# ENV DISABLEMODULE_redis=1
-# ENV DISABLEMODULE_msgpack=1
-# ENV DISABLEMODULE_xdebug=1
-# ENV DISABLEMODULE_yaml=1
-# ENV DISABLEMODULE_mongodb=1
+# Disable unnecessary modules for better performance. Every module that can be disabled in 8.5;
+# the list varies a little by version: run "php-disable-module --list" in the image to see it.
+# ENV PHP_DISABLE_MODULES="bcmath,ctype,curl,dba,dom,exif,fileinfo,ftp,gd,gettext,iconv,igbinary,intl,mbstring,memcached,mongodb,msgpack,mysqli,mysqlnd,openssl,pcntl,pdo,pdo_dblib,pdo_mysql,pdo_pgsql,pdo_sqlite,phar,posix,redis,session,shmop,simplexml,soap,sockets,sqlite3,tokenizer,xdebug,xml,xmlreader,xmlwriter,xsl,yaml,zip"
 
 # Copy application with proper ownership
 COPY --chown=app:app . /app
@@ -200,7 +244,7 @@ ENV PHP_CONTROLLER=/index.php
 ENV NGINX_ROOT=/var/www/html/public
 
 # Disable XDebug in production
-ENV DISABLEMODULE_xdebug=1
+RUN php-disable-module xdebug
 
 EXPOSE 80
 ```
diff --git a/docs/environment.md b/docs/environment.md
index caadc95..9027f06 100644
--- a/docs/environment.md
+++ b/docs/environment.md
@@ -62,17 +62,43 @@ docker run \
 
 ### PHP Module Management
 
-#### `DISABLEMODULE_[name]`
+#### `PHP_DISABLE_MODULES`
 
-Disable specific PHP modules at runtime. All modules are enabled by default.
+Disable PHP modules when the container starts. A comma or space separated list of module names.
+All modules are enabled by default.
 
 ```bash
 docker run \
-  -e DISABLEMODULE_DOM=true \
-  -e DISABLEMODULE_XSL=true \
+  -e PHP_DISABLE_MODULES="dom,xsl" \
   byjg/php:8.3-cli
 ```
 
+#### `PHP_ENABLED_MODULES`
+
+Disable every module except these, when the container starts. A comma or space separated list of
+module names. The modules they require are kept too: `pdo_mysql` also keeps `pdo`, `mysqlnd` and
+`openssl`.
+
+```bash
+docker run \
+  -e PHP_ENABLED_MODULES="pdo_mysql,mbstring" \
+  byjg/php:8.3-cli
+```
+
+When both are set, `PHP_ENABLED_MODULES` is applied first and `PHP_DISABLE_MODULES` after it, so
+`PHP_ENABLED_MODULES="pdo_mysql,xdebug"` with `PHP_DISABLE_MODULES="xdebug"` keeps only `pdo_mysql`
+and what it requires.
+
+To see the modules that can be disabled in an image, run
+`docker run --rm byjg/php:8.5-cli php-disable-module --list`. To disable modules once, when
+building your own image, use the `php-disable-module` helper instead (see
+[Disabling modules](dockerfile.md#disabling-modules)).
+
+:::warning Deprecated
+`DISABLEMODULE_<name>=true` still works, but it is deprecated and will be removed in a future
+release. Use `PHP_DISABLE_MODULES` instead.
+:::
+
 :::tip
 Disabling unused modules can slightly improve performance and reduce memory footprint.
 :::
diff --git a/docs/security.md b/docs/security.md
index a5d6f57..080ac50 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -167,9 +167,9 @@ repository, which is the only Alpine repository carrying PHP 8.6 packages.
 - Previewing upcoming PHP features
 
 Because PHP 8.6 is only available in `edge/testing`, Alpine has not published every extension
-for it yet. `imagick`, `memcached` and `yaml` are built from a pinned commit of their upstream
-git repositories (see `pecl[].source` in `config/php-8.6.yml`), since their latest PECL releases
-do not compile on PHP 8.6. They are replaced by the Alpine packages as soon as those are published.
+for it yet. `imagick`, `memcached` and `yaml` are built with [PIE](https://github.com/php/pie) from a pinned
+commit of their upstream development branch (see `pie[].package` in `config/php-8.6.yml`), since
+their latest releases do not compile on PHP 8.6. They are replaced by the Alpine packages as soon as those are published.
 `imagick` is compiled but not enabled; see [Imagick on PHP 8.6](dockerfile.md#imagick-on-php-86).
 
 ### Legacy PHP Versions (8.1 and older)
diff --git a/generator/__init__.py b/generator/__init__.py
index b6802cd..60e1d89 100644
--- a/generator/__init__.py
+++ b/generator/__init__.py
@@ -1,4 +1,4 @@
-import os, sys
+import os, re, sys
 import yaml
 from jinja2 import Environment, FileSystemLoader
 from datetime import datetime, date
@@ -33,8 +33,9 @@ def parse_config(self, template, prepared=True):
             # Process each line individually
             processed_lines = []
             for line in output.split('\n'):
-                # Remove trailing comments and strip whitespace
-                processed_line = line.split('#')[0].strip()
+                # Remove comments (a '#' at the start of the line or after a blank) and strip whitespace.
+                # A '#' inside a word is kept, e.g. a PIE constraint like "vendor/ext:dev-master#<commit>"
+                processed_line = re.sub(r'(^|\s)#.*$', '', line).strip()
                 # Keep only non-empty lines
                 if processed_line:
                     processed_lines.append(processed_line)
@@ -109,6 +110,9 @@ def build_base(self):
         self.dockerfile_content["workdir"] += "WORKDIR /srv\n"
         self.dockerfile_content["copy"] += "COPY assets/entrypoint.sh /\n"
         self.dockerfile_content["copy"] += "COPY assets/script/install-sqlsvr.sh /install-sqlsvr.sh\n"
+        self.dockerfile_content["copy"] += "COPY assets/script/php-disable-module.sh /usr/local/bin/php-disable-module\n"
+        if self.build_config.get("pie"):
+            self.dockerfile_content["copy"] += "COPY assets/script/pie-install.sh /usr/local/bin/pie-install\n"
         self.local_base = True
         return self._build()
 
diff --git a/templates/php-base.j2 b/templates/php-base.j2
index ea914db..4d7438e 100644
--- a/templates/php-base.j2
+++ b/templates/php-base.j2
@@ -6,8 +6,10 @@ apk --no-cache {% for rep in repositories %}--repository {{ rep }} {% endfor %}
 (ln -s /usr/bin/pecl{{ version.suffix }} /usr/bin/pecl || true)
 mkdir -p /etc/php/conf.d
 
-# Install PECL and additional packages
-apk --no-cache {% for rep in repositories %}--repository {{ rep }} {% endfor %} add {% for pkg in additionalPackages %}{{ pkg }} {% endfor %}{% for ext in pecl %}{% for pkg in ext.packages | default([]) %}{{ pkg }} {% endfor %}{% endfor %}
+# Install the additional packages
+apk --no-cache {% for rep in repositories %}--repository {{ rep }} {% endfor %} add {% for pkg in additionalPackages %}{{ pkg }} {% endfor %}{% for ext in (pecl | default([])) + (pie | default([])) %}{% for pkg in ext.packages | default([]) %}{{ pkg }} {% endfor %}{% endfor %}
+{% if pecl is defined and pecl %}
+# Install the PECL extensions (PHP versions PIE cannot run on: it needs PHP 8.1+)
 apk --no-cache {% for rep in repositories %}--repository {{ rep }} {% endfor %} add --virtual .build php{{ version.suffix }}-pear php{{ version.suffix }}-dev {% for pkg in peclBuildPackages %}{{ pkg }} {% endfor %}{% for ext in pecl %}{% for pkg in ext.buildPackages | default([]) %}{{ pkg }} {% endfor %}{% endfor %}
 sed -ie "s/ -n / /" /usr/bin/pecl
 {% for ext in pecl -%}
@@ -17,6 +19,26 @@ rm -rf /tmp/pecl-{{ ext.name }}{% else %}yes "" | pecl install {{ ext.name }}{%
 {% if ext.enable is not defined or ext.enable %}printf "{% if ext.zend %}zend_{% endif %}extension={{ ext.name }}.so{% for config in ext.config %}\n{{ config }}{% endfor %}\n" > /etc/php{{ version.suffix }}/conf.d/{{ ext.name }}.ini{% endif %}
 {% endfor %}
 apk del --no-cache .build
+{% endif %}
+{% if pie is defined and pie %}
+{% set pie_version = "1.5.2" %}
+{% set pie_sha256 = "fe70c59738cf56ec00a818cf9cb9593da171aac86f5f1f859995b8839dfd2cc7" %}
+# Install PIE (https://github.com/php/pie) and build the PIE extensions (the build packages are removed at the end)
+wget -q -O /usr/local/bin/pie https://github.com/php/pie/releases/download/{{ pie_version }}/pie.phar
+echo "{{ pie_sha256 }}  /usr/local/bin/pie" | sha256sum -c -
+chmod +x /usr/local/bin/pie /usr/local/bin/pie-install
+apk --no-cache {% for rep in repositories %}--repository {{ rep }} {% endfor %} add --virtual .build php{{ version.suffix }}-dev {% for pkg in pieBuildPackages %}{{ pkg }} {% endfor %}{% for ext in pie %}{% for pkg in ext.buildPackages | default([]) %}{{ pkg }} {% endfor %}{% endfor %}
+{% for ext in pie -%}
+{% if ext.install is not defined or ext.install -%}
+pie install -n "{{ ext.package }}"{% for opt in ext.options | default([]) %} {{ opt }}{% endfor %}{% if ext.enable is defined and not ext.enable %} --skip-enable-extension{% endif %}
+{% if (ext.enable is not defined or ext.enable) and ext.config is defined %}printf "{% for config in ext.config %}{{ config }}\n{% endfor %}" > /etc/php{{ version.suffix }}/conf.d/{{ ext.name }}.ini{% endif %}
+{% elif ext.enable is not defined or ext.enable -%}
+printf "{% if ext.zend %}zend_{% endif %}extension={{ ext.name }}.so{% for config in ext.config | default([]) %}\n{{ config }}{% endfor %}\n" > /etc/php{{ version.suffix }}/conf.d/{{ ext.name }}.ini
+{% endif %}
+{% endfor %}
+apk del --no-cache .build
+rm -rf /root/.pie /root/.composer/cache /tmp/pie_*
+{% endif %}
 
 # Install Composer
 php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
@@ -28,6 +50,6 @@ mv composer.phar /usr/local/bin/composer
 addgroup -S app && adduser -S app -G app
 mkdir -p /srv
 chown -R app:app /srv /etc/php /etc/php{{ version.suffix }} /var/log /tmp /run /entrypoint.sh
-chmod +x /entrypoint.sh
+chmod +x /entrypoint.sh /usr/local/bin/php-disable-module
 
 date > /etc/build-date

From 49ef8adcbf426bf4f58202fdfb666af11e322045 Mon Sep 17 00:00:00 2001
From: Joao Gilberto Magalhaes <joao@byjg.com.br>
Date: Wed, 21 Oct 2026 18:56:11 -0400
Subject: [PATCH 2/2] Disable dependent modules and make module errors
 consistent

- php-disable-module also disables the modules that require a disabled one
  (e.g. dom also disables xmlreader and xsl)
- Find a module by the extension line of its ini file, not the file name
- A module already disabled is not an error, so it is safe to run again
  (fixes a container that failed on restart with PHP_ENABLED_MODULES)
- Both PHP_DISABLE_MODULES and PHP_ENABLED_MODULES always show errors and
  stop the container; the deprecated DISABLEMODULE_<name> only warns
- Check that PHP starts cleanly after disabling, in both modes
- Clean up shellcheck warnings in php-disable-module and entrypoint.sh
- Fix the docs saying which PHP versions use PIE
---
 assets/entrypoint.sh                |  63 ++++---
 assets/script/php-disable-module.sh | 264 +++++++++++++++++++---------
 docs/building.md                    |   2 +-
 docs/dockerfile.md                  |  18 +-
 docs/environment.md                 |   7 +-
 5 files changed, 228 insertions(+), 126 deletions(-)

diff --git a/assets/entrypoint.sh b/assets/entrypoint.sh
index f27315f..76a5928 100755
--- a/assets/entrypoint.sh
+++ b/assets/entrypoint.sh
@@ -16,7 +16,7 @@ then
     echo "       |___/               "
     echo
     echo "Image: $DOCKER_IMAGE"
-    echo "Build Date: `cat /etc/build-date`"
+    echo "Build Date: $(cat /etc/build-date)"
     echo
 fi
 
@@ -24,52 +24,51 @@ fi
 if [[ -f /usr/bin/php ]]
 then
   # Getting PHP INI Paths
-  PHPINI=`php -i | grep "Loaded Configuration File" | awk -F" => " '{print $2}'`
-  PHPMODULES=`php -i | grep "Scan this dir" |  awk -F" => " '{print $2}'`
+  PHPMODULES=$(php -i | grep "Scan this dir" |  awk -F" => " '{print $2}')
   PHPCUSTOM=/etc/php/conf.d
 
+  # Errors are always shown and stop the container; VERBOSE only shows the modules disabled.
+  # A module already disabled (e.g. after a restart) is not an error.
+  MODULE_OUTPUT=/dev/null
+  ${VERBOSE_MODE} && MODULE_OUTPUT=/dev/stdout
+
   # Keep only these modules (and the ones they require): PHP_ENABLED_MODULES="pdo_mysql,mbstring"
-  ENABLED_MODULES=`echo "$PHP_ENABLED_MODULES" | tr ',' ' '`
-  if [[ -n "${ENABLED_MODULES// /}" ]]
+  read -r -a ENABLED_MODULES <<< "${PHP_ENABLED_MODULES//,/ }"
+  if [[ ${#ENABLED_MODULES[@]} -gt 0 ]]
   then
-      if ${VERBOSE_MODE}
+      if ! /usr/local/bin/php-disable-module --all-except "${ENABLED_MODULES[@]}" > "$MODULE_OUTPUT"
       then
-          /usr/local/bin/php-disable-module --all-except $ENABLED_MODULES
-      else
-          /usr/local/bin/php-disable-module --all-except $ENABLED_MODULES > /dev/null
+          echo "PHP_ENABLED_MODULES=\"$PHP_ENABLED_MODULES\" failed (see above), stopping the container." >&2
+          exit 1
       fi
   fi
 
-  # Disable modules: PHP_DISABLE_MODULES="yaml,memcached" (comma or space separated)
-  DISABLE_MODULES=`echo "$PHP_DISABLE_MODULES" | tr ',' ' '`
-
-  # Deprecated: DISABLEMODULE_<module>=true, will be removed in a future release
-  DEPRECATED_MODULES=`printenv | grep -E '^DISABLEMODULE_[^=]+=(true|yes|1)$' | cut -d= -f1 | cut -d_ -f2-`
-  if [[ -n "$DEPRECATED_MODULES" ]]
+  # Disable modules (and the ones that require them): PHP_DISABLE_MODULES="yaml,memcached"
+  read -r -a DISABLE_MODULES <<< "${PHP_DISABLE_MODULES//,/ }"
+  if [[ ${#DISABLE_MODULES[@]} -gt 0 ]]
   then
-      echo "DISABLEMODULE_<module> is deprecated, use PHP_DISABLE_MODULES=\"`echo $DEPRECATED_MODULES | tr '[:upper:] ' '[:lower:],'`\"" >&2
-      DISABLE_MODULES="$DISABLE_MODULES $DEPRECATED_MODULES"
+      if ! /usr/local/bin/php-disable-module "${DISABLE_MODULES[@]}" > "$MODULE_OUTPUT"
+      then
+          echo "PHP_DISABLE_MODULES=\"$PHP_DISABLE_MODULES\" failed (see above), stopping the container." >&2
+          exit 1
+      fi
   fi
 
-  if [[ -n "${DISABLE_MODULES// /}" ]]
+  # Deprecated: DISABLEMODULE_<module>=true, will be removed in a future release. It does not stop
+  # the container on an error, as it did not before.
+  mapfile -t DEPRECATED_MODULES < <(printenv | grep -E '^DISABLEMODULE_[^=]+=(true|yes|1)$' | cut -d= -f1 | cut -d_ -f2- | awk '{print tolower($0)}')
+  if [[ ${#DEPRECATED_MODULES[@]} -gt 0 ]]
   then
-      if ${VERBOSE_MODE}
-      then
-          /usr/local/bin/php-disable-module $DISABLE_MODULES
-          echo
-      else
-          /usr/local/bin/php-disable-module $DISABLE_MODULES > /dev/null
-      fi
+      echo "DISABLEMODULE_<module> is deprecated, use PHP_DISABLE_MODULES=\"$(IFS=,; echo "${DEPRECATED_MODULES[*]}")\"" >&2
+      /usr/local/bin/php-disable-module "${DEPRECATED_MODULES[@]}" > "$MODULE_OUTPUT"
   fi
 
-  # List available modules
-  if [[ "$VERBOSE" == "true" ]]
+  # List the enabled modules
+  if ${VERBOSE_MODE}
   then
+      echo
       echo "Available Modules:"
-      for VAR in `ls $PHPMODULES/ | sort`
-      do
-          echo $VAR | awk -F"." '{printf $1; printf " "}'
-      done
+      /usr/local/bin/php-disable-module --list | tr '\n' ' '
       echo
   fi
 
@@ -80,7 +79,7 @@ then
   fi
 
   # Copy Custom Config
-  cp $PHPCUSTOM/*.ini $PHPMODULES/ 2>/dev/null || :
+  cp "$PHPCUSTOM"/*.ini "$PHPMODULES"/ 2>/dev/null || :
 fi
 
 exec "$@"
diff --git a/assets/script/php-disable-module.sh b/assets/script/php-disable-module.sh
index b2626a7..053e036 100755
--- a/assets/script/php-disable-module.sh
+++ b/assets/script/php-disable-module.sh
@@ -12,53 +12,175 @@
 #   php-disable-module xdebug memcached
 #   php-disable-module --all-except pdo_mysql mbstring
 #
-# The ini file can be "<module>.ini" or have a numeric priority prefix: "70_yaml.ini" (apk),
-# "80-yaml.ini" (PIE). Exits with 1 if any module was not found.
+# The module is found by the extension line of its ini file, whatever the file name:
+# "70_yaml.ini" (apk), "80-yaml.ini" (PIE). A module already disabled is not an error, so it is
+# safe to run again. Exits with 1 if any module was not found.
 #
-# --all-except also keeps the modules the given ones require (e.g. pdo_mysql keeps pdo and
-# mysqlnd), and exits with 1 if PHP does not start cleanly afterwards.
+# The modules that require a disabled one are disabled too (e.g. dom also disables xmlreader
+# and xsl). --all-except keeps the modules the given ones require (e.g. pdo_mysql keeps pdo and
+# mysqlnd). Both exit with 1 if PHP does not start cleanly afterwards.
 #
 
 if [[ -z "$1" ]]; then
-    sed -n '3,19p' "$0" | sed 's/^# \{0,1\}//'
+    sed -n '3,21p' "$0" | sed 's/^# \{0,1\}//'
     exit 1
 fi
 
-PHPMODULES=`php -i | grep "Scan this dir" | awk -F" => " '{print $2}'`
+PHPMODULES=$(php -i | grep "Scan this dir" | awk -F" => " '{print $2}')
+EXTENSION_DIR=$(php -r 'echo ini_get("extension_dir");')
+LOADED=" $(php -m 2>/dev/null | awk '{print tolower($0)}' | tr '\n' ' ') "
+
+# "<module> <ini file>" for each ini file in the scan directory that loads a module. The module
+# comes from the extension line, not the file name: "30_sqlsvr.ini" loads pdo_sqlsrv.
+module_inis() {
+    local FILE
+    for FILE in "$PHPMODULES"/*.ini
+    do
+        [[ -f "$FILE" ]] || continue
+        grep -E '^\s*(zend_)?extension\s*=' "$FILE" \
+            | sed -E 's/^[^=]*=\s*"?([^";[:space:]]*).*/\1/; s|.*/||; s/\.so$//' \
+            | awk -v f="${FILE##*/}" '{print tolower($0), f}'
+    done
+}
 
 # A module can be disabled when an ini file in the scan directory loads it
 list_modules() {
-    (cd "$PHPMODULES" && grep -l -E '^\s*(zend_)?extension\s*=' *.ini 2>/dev/null) \
-        | sed -E 's/^[0-9]+[_-]//; s/\.ini$//' | sort -u
+    module_inis | awk '{print $1}' | sort -u
+}
+
+# The ini files of a module: the ones that load it, plus "<module>.ini" or "70_<module>.ini"
+# that only have its settings
+module_files() {
+    local FILE
+    {
+        module_inis | awk -v m="$1" '$1 == m {print $2}'
+        for FILE in "$PHPMODULES"/*.ini
+        do
+            [[ "${FILE##*/}" =~ ^([0-9]+[_-])?"$1"\.ini$ ]] && echo "${FILE##*/}"
+        done
+    } | sort -u
 }
 
-# The modules a module requires: the ones PHP declares, plus the apk package dependencies, which
-# also list libraries PHP does not declare (e.g. mysqlnd needs openssl). A module PIE built has no
-# apk package, so only what PHP declares is known for it.
-requires() {
-    php -r '
-        if (extension_loaded($argv[1])) {
-            foreach ((new ReflectionExtension($argv[1]))->getDependencies() as $dep => $type) {
-                if ($type === "Required") {
-                    echo strtolower($dep), "\n";
-                }
+# enabled:  an ini file loads it
+# builtin:  compiled into PHP (e.g. json, spl), it has no ini file and cannot be disabled
+# disabled: its library is installed but no ini file loads it (e.g. a previous run disabled it)
+# missing:  not in this image
+module_state() {
+    if module_inis | awk -v m="$1" '$1 == m {found = 1} END {exit !found}'; then
+        echo enabled
+    elif [[ "$LOADED" == *" $1 "* ]]; then
+        echo builtin
+    elif [[ -f "$EXTENSION_DIR/$1.so" ]]; then
+        echo disabled
+    else
+        echo missing
+    fi
+}
+
+# The apk packages that installed the ini files of a module (none for a module PIE built)
+module_packages() {
+    local FILE
+    for FILE in $(module_files "$1")
+    do
+        apk info -W "$PHPMODULES/$FILE" 2>/dev/null | awk '/is owned by/ {print $NF}' | sed -E 's/-[0-9][^-]*-r[0-9]+$//'
+    done | sort -u
+}
+
+# The enabled modules of the PHP packages apk relates to a module: "-R" the packages it depends on,
+# "-r" the packages that depend on it
+apk_modules() {
+    local PACKAGES PACKAGE INI
+    mapfile -t PACKAGES < <(module_packages "$2")
+    [[ ${#PACKAGES[@]} -eq 0 ]] && return
+    for PACKAGE in $(apk info "$1" "${PACKAGES[@]}" 2>/dev/null | grep -v ':$' | grep -E '^php[0-9]*-' | sed -E 's/[<>=~].*//; s/-[0-9][^-]*-r[0-9]+$//')
+    do
+        for INI in $(apk info -L "$PACKAGE" 2>/dev/null | grep -E "/conf\.d/[^/]+\.ini$" | sed -E 's|.*/||')
+        do
+            module_inis | awk -v f="$INI" '$2 == f {print $1}'
+        done
+    done
+}
+
+# "<module> <module it requires>" for every loaded module, as PHP declares it
+# shellcheck disable=SC2016 # the $ belong to the PHP code
+PHP_DEPENDENCIES=$(php -r '
+    foreach (get_loaded_extensions() as $ext) {
+        foreach ((new ReflectionExtension($ext))->getDependencies() as $dep => $type) {
+            if ($type === "Required") {
+                echo strtolower($ext), " ", strtolower($dep), "\n";
             }
         }
-    ' -- "$1" 2>/dev/null
+    }
+' 2>/dev/null)
 
-    local FILE PACKAGE DEP
-    for FILE in `ls "$PHPMODULES" | grep -E "^([0-9]+[_-])?${1}\.ini$"`
+# --requires: the modules a module requires. The ones PHP declares, plus the apk package
+# dependencies, which also list libraries PHP does not declare (e.g. mysqlnd needs openssl).
+# --required-by: the enabled modules that require a module (e.g. xmlreader and xsl require dom).
+# A module PIE built has no apk package, so only what PHP declares is known for it.
+related() {
+    case "$1" in
+        --requires)
+            echo "$PHP_DEPENDENCIES" | awk -v m="$2" '$1 == m {print $2}'
+            apk_modules -R "$2"
+            ;;
+        --required-by)
+            echo "$PHP_DEPENDENCIES" | awk -v m="$2" '$2 == m {print $1}'
+            apk_modules -r "$2"
+            ;;
+    esac
+}
+
+# "<module> <the module that added it>" for the given modules and every one related to them
+# (--requires or --required-by), until no new one shows up
+closure() {
+    local DIRECTION=$1 ALL MODULE DEP
+    local -a QUEUE NEXT
+    shift
+    [[ $# -eq 0 ]] && return
+    ALL=" $* "
+    QUEUE=("$@")
+    printf '%s\n' "$@"
+    while [[ ${#QUEUE[@]} -gt 0 ]]
     do
-        PACKAGE=`apk info -W "$PHPMODULES/$FILE" 2>/dev/null | awk '/is owned by/ {print $NF}' | sed -E 's/-[0-9][^-]*-r[0-9]+$//'`
-        [[ -z "$PACKAGE" ]] && continue
-        for DEP in `apk info -R "$PACKAGE" 2>/dev/null | grep -v 'depends on' | grep -E '^php[0-9]*-'`
+        NEXT=()
+        for MODULE in "${QUEUE[@]}"
         do
-            apk info -L "$DEP" 2>/dev/null | grep -E "/conf\.d/[^/]+\.ini$" \
-                | sed -E 's|.*/||; s/^[0-9]+[_-]//; s/\.ini$//'
+            for DEP in $(related "$DIRECTION" "$MODULE")
+            do
+                if [[ "$ALL" != *" $DEP "* ]]; then
+                    ALL="$ALL$DEP "
+                    NEXT+=("$DEP")
+                    echo "$DEP $MODULE"
+                fi
+            done
         done
+        QUEUE=("${NEXT[@]}")
     done
 }
 
+disable_module() {
+    local FILE
+    for FILE in $(module_files "$1")
+    do
+        rm -f "${PHPMODULES:?}/$FILE"
+    done
+}
+
+# A module can need another one neither PHP nor apk declares; it then fails to load
+check_php() {
+    local ERRORS
+    ERRORS=$(php -v 2>&1 | grep -E 'Warning|Fatal error')
+    if [[ -n "$ERRORS" ]]; then
+        echo "PHP does not start cleanly after disabling the modules:" >&2
+        echo "$ERRORS" >&2
+        exit 1
+    fi
+}
+
+lowercase() {
+    printf '%s\n' "$@" | awk 'NF {print tolower($0)}'
+}
+
 if [[ "$1" == "--list" ]]; then
     list_modules
     exit 0
@@ -66,78 +188,54 @@ fi
 
 if [[ "$1" == "--all-except" ]]; then
     shift
-    AVAILABLE=" `list_modules | tr '\n' ' '` "
-    LOADED=" `php -m 2>/dev/null | awk '{print tolower($0)}' | tr '\n' ' '` "
-
-    KEEP=""
-    for MODULE in "$@"
+    KEEP=()
+    for MODULE in $(lowercase "$@")
     do
-        MODULE=`echo "$MODULE" | awk '{print tolower($0)}'`
-        # A module compiled into PHP (e.g. json, spl) has no ini file and is always enabled
-        if [[ "$AVAILABLE" != *" $MODULE "* && "$LOADED" != *" $MODULE "* ]]; then
-            echo "Module not found: $MODULE" >&2
-            exit 1
-        fi
-        KEEP="$KEEP $MODULE"
+        case $(module_state "$MODULE") in
+            missing)  echo "Module not found: $MODULE" >&2; exit 1 ;;
+            disabled) echo "Module already disabled: $MODULE" ;;
+        esac
+        KEEP+=("$MODULE")
     done
 
-    # Add the modules they require, until no new one shows up
-    QUEUE="$KEEP"
-    while [[ -n "${QUEUE// /}" ]]
-    do
-        NEXT=""
-        for MODULE in $QUEUE
-        do
-            for DEP in `requires "$MODULE"`
-            do
-                if [[ " $KEEP " != *" $DEP "* ]]; then
-                    KEEP="$KEEP $DEP"
-                    NEXT="$NEXT $DEP"
-                fi
-            done
-        done
-        QUEUE="$NEXT"
-    done
+    KEEP_ALL=" $(closure --requires "${KEEP[@]}" | awk '{print $1}' | tr '\n' ' ') "
     KEPT=""
-    DISABLE=""
-    for MODULE in $AVAILABLE
+    for MODULE in $(list_modules)
     do
-        if [[ " $KEEP " == *" $MODULE "* ]]; then
+        if [[ "$KEEP_ALL" == *" $MODULE "* ]]; then
             KEPT="$KEPT $MODULE"
         else
-            DISABLE="$DISABLE $MODULE"
+            echo "Disabling module $MODULE ..."
+            disable_module "$MODULE"
         fi
     done
     echo "Keeping modules:$KEPT"
-    [[ -n "$DISABLE" ]] && "$0" $DISABLE
-
-    # A module can need another one PHP does not declare; it then fails to load
-    ERRORS=`php -v 2>&1 | grep -E 'Warning|Fatal error'`
-    if [[ -n "$ERRORS" ]]; then
-        echo "PHP does not start cleanly after disabling the modules:" >&2
-        echo "$ERRORS" >&2
-        exit 1
-    fi
+    check_php
     exit 0
 fi
 
 STATUS=0
-for MODULE in "$@"
+DISABLE=()
+for MODULE in $(lowercase "$@")
 do
-    MODULE=`echo "$MODULE" | awk '{print tolower($0)}'`
-    MODULE_FILES=`ls "$PHPMODULES" | grep -E "^([0-9]+[_-])?${MODULE}\.ini$"`
-    if [[ -z "$MODULE_FILES" ]]
-    then
-        echo "Module not found: $MODULE" >&2
-        STATUS=1
-        continue
-    fi
-
-    echo "Disabling module $MODULE ..."
-    for FILE in $MODULE_FILES
-    do
-        rm -f "$PHPMODULES/$FILE"
-    done
+    case $(module_state "$MODULE") in
+        enabled)  DISABLE+=("$MODULE") ;;
+        disabled) echo "Module already disabled: $MODULE" ;;
+        builtin)  echo "Module compiled into PHP, it cannot be disabled: $MODULE" >&2; STATUS=1 ;;
+        missing)  echo "Module not found: $MODULE" >&2; STATUS=1 ;;
+    esac
 done
 
+# The modules that require a disabled one can no longer load: disable them too
+while read -r MODULE REQUIRED
+do
+    if [[ -n "$REQUIRED" ]]; then
+        echo "Disabling module $MODULE (requires $REQUIRED) ..."
+    else
+        echo "Disabling module $MODULE ..."
+    fi
+    disable_module "$MODULE"
+done < <(closure --required-by "${DISABLE[@]}")
+
+check_php
 exit $STATUS
diff --git a/docs/building.md b/docs/building.md
index 75c32ca..bcb79ce 100644
--- a/docs/building.md
+++ b/docs/building.md
@@ -138,7 +138,7 @@ extensions:
 
 # The extensions installed with PIE (https://github.com/php/pie), the PHP Foundation's
 # replacement for PECL. Prefer the Alpine package in `extensions` when there is one.
-# PIE needs PHP 8.1 or later: the configs of PHP 5.6 to 7.3 keep `pecl:` (see below).
+# PIE needs PHP 8.1 or later. The configs of PHP 8.3+ use `pie:`; the older ones keep `pecl:` (see below).
 pie:
   - name: imagick                   # required - the extension name (used for the .ini file)
     package: imagick/imagick        # required unless `install: False` - the PIE (Packagist) package,
diff --git a/docs/dockerfile.md b/docs/dockerfile.md
index a3da809..c908359 100644
--- a/docs/dockerfile.md
+++ b/docs/dockerfile.md
@@ -90,7 +90,7 @@ Always switch back to the `app` user after installing packages. Running your app
 ### Installing a PHP Extension with PIE
 
 If the extension has no Alpine package (`apk search phpXY-pecl-<name>`), install it with
-[PIE](https://github.com/php/pie), the PHP Foundation's replacement for PECL. The images ship
+[PIE](https://github.com/php/pie), the PHP Foundation's replacement for PECL. The PHP 8.3+ images ship
 `pie` and the `pie-install` helper; `pie-install` adds the compiler and the `phpXY-dev` package,
 runs `pie install`, enables the extension and removes the build tools again, so they do not stay
 in your image. It must run as `root`:
@@ -156,9 +156,14 @@ FROM byjg/php:8.5-cli
 RUN php-disable-module xdebug soap ftp
 ```
 
-It finds the ini file whatever its name: `<module>.ini`, or with a priority prefix such as
-`70_yaml.ini` (apk) or `80-yaml.ini` (PIE). It exits with an error if a module is not found, so a
-typo fails the build.
+It finds the module by the extension line of its ini file, whatever the file name: `70_yaml.ini`
+(apk) or `80-yaml.ini` (PIE). It exits with an error if a module is not found, so a typo fails the
+build; a module already disabled (e.g. by the base image) is not an error.
+
+The modules that require a disabled one are disabled too, since they can no longer load:
+`php-disable-module pdo` also disables `pdo_mysql`, `pdo_pgsql`, `pdo_sqlite` and `pdo_dblib`, and
+prints each one with the module it requires. Afterwards it starts PHP once and fails if a module
+does not load.
 
 To keep only some modules and disable all the others, use `--all-except`:
 
@@ -178,11 +183,6 @@ The modules that can be disabled vary a little by PHP version. List them with:
 docker run --rm byjg/php:8.5-cli php-disable-module --list
 ```
 
-:::note
-Some modules depend on others. Disabling `pdo` without the `pdo_*` drivers makes PHP print a
-startup warning for each driver: disable them together.
-:::
-
 To disable modules when the container starts instead, set
 [`PHP_DISABLE_MODULES`](environment.md#php_disable_modules) or
 [`PHP_ENABLED_MODULES`](environment.md#php_enabled_modules).
diff --git a/docs/environment.md b/docs/environment.md
index 9027f06..ff822f3 100644
--- a/docs/environment.md
+++ b/docs/environment.md
@@ -65,7 +65,8 @@ docker run \
 #### `PHP_DISABLE_MODULES`
 
 Disable PHP modules when the container starts. A comma or space separated list of module names.
-All modules are enabled by default.
+All modules are enabled by default. The modules that require a disabled one are disabled too:
+`dom` also disables `xmlreader` and `xsl`.
 
 ```bash
 docker run \
@@ -85,6 +86,10 @@ docker run \
   byjg/php:8.3-cli
 ```
 
+For both variables, if a module is not found, or PHP does not start cleanly afterwards, the
+container stops with an error instead of running with the wrong modules. A module already disabled,
+e.g. after `docker restart`, is not an error. `VERBOSE=true` also shows each module disabled.
+
 When both are set, `PHP_ENABLED_MODULES` is applied first and `PHP_DISABLE_MODULES` after it, so
 `PHP_ENABLED_MODULES="pdo_mysql,xdebug"` with `PHP_DISABLE_MODULES="xdebug"` keeps only `pdo_mysql`
 and what it requires.