feat(v2): Migrate Debian base from Bookworm to Trixie with backward-compatible tags

.github/workflows/docker-ci.yml

@@ -42,6 +42,35 @@ jobs:
         exclude:
           - php-type: apache
             php-base: alpine
+          # v2 uses trixie as the Debian base; bookworm retained for v1
+          - variant: v2
+            php-base: bookworm
+        include:
+          # v2 builds on trixie for Debian images
+          - variant: v2
+            php-version: '8.4'
+            php-type: fpm
+            php-base: trixie
+          - variant: v2
+            php-version: '8.4'
+            php-type: cli
+            php-base: trixie
+          - variant: v2
+            php-version: '8.3'
+            php-type: fpm
+            php-base: trixie
+          - variant: v2
+            php-version: '8.3'
+            php-type: cli
+            php-base: trixie
+          - variant: v2
+            php-version: '8.2'
+            php-type: fpm
+            php-base: trixie
+          - variant: v2
+            php-version: '8.2'
+            php-type: cli
+            php-base: trixie
 
     name: ${{ matrix.variant }}-${{ matrix.php-version }}-${{ matrix.php-type }}-${{ matrix.php-base }}
 
@@ -244,6 +273,47 @@ jobs:
         exclude:
           - php-type: apache
             php-base: alpine
+          # v2 uses trixie as the Debian base; bookworm retained for v1
+          - variant: v2
+            php-base: bookworm
+        include:
+          # v2 builds on trixie for Debian images
+          - variant: v2
+            php-version: '8.4'
+            php-type: fpm
+            php-base: trixie
+          - variant: v2
+            php-version: '8.4'
+            php-type: cli
+            php-base: trixie
+          - variant: v2
+            php-version: '8.4'
+            php-type: apache
+            php-base: trixie
+          - variant: v2
+            php-version: '8.3'
+            php-type: fpm
+            php-base: trixie
+          - variant: v2
+            php-version: '8.3'
+            php-type: cli
+            php-base: trixie
+          - variant: v2
+            php-version: '8.3'
+            php-type: apache
+            php-base: trixie
+          - variant: v2
+            php-version: '8.2'
+            php-type: fpm
+            php-base: trixie
+          - variant: v2
+            php-version: '8.2'
+            php-type: cli
+            php-base: trixie
+          - variant: v2
+            php-version: '8.2'
+            php-type: apache
+            php-base: trixie
 
     name: publish-${{ matrix.variant }}-${{ matrix.php-version }}-${{ matrix.php-type }}-${{ matrix.php-base }}
 
@@ -318,6 +388,30 @@ jobs:
             ${{ steps.vars.outputs.GHCR_TAG }}
             ${{ steps.vars.outputs.QUAY_TAG }}
 
+      - name: Create bookworm compatibility tag for v2 trixie images
+        if: matrix.variant == 'v2' && matrix.php-base == 'trixie'
+        run: |
+          echo "::group::Creating bookworm compatibility tags for trixie-built v2 image"
+
+          # Replace 'trixie' with 'bookworm' in tag names to maintain backward compatibility
+          BOOKWORM_VERSION="${{ matrix.php-version }}-${{ matrix.php-type }}-bookworm"
+
+          # Create manifest aliases pointing trixie-built images to bookworm tags
+          docker buildx imagetools create -t \
+            docker.io/${{ secrets.DOCKERHUB_USERNAME }}/php-docker:${BOOKWORM_VERSION}-v2 \
+            ${{ steps.vars.outputs.DOCKERHUB_TAG }}
+
+          docker buildx imagetools create -t \
+            ghcr.io/kingpin/php-docker:${BOOKWORM_VERSION}-v2 \
+            ${{ steps.vars.outputs.GHCR_TAG }}
+
+          docker buildx imagetools create -t \
+            quay.io/kingpinx1/php-docker:${BOOKWORM_VERSION}-v2 \
+            ${{ steps.vars.outputs.QUAY_TAG }}
+
+          echo "✅ Created bookworm compatibility tags pointing to trixie image"
+          echo "::endgroup::"
+
       - name: Run Trivy vulnerability scanner
         uses: aquasecurity/trivy-action@master
         with:

.github/workflows/docker-image.v2.yml

@@ -41,7 +41,7 @@ jobs:
           echo '{
             "php-version": ["8.1", "8.2", "8.3", "8.4"],
             "php-type": ["cli", "fpm", "apache"],
-            "php-base-os": ["bookworm", "alpine"],
+            "php-base-os": ["trixie", "alpine"],
             "exclude": [
               {"php-type": "apache", "php-base-os": "alpine"}
             ]
@@ -135,8 +135,10 @@ jobs:
             # Regular version tags 
             ADDITIONAL_TAGS="${MAJOR_VERSION}-${{ matrix.php-type }}-${{ matrix.php-base-os }},${MINOR_VERSION}-${{ matrix.php-type }}-${{ matrix.php-base-os }}"
 
-            # Add bullseye-compatible tags for bookworm images
-            if [[ "${{ matrix.php-base-os }}" == "bookworm" ]]; then
+            # Add bookworm compatibility tags for trixie images (backward compatibility)
+            # Also add bullseye tags for transition compatibility
+            if [[ "${{ matrix.php-base-os }}" == "trixie" ]]; then
+              ADDITIONAL_TAGS="${ADDITIONAL_TAGS},${{ matrix.php-version }}-${{ matrix.php-type }}-bookworm,${MAJOR_VERSION}-${{ matrix.php-type }}-bookworm,${MINOR_VERSION}-${{ matrix.php-type }}-bookworm"
               ADDITIONAL_TAGS="${ADDITIONAL_TAGS},${{ matrix.php-version }}-${{ matrix.php-type }}-bullseye,${MAJOR_VERSION}-${{ matrix.php-type }}-bullseye,${MINOR_VERSION}-${{ matrix.php-type }}-bullseye"
             fi
 

Dockerfile.v2

@@ -11,8 +11,7 @@ ENV DEBIAN_FRONTEND=noninteractive
 # Install dependencies based on the base OS with BuildKit cache mounts
 RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
     --mount=type=cache,target=/var/lib/apt,sharing=locked \
-    if [ "$BASEOS" = "bookworm" ]; then \
-        echo 'deb http://deb.debian.org/debian bookworm main' > /etc/apt/sources.list && \
+    if [ "$BASEOS" = "trixie" ] || [ "$BASEOS" = "bookworm" ]; then \
         apt-get update && \
         apt-get -y upgrade && \
         apt-get install -y --no-install-recommends \
@@ -86,7 +85,7 @@ ARG TARGETARCH
 COPY --from=builder /usr/local/ /usr/local/
 
 # Install S6 Overlay init system
-RUN if [ "$BASEOS" = "bookworm" ]; then \
+RUN if [ "$BASEOS" = "trixie" ] || [ "$BASEOS" = "bookworm" ]; then \
         apt-get update && \
         apt-get install -y --no-install-recommends \
             xz-utils \
@@ -122,28 +121,28 @@ RUN if [ "$BASEOS" = "bookworm" ]; then \
     fi
 
 # Install required system libraries based on OS
-RUN if [ "$BASEOS" = "bookworm" ]; then \
+RUN if [ "$BASEOS" = "trixie" ] || [ "$BASEOS" = "bookworm" ]; then \
         apt-get update && \
         apt-get install -y --no-install-recommends \
             librabbitmq4 \
-            libpng16-16 \
-            libmagickwand-6.q16-6 \
-            libc-client2007e \
+            libpng16-16t64 \
+            libmagickwand-7.q16-10\
+            # libc-client2007e \
             libsnappy1v5 \
             libpq5 \
-            libsnmp40 \
-            libtidy5deb1 \
-            libvips42 \
+            libsnmp40t64 \
+            libtidy58 \
+            libvips42t64 \
             libxslt1.1 \
             libyaml-0-2 \
-            libzip4 \
-            libmemcached11 \
+            libzip5 \
+            libmemcached11t64 \
             ghostscript \
             imagemagick \
             libwebp7 \
-            libavif15 \
-            libicu72 \
-            libldap-2.5-0 \
+            libavif16 \
+            libicu76 \
+            libldap2 \
             libuuid1 \
             libxpm4 && \
         rm -rf /var/lib/apt/lists/*; \
@@ -221,7 +220,7 @@ RUN chmod -R 755 /etc/cont-init.d /etc/services.d && \
     mkdir -p /var/run/s6 && \
     chmod -R 755 /var/run/s6 && \
     # Make sure scripts are executable and have correct line endings
-    if [ "$BASEOS" = "bookworm" ]; then \
+    if [ "$BASEOS" = "trixie" ] || [ "$BASEOS" = "bookworm" ]; then \
         apt-get update && \
         apt-get install -y --no-install-recommends dos2unix && \
         dos2unix /etc/cont-init.d/* /etc/services.d/php/* && \

README.md

@@ -19,45 +19,52 @@ See [v1 vs v2 comparison](#v1-vs-v2-comparison) below for details.
 - **Multi-Architecture Support**: Works on `amd64`, `arm64/aarch64` and `arm32v7/armhf` platforms
 - **Multiple PHP Versions**: PHP 8.2, 8.3, and 8.4 (actively built); PHP 7.x, 8.0, and 8.1 deprecated
 - **Multiple Server Types**: CLI, FPM, and Apache
-- **Base OS Options**: Alpine (lightweight) and Debian (Bookworm/Bullseye)
+- **Base OS Options**: Alpine (lightweight) and Debian (v1: Bookworm, v2: Trixie with Bookworm-compatible tags)
 - **Extensive Extensions**: 30+ PHP extensions pre-installed
 - **Latest Composer**: Always ships with the latest Composer version
 - **Image Processing Tools**: Includes ImageMagick, GD, and various image optimization utilities
 - **Apache Mods**: Includes Apache rewrite module (for Apache variants)
 - **v2: s6-overlay init**: Proper PID 1 and service supervision for reliable multi-process containers
 
+> **ℹ️ Base OS Update (v2 only)**: v2 Debian images now use **Debian Trixie** as the base OS (following upstream PHP official images). For backward compatibility, `:bookworm` tags continue to work and point to the same Trixie-built images. v1 images remain on Bookworm. [See migration notes](docs/migration.md#debian-trixie-migration-v2-only) for details.
+
 ## Environment Variables
 
 The following environment variables can be overridden when running containers:
 
 ### Memory Settings
+
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `PHP_MEMORY_LIMIT` | `256M` | Maximum memory a script can consume |
 | `PHP_OPCACHE_MEMORY_CONSUMPTION` | `128` | OPCache memory consumption limit |
 | `PHP_OPCACHE_INTERNED_STRINGS_BUFFER` | `16` | OPCache interned strings buffer |
 
 ### Upload Settings
+
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `PHP_UPLOAD_MAX_FILESIZE` | `64M` | Maximum allowed size for uploaded files |
 | `PHP_POST_MAX_SIZE` | `64M` | Maximum size of POST data allowed |
 | `PHP_MAX_FILE_UPLOADS` | `20` | Maximum number of files allowed for upload |
 
 ### Execution Settings
+
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `PHP_MAX_EXECUTION_TIME` | `300` | Maximum execution time of scripts (seconds) |
 | `PHP_MAX_INPUT_VARS` | `1000` | Maximum input variables allowed |
 
 ### Error Handling
+
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `PHP_ERROR_REPORTING` | `E_ALL` | Error reporting level |
 | `PHP_DISPLAY_ERRORS` | `Off` | Display errors in output |
 | `PHP_LOG_ERRORS` | `On` | Log errors to error log |
 
 ### Other Settings
+
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `PHP_DATE_TIMEZONE` | `UTC` | Default timezone |
@@ -137,14 +144,15 @@ We maintain **two image variants** to support both existing users and modern use
 
 ### v2 (Modern) - Tags with `-v2` suffix
 
-**Purpose:** Modernized image with s6-overlay for proper init and service supervision.
+**Purpose:** Modernized image with s6-overlay for proper init and service supervision, built on latest Debian Trixie.
 
 **Key Characteristics:**
 
 - Uses [s6-overlay](https://github.com/just-containers/s6-overlay) as PID 1 init
 - Proper signal handling and zombie process reaping
 - Service supervision and restart policies
 - BuildKit-enabled for better build performance and caching
+- Built on Debian Trixie (`:trixie` tags) with `:bookworm` compatibility aliases
 
 **Pros:**