From 6a0865f4af3c52dcfab3c4d96eeb6382c4549453 Mon Sep 17 00:00:00 2001
From: KingPin <28669+KingPin@users.noreply.github.com>
Date: Sat, 16 May 2026 23:34:57 -0400
Subject: [PATCH 01/10] feat: add PHP 8.5 to build matrix

PHP 8.5.0 was released 2025-11-20. Add it alongside 8.2/8.3/8.4 in the
push, PR fast-path (newest+oldest = 8.5+8.2), and publish matrices,
including the v2 trixie includes. README tags table updated.
---
 .github/workflows/docker-ci.yml | 20 ++++++++++++++++----
 README.md                       |  7 ++++++-
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/docker-ci.yml b/.github/workflows/docker-ci.yml
index 54285ea..9dd5a8e 100644
--- a/.github/workflows/docker-ci.yml
+++ b/.github/workflows/docker-ci.yml
@@ -40,10 +40,10 @@ jobs:
         id: matrix
         run: |
           if [ "${{ github.event_name }}" = "pull_request" ]; then
-            PHP_VERSIONS='["8.4","8.2"]'
-            echo "::notice::PR detected — testing PHP 8.4 + 8.2 only (skipping 8.3)"
+            PHP_VERSIONS='["8.5","8.2"]'
+            echo "::notice::PR detected — testing PHP 8.5 + 8.2 only (skipping 8.4 and 8.3)"
           else
-            PHP_VERSIONS='["8.4","8.3","8.2"]'
+            PHP_VERSIONS='["8.5","8.4","8.3","8.2"]'
           fi
 
           # Build trixie include list for v2 based on selected PHP versions
@@ -301,7 +301,7 @@ jobs:
       fail-fast: false
       matrix:
         variant: [v1, v2]
-        php-version: ['8.4', '8.3', '8.2']
+        php-version: ['8.5', '8.4', '8.3', '8.2']
         php-type: [fpm, cli, apache]
         php-base: [alpine, bookworm]
         exclude:
@@ -312,6 +312,18 @@ jobs:
             php-base: bookworm
         include:
           # v2 builds on trixie for Debian images
+          - variant: v2
+            php-version: '8.5'
+            php-type: fpm
+            php-base: trixie
+          - variant: v2
+            php-version: '8.5'
+            php-type: cli
+            php-base: trixie
+          - variant: v2
+            php-version: '8.5'
+            php-type: apache
+            php-base: trixie
           - variant: v2
             php-version: '8.4'
             php-type: fpm
diff --git a/README.md b/README.md
index 96fcfdf..79b7c6e 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@ See [v1 vs v2 comparison](#v1-vs-v2-comparison) below for details.
 ## Features
 
 - **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 PHP Versions**: PHP 8.2, 8.3, 8.4, and 8.5 (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 (v1: Bookworm, v2: Trixie with Bookworm-compatible tags)
 - **Extensive Extensions**: 30+ PHP extensions pre-installed
@@ -318,6 +318,11 @@ Both v1 and v2 variants are available for all combinations below:
 
 | PHP Version | Type   | OS        | v1 Tag Example         | v2 Tag Example             |
 |-------------|--------|-----------|------------------------|----------------------------|
+| 8.5         | CLI    | Alpine    | `8.5-cli-alpine`       | `8.5-cli-alpine-v2`        |
+| 8.5         | CLI    | Bookworm  | `8.5-cli-bookworm`     | `8.5-cli-bookworm-v2`      |
+| 8.5         | FPM    | Alpine    | `8.5-fpm-alpine`       | `8.5-fpm-alpine-v2`        |
+| 8.5         | FPM    | Bookworm  | `8.5-fpm-bookworm`     | `8.5-fpm-bookworm-v2`      |
+| 8.5         | Apache | Bookworm  | `8.5-apache-bookworm`  | `8.5-apache-bookworm-v2`   |
 | 8.4         | CLI    | Alpine    | `8.4-cli-alpine`       | `8.4-cli-alpine-v2`        |
 | 8.4         | CLI    | Bookworm  | `8.4-cli-bookworm`     | `8.4-cli-bookworm-v2`      |
 | 8.4         | FPM    | Alpine    | `8.4-fpm-alpine`       | `8.4-fpm-alpine-v2`        |

From 08e775f4102e5da72ea31d6f28449d2371f1e74b Mon Sep 17 00:00:00 2001
From: KingPin <28669+KingPin@users.noreply.github.com>
Date: Sun, 17 May 2026 00:05:45 -0400
Subject: [PATCH 02/10] docs: add CLAUDE.md project guide for AI assistants
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Captures project overview, build commands, CI workflow, v1-vs-v2
architecture, s6-overlay notes, and platform gotchas. Note that the
single primary workflow (docker-ci.yml) handles push/PR/schedule and
workflow_dispatch — there are no separate manual v1/v2 workflows.
---
 CLAUDE.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..713da5e
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,60 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Multi-architecture PHP Docker image builder. Two parallel Dockerfile variants (v1 and v2) produce images for PHP 8.2, 8.3, 8.4, 8.5 across alpine/bookworm (v1) and alpine/trixie (v2), with fpm and cli types. Published to Docker Hub, GHCR, and Quay.io.
+
+## Local Build Commands
+
+```bash
+# Build a single image locally
+./extras/test-build.sh v1 8.3-fpm-alpine
+./extras/test-build.sh v2 8.3-fpm-alpine    # tags as php-docker:8.3-fpm-alpine-v2
+./extras/test-build.sh both 8.3-fpm-alpine   # builds both variants
+
+# v2 requires BuildKit (test-build.sh sets DOCKER_BUILDKIT=1 automatically)
+
+# Smoke test installed extensions
+docker run --rm php-docker:8.3-fpm-alpine php /extras/php_test.php
+```
+
+Tag format: `<php-version>-<type>-<baseos>` (e.g., `8.4-cli-trixie`, `8.2-fpm-bookworm`).
+
+Build args used by both Dockerfiles: `VERSION`, `PHPVERSION`, `BASEOS`.
+
+## CI/CD
+
+Primary workflow: `.github/workflows/docker-ci.yml` — runs on push to main, PRs, weekly schedule (Tuesday 3 AM UTC), and `workflow_dispatch`. Uses a build matrix across all variant/version/type/base combinations with `fail-fast: false`.
+
+Key matrix rules:
+- v1 uses bookworm for Debian; v2 uses trixie
+- No apache type on alpine
+- Multi-arch production builds: linux/amd64, linux/arm64, linux/arm/v7
+- PR fast-path tests only newest + oldest PHP versions (currently 8.5 + 8.2); push/schedule runs the full matrix
+
+## Architecture: v1 vs v2
+
+**v1 (Dockerfile.v1)**: Simple single-stage build. No init system. Base images from ECR (`public.ecr.aws/docker/library/php`). Suited for single-process containers.
+
+**v2 (Dockerfile.v2)**: s6-overlay v3.2.1.0 for process supervision. OCI labels. Handles Debian Trixie t64 library transitions. BuildKit required. Production multi-process workloads.
+
+Both install 30+ PHP extensions via `install-php-extensions` (with retry/backoff logic) and include Composer, image optimization tools (gifsicle, jpegoptim, optipng, pngquant).
+
+## s6-overlay (v2 only)
+
+- `s6-overlay/cont-init.d/10-php-config` — applies PHP config from environment variables (PHP_MEMORY_LIMIT, PHP_UPLOAD_MAX_FILESIZE, etc.)
+- `s6-overlay/services.d/php/run` — auto-detects and starts php-fpm, apache, or sleep for cli
+- `s6-overlay/services.d/php/finish` — graceful shutdown
+
+## Platform-Specific Gotchas
+
+- ARM/v7: GD built without AVIF support (no AV1 on armv7)
+- Trixie (v2): requires t64 library name handling (`libavif-dev` vs `libavif-devt64`)
+- ECR base images preferred over Docker Hub to avoid rate limits
+- install-php-extensions download has retry logic with exponential backoff
+
+## Documentation Checks
+
+`docs-ci.yml` validates markdown links on changes to `**.md` or `docs/**`. Config in `.github/markdown-link-check-config.json`.

From 2a797f4fc827ace7210b9854e1d64b3b9a3e2e4c Mon Sep 17 00:00:00 2001
From: KingPin <28669+KingPin@users.noreply.github.com>
Date: Sun, 17 May 2026 00:06:35 -0400
Subject: [PATCH 03/10] docs(ci): correct example matrices to match actual
 workflow

The build-and-test and publish matrix snippets in docs/ci.md drifted
to show deprecated versions (8.1, 7) and a wrong base set. Align with
the real docker-ci.yml matrix: PHP 8.2-8.5, fpm/cli/apache, v1 on
alpine/bookworm, v2 on alpine/trixie, plus the PR fast-path note.
---
 docs/ci.md | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/docs/ci.md b/docs/ci.md
index 6d7a030..609943c 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -21,14 +21,15 @@ The unified CI workflow handles both v1 and v2 variants in a single pipeline.
 
 #### 1. build-and-test
 
-Runs on every push and pull request:
+Runs on every push to `main`, pull request, weekly schedule, and `workflow_dispatch`:
 
 ```yaml
 matrix:
   variant: [v1, v2]
-  php-version: ['8.3', '8.1']
-  php-type: [fpm, cli]
-  php-base: [alpine, bookworm]
+  php-version: ['8.5', '8.4', '8.3', '8.2']  # PR fast-path: ['8.5', '8.2']
+  php-type: [fpm, cli, apache]
+  php-base: [alpine, bookworm]   # v2 uses trixie instead of bookworm
+  # apache+alpine excluded; v2/trixie added via include
 ```
 
 **What it does:**
@@ -49,9 +50,10 @@ Runs **only on `main` branch** after successful build-and-test:
 ```yaml
 matrix:
   variant: [v1, v2]
-  php-version: ['8.3', '8.2', '8.1', '7']
+  php-version: ['8.5', '8.4', '8.3', '8.2']
   php-type: [fpm, cli, apache]
-  php-base: [alpine, bookworm, bullseye]
+  php-base: [alpine, bookworm]   # v2 uses trixie instead of bookworm
+  # apache+alpine excluded; v2/trixie added via include
 ```
 
 **What it does:**

From 3b2563e34437faf2d956c551a75fd790b7ebdefd Mon Sep 17 00:00:00 2001
From: KingPin <28669+KingPin@users.noreply.github.com>
Date: Sun, 17 May 2026 00:09:38 -0400
Subject: [PATCH 04/10] docs: bump example tags to PHP 8.5 and refresh
 supported-version prose

Switch the "current version" example tag in README, docs, and the
extras/ scripts from 8.3 to 8.5 so examples stay aligned with the
newest actively-built version. The 8.3 row in the README tags table
is preserved as a real supported version. Also broaden deprecation/
migration prose from "PHP 8.2 or 8.3" to "8.2-8.5" or "newer" so it
won't go stale on every PHP release.
---
 README.md                 | 46 ++++++++++++-------------
 docs/ci.md                |  4 +--
 docs/deprecated-images.md | 18 +++++-----
 docs/local-build.md       | 70 +++++++++++++++++++--------------------
 docs/migration.md         | 38 ++++++++++-----------
 docs/troubleshooting.md   | 60 ++++++++++++++++-----------------
 extras/php_test.php       | 14 ++++----
 extras/test-build.sh      | 16 ++++-----
 8 files changed, 133 insertions(+), 133 deletions(-)

diff --git a/README.md b/README.md
index 79b7c6e..c7a0714 100644
--- a/README.md
+++ b/README.md
@@ -9,8 +9,8 @@ Multi-architecture PHP Docker images with extensive extensions for modern web de
 
 ## 🎯 Which Image Should I Use?
 
-**New projects or need process supervision?** → Use **v2** images (e.g., `8.3-fpm-alpine-v2`)  
-**Existing deployments or maximum compatibility?** → Use **v1** images (e.g., `8.3-fpm-alpine`)
+**New projects or need process supervision?** → Use **v2** images (e.g., `8.5-fpm-alpine-v2`)  
+**Existing deployments or maximum compatibility?** → Use **v1** images (e.g., `8.5-fpm-alpine`)
 
 See [v1 vs v2 comparison](#v1-vs-v2-comparison) below for details.
 
@@ -75,7 +75,7 @@ The following environment variables are applied at container startup by the s6-o
 ### Example usage
 
 ```bash
-docker run -e PHP_MEMORY_LIMIT=512M -e PHP_MAX_EXECUTION_TIME=600 kingpin/php-docker:8.3-fpm-alpine-v2
+docker run -e PHP_MEMORY_LIMIT=512M -e PHP_MAX_EXECUTION_TIME=600 kingpin/php-docker:8.5-fpm-alpine-v2
 ```
 
 ## 🚀 Quick Start
@@ -84,26 +84,26 @@ docker run -e PHP_MEMORY_LIMIT=512M -e PHP_MAX_EXECUTION_TIME=600 kingpin/php-do
 
 ```bash
 # Run PHP CLI
-docker run --rm kingpin/php-docker:8.3-cli-alpine php -v
+docker run --rm kingpin/php-docker:8.5-cli-alpine php -v
 
 # Run with your code mounted
-docker run --rm -v $(pwd):/app -w /app kingpin/php-docker:8.3-cli-alpine php script.php
+docker run --rm -v $(pwd):/app -w /app kingpin/php-docker:8.5-cli-alpine php script.php
 
 # Start PHP-FPM server
-docker run -d -p 9000:9000 -v $(pwd):/var/www/html kingpin/php-docker:8.3-fpm-alpine
+docker run -d -p 9000:9000 -v $(pwd):/var/www/html kingpin/php-docker:8.5-fpm-alpine
 ```
 
 ### v2 (Modern/Supervised)
 
 ```bash
 # Run PHP CLI with s6-overlay
-docker run --rm kingpin/php-docker:8.3-cli-alpine-v2 php -v
+docker run --rm kingpin/php-docker:8.5-cli-alpine-v2 php -v
 
 # Run with your code mounted
-docker run --rm -v $(pwd):/app -w /app kingpin/php-docker:8.3-cli-alpine-v2 php script.php
+docker run --rm -v $(pwd):/app -w /app kingpin/php-docker:8.5-cli-alpine-v2 php script.php
 
 # Start PHP-FPM with s6 supervision
-docker run -d -p 9000:9000 -v $(pwd):/var/www/html kingpin/php-docker:8.3-fpm-alpine-v2
+docker run -d -p 9000:9000 -v $(pwd):/var/www/html kingpin/php-docker:8.5-fpm-alpine-v2
 ```
 
 ## v1 vs v2 Comparison
@@ -218,27 +218,27 @@ These images are designed with security in mind:
 
 1. **Never run as root**: Keep the default non-root user or specify your own
    ```bash
-   docker run --user 1001:1001 kingpin/php-docker:8.3-fpm-alpine
+   docker run --user 1001:1001 kingpin/php-docker:8.5-fpm-alpine
    ```
 
 2. **Use read-only volumes when possible**
    ```bash
-   docker run -v $(pwd)/config:/app/config:ro kingpin/php-docker:8.3-cli-alpine
+   docker run -v $(pwd)/config:/app/config:ro kingpin/php-docker:8.5-cli-alpine
    ```
 
 3. **Limit capabilities**: Drop unnecessary capabilities
    ```bash
-   docker run --cap-drop ALL --cap-add NET_BIND_SERVICE kingpin/php-docker:8.3-apache-bookworm
+   docker run --cap-drop ALL --cap-add NET_BIND_SERVICE kingpin/php-docker:8.5-apache-bookworm
    ```
 
 4. **Set memory and CPU limits**
    ```bash
-   docker run --memory="256m" --cpus="0.5" kingpin/php-docker:8.3-fpm-alpine
+   docker run --memory="256m" --cpus="0.5" kingpin/php-docker:8.5-fpm-alpine
    ```
 
 5. **Use secrets management for sensitive data**
    ```bash
-   docker run --secret db_password kingpin/php-docker:8.3-cli-alpine
+   docker run --secret db_password kingpin/php-docker:8.5-cli-alpine
    ```
 
 6. **Regularly update images** to get the latest security patches
@@ -254,7 +254,7 @@ docker run \
   -e PHP_OPCACHE_MEMORY_CONSUMPTION=256 \
   -e PHP_OPCACHE_MAX_ACCELERATED_FILES=20000 \
   -e PHP_OPCACHE_INTERNED_STRINGS_BUFFER=32 \
-  kingpin/php-docker:8.3-fpm-alpine
+  kingpin/php-docker:8.5-fpm-alpine
 ```
 
 ### PHP-FPM Tuning (for FPM variants)
@@ -275,7 +275,7 @@ pm.max_requests = 500
 ```bash
 docker run \
   -e PHP_MEMORY_LIMIT=128M \
-  kingpin/php-docker:8.3-fpm-alpine
+  kingpin/php-docker:8.5-fpm-alpine
 ```
 
 ### JIT Configuration (PHP 8.0+)
@@ -309,8 +309,8 @@ All registries have identical image content and tags.
 
 ### Tag Format
 
-- **v1 images**: `{php-version}-{type}-{os}` (e.g., `8.3-fpm-alpine`)
-- **v2 images**: `{php-version}-{type}-{os}-v2` (e.g., `8.3-fpm-alpine-v2`)
+- **v1 images**: `{php-version}-{type}-{os}` (e.g., `8.5-fpm-alpine`)
+- **v2 images**: `{php-version}-{type}-{os}-v2` (e.g., `8.5-fpm-alpine-v2`)
 
 ### Current Supported Images
 
@@ -360,7 +360,7 @@ The following tags are deprecated and will not be built going forward, but remai
   - `8.1-fpm-bullseye`, `8.1-fpm-bookworm`, `8.1-fpm-alpine`
   - `8.1-apache-bullseye`, `8.1-apache-bookworm`
 
-> **Important:** These versions are deprecated. Please upgrade to PHP 8.2, 8.3, or 8.4 for security and performance.
+> **Important:** These versions are deprecated. Please upgrade to an actively-supported PHP version (8.2–8.5) for security and performance.
 
 ## 📊 Image Sizes
 
@@ -426,7 +426,7 @@ Approximate compressed sizes (vary by PHP version and platform):
 ### Basic usage with Docker
 
 ```bash
-docker run -d --name php-app kingpin/php-docker:8.3-cli-alpine php -v
+docker run -d --name php-app kingpin/php-docker:8.5-cli-alpine php -v
 ```
 
 ### With Docker Compose
@@ -434,7 +434,7 @@ docker run -d --name php-app kingpin/php-docker:8.3-cli-alpine php -v
 ```yaml
 services:
   php-fpm:
-    image: kingpin/php-docker:8.3-fpm-alpine
+    image: kingpin/php-docker:8.5-fpm-alpine
     volumes:
       - ./src:/var/www/html
     networks:
@@ -461,7 +461,7 @@ For detailed WordPress setup instructions, visit our [guide](https://sumguy.com/
 You can build custom images based on these by extending the Dockerfile:
 
 ```dockerfile
-FROM kingpin/php-docker:8.3-fpm-alpine
+FROM kingpin/php-docker:8.5-fpm-alpine
 
 # Add your custom configurations
 COPY custom-php.ini /usr/local/etc/php/conf.d/
@@ -485,7 +485,7 @@ The following PHP versions are **no longer actively built** but remain available
 - Available tags: `8.1-cli-alpine`, `8.1-fpm-alpine`, `8.1-apache-bookworm`, etc.
 
 **Migration Path:**
-- Upgrade to PHP 8.2 or 8.3 for continued security updates and new builds
+- Upgrade to an actively-supported PHP version (8.2–8.5) for continued security updates and new builds
 - See [migration guide](docs/migration.md) for upgrade assistance
 - Existing images will remain available in Docker Hub, GHCR, and Quay.io
 
diff --git a/docs/ci.md b/docs/ci.md
index 609943c..fca5b2b 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -178,8 +178,8 @@ Published tags follow this format:
 **v2:** `{php-version}-{type}-{os}-v2`
 
 Examples:
-- `8.3-fpm-alpine` (v1)
-- `8.3-fpm-alpine-v2` (v2)
+- `8.5-fpm-alpine` (v1)
+- `8.5-fpm-alpine-v2` (v2)
 - `8.2-cli-bookworm` (v1)
 - `8.2-cli-bookworm-v2` (v2)
 
diff --git a/docs/deprecated-images.md b/docs/deprecated-images.md
index 1643b5d..19e2678 100644
--- a/docs/deprecated-images.md
+++ b/docs/deprecated-images.md
@@ -61,7 +61,7 @@ This document lists PHP versions that are **no longer actively built** but remai
 
 ## Migration Recommendations
 
-### From PHP 7.x → PHP 8.2 or 8.3
+### From PHP 7.x → PHP 8.2 or newer
 
 **Breaking Changes to Consider:**
 - Deprecated features removed in PHP 8.0+
@@ -71,7 +71,7 @@ This document lists PHP versions that are **no longer actively built** but remai
 
 **Steps:**
 1. Review [PHP 8 migration guide](https://www.php.net/manual/en/migration80.php)
-2. Test your application locally with PHP 8.2 or 8.3
+2. Test your application locally with PHP 8.2 or newer
 3. Update dependencies in `composer.json`
 4. Run automated tests
 5. Update Docker image tags
@@ -82,10 +82,10 @@ This document lists PHP versions that are **no longer actively built** but remai
 docker pull kingpin/php-docker:7-fpm-alpine
 
 # New (recommended)
-docker pull kingpin/php-docker:8.3-fpm-alpine
+docker pull kingpin/php-docker:8.5-fpm-alpine
 ```
 
-### From PHP 8.1 → PHP 8.2 or 8.3
+### From PHP 8.1 → PHP 8.2 or newer
 
 **Breaking Changes:**
 - PHP 8.2: Deprecated dynamic properties
@@ -103,7 +103,7 @@ docker pull kingpin/php-docker:8.3-fpm-alpine
 docker pull kingpin/php-docker:8.1-fpm-alpine
 
 # New (recommended)
-docker pull kingpin/php-docker:8.3-fpm-alpine
+docker pull kingpin/php-docker:8.5-fpm-alpine
 ```
 
 ### Docker Compose Migration
@@ -117,7 +117,7 @@ services:
 # After (recommended)
 services:
   app:
-    image: kingpin/php-docker:8.3-fpm-alpine
+    image: kingpin/php-docker:8.5-fpm-alpine
 ```
 
 ### Kubernetes/Helm Migration
@@ -131,7 +131,7 @@ containers:
 # After (recommended)
 containers:
   - name: app
-    image: kingpin/php-docker:8.3-fpm-alpine
+    image: kingpin/php-docker:8.5-fpm-alpine
 ```
 
 ## Long-Term Availability
@@ -163,11 +163,11 @@ docker pull kingpin/php-docker:8.1-fpm-alpine
 - Updates to PHP extensions
 - Bug fixes
 
-**For production use**, we strongly recommend migrating to actively supported versions (PHP 8.2 or 8.3).
+**For production use**, we strongly recommend migrating to actively supported versions (PHP 8.2–8.5).
 
 ## Support Policy
 
-- **Active Builds**: PHP 8.2 and 8.3 (receive regular updates)
+- **Active Builds**: PHP 8.2, 8.3, 8.4, 8.5 (receive regular updates)
 - **Deprecated**: PHP 7.x and 8.1 (images frozen, no updates)
 - **Removed**: None (all previously published images remain available)
 
diff --git a/docs/local-build.md b/docs/local-build.md
index d434752..3c8c1ba 100644
--- a/docs/local-build.md
+++ b/docs/local-build.md
@@ -32,20 +32,20 @@ The repository includes a helper script for building images locally.
 
 ```bash
 # Build v1 variant
-./test-build.sh v1 8.3-fpm-alpine
+./test-build.sh v1 8.5-fpm-alpine
 
 # Build v2 variant
-./test-build.sh v2 8.3-fpm-alpine
+./test-build.sh v2 8.5-fpm-alpine
 
 # Build both variants
-./test-build.sh both 8.3-fpm-alpine
+./test-build.sh both 8.5-fpm-alpine
 ```
 
 ### How It Works
 
 The script automatically:
-- Parses the tag (e.g., `8.3-fpm-alpine`) to extract:
-  - PHP version: `8.3`
+- Parses the tag (e.g., `8.5-fpm-alpine`) to extract:
+  - PHP version: `8.5`
   - PHP type: `fpm`
   - Base OS: `alpine`
 - Passes these as build arguments
@@ -58,10 +58,10 @@ The script automatically:
 # Build different PHP versions
 ./test-build.sh v2 8.1-cli-alpine
 ./test-build.sh v2 8.2-fpm-bookworm
-./test-build.sh v2 8.3-apache-bookworm
+./test-build.sh v2 8.5-apache-bookworm
 
 # Build both v1 and v2
-./test-build.sh both 8.3-cli-alpine
+./test-build.sh both 8.5-cli-alpine
 ```
 
 ### Testing Built Images
@@ -70,16 +70,16 @@ After building, test your images:
 
 ```bash
 # Check PHP version
-docker run --rm php-docker:8.3-fpm-alpine-v2 php -v
+docker run --rm php-docker:8.5-fpm-alpine-v2 php -v
 
 # List extensions
-docker run --rm php-docker:8.3-fpm-alpine-v2 php -m
+docker run --rm php-docker:8.5-fpm-alpine-v2 php -m
 
 # Check s6-overlay (v2 only)
-docker run --rm php-docker:8.3-fpm-alpine-v2 ls -la /etc/s6-overlay
+docker run --rm php-docker:8.5-fpm-alpine-v2 ls -la /etc/s6-overlay
 
 # Interactive shell
-docker run --rm -it php-docker:8.3-cli-alpine-v2 sh
+docker run --rm -it php-docker:8.5-cli-alpine-v2 sh
 ```
 
 ## Manual Building
@@ -91,10 +91,10 @@ v1 images use standard Docker build:
 ```bash
 docker build \
   -f Dockerfile.v1 \
-  --build-arg VERSION=8.3-fpm-alpine \
-  --build-arg PHPVERSION=8.3 \
+  --build-arg VERSION=8.5-fpm-alpine \
+  --build-arg PHPVERSION=8.5 \
   --build-arg BASEOS=alpine \
-  -t php-docker:8.3-fpm-alpine \
+  -t php-docker:8.5-fpm-alpine \
   .
 ```
 
@@ -106,20 +106,20 @@ v2 images require BuildKit:
 # Option 1: Environment variable
 DOCKER_BUILDKIT=1 docker build \
   -f Dockerfile.v2 \
-  --build-arg VERSION=8.3-fpm-alpine \
-  --build-arg PHPVERSION=8.3 \
+  --build-arg VERSION=8.5-fpm-alpine \
+  --build-arg PHPVERSION=8.5 \
   --build-arg BASEOS=alpine \
-  -t php-docker:8.3-fpm-alpine-v2 \
+  -t php-docker:8.5-fpm-alpine-v2 \
   .
 
 # Option 2: Using buildx
 docker buildx build \
   -f Dockerfile.v2 \
-  --build-arg VERSION=8.3-fpm-alpine \
-  --build-arg PHPVERSION=8.3 \
+  --build-arg VERSION=8.5-fpm-alpine \
+  --build-arg PHPVERSION=8.5 \
   --build-arg BASEOS=alpine \
   --load \
-  -t php-docker:8.3-fpm-alpine-v2 \
+  -t php-docker:8.5-fpm-alpine-v2 \
   .
 ```
 
@@ -129,8 +129,8 @@ Both Dockerfile.v1 and Dockerfile.v2 accept these build arguments:
 
 | Argument | Description | Example |
 |----------|-------------|---------|
-| `VERSION` | Full version string | `8.3-fpm-alpine` |
-| `PHPVERSION` | PHP version only | `8.3` |
+| `VERSION` | Full version string | `8.5-fpm-alpine` |
+| `PHPVERSION` | PHP version only | `8.5` |
 | `BASEOS` | Base OS | `alpine` or `bookworm` |
 
 ## Running Smoke Tests Locally
@@ -138,7 +138,7 @@ Both Dockerfile.v1 and Dockerfile.v2 accept these build arguments:
 ### Basic Smoke Tests
 
 ```bash
-IMAGE="php-docker:8.3-fpm-alpine-v2"
+IMAGE="php-docker:8.5-fpm-alpine-v2"
 
 # Test 1: PHP version
 docker run --rm $IMAGE php -v
@@ -157,7 +157,7 @@ docker run --rm $IMAGE sh -c "test -w /var/www && echo '/var/www writable'"
 ### v2-Specific Tests
 
 ```bash
-IMAGE="php-docker:8.3-fpm-alpine-v2"
+IMAGE="php-docker:8.5-fpm-alpine-v2"
 
 # Test 5: s6-overlay presence
 docker run --rm $IMAGE test -d /etc/s6-overlay && echo "s6-overlay present"
@@ -173,10 +173,10 @@ docker run --rm $IMAGE php -r "echo 'Running via s6 init';"
 
 ```bash
 # Test PHP-FPM
-docker run --rm php-docker:8.3-fpm-alpine-v2 php-fpm --version
+docker run --rm php-docker:8.5-fpm-alpine-v2 php-fpm --version
 
 # Start FPM and test
-docker run -d --name test-fpm -p 9000:9000 php-docker:8.3-fpm-alpine-v2
+docker run -d --name test-fpm -p 9000:9000 php-docker:8.5-fpm-alpine-v2
 sleep 2
 docker logs test-fpm
 docker stop test-fpm
@@ -195,10 +195,10 @@ docker buildx create --name multiarch --use
 docker buildx build \
   -f Dockerfile.v2 \
   --platform linux/amd64,linux/arm64,linux/arm/v7 \
-  --build-arg VERSION=8.3-fpm-alpine \
-  --build-arg PHPVERSION=8.3 \
+  --build-arg VERSION=8.5-fpm-alpine \
+  --build-arg PHPVERSION=8.5 \
   --build-arg BASEOS=alpine \
-  -t php-docker:8.3-fpm-alpine-v2 \
+  -t php-docker:8.5-fpm-alpine-v2 \
   .
 
 # Remove builder when done
@@ -212,7 +212,7 @@ docker buildx rm multiarch
 Create a custom Dockerfile:
 
 ```dockerfile
-FROM php-docker:8.3-fpm-alpine-v2
+FROM php-docker:8.5-fpm-alpine-v2
 
 # Install additional extensions
 RUN install-php-extensions \
@@ -247,7 +247,7 @@ chmod +x s6-services/worker/run
 
 Dockerfile:
 ```dockerfile
-FROM php-docker:8.3-fpm-alpine-v2
+FROM php-docker:8.5-fpm-alpine-v2
 COPY s6-services/ /etc/services.d/
 ```
 
@@ -266,13 +266,13 @@ COPY s6-services/ /etc/services.d/
 
 ```bash
 # Build both variants
-./test-build.sh both 8.3-fpm-alpine
+./test-build.sh both 8.5-fpm-alpine
 
 # Run quick tests
 for variant in "" "-v2"; do
-  echo "Testing php-docker:8.3-fpm-alpine$variant"
-  docker run --rm php-docker:8.3-fpm-alpine$variant php -v
-  docker run --rm php-docker:8.3-fpm-alpine$variant php -m | wc -l
+  echo "Testing php-docker:8.5-fpm-alpine$variant"
+  docker run --rm php-docker:8.5-fpm-alpine$variant php -v
+  docker run --rm php-docker:8.5-fpm-alpine$variant php -m | wc -l
 done
 ```
 
diff --git a/docs/migration.md b/docs/migration.md
index e344bbc..4641909 100644
--- a/docs/migration.md
+++ b/docs/migration.md
@@ -19,9 +19,9 @@ All v2 Debian images now use Trixie as the base, with multiple compatible tags:
 
 ```bash
 # These all reference the SAME trixie-built image:
-kingpin/php-docker:8.3-fpm-trixie-v2      # Explicit trixie tag
-kingpin/php-docker:8.3-fpm-bookworm-v2    # Backward-compatible alias
-kingpin/php-docker:8.3-fpm-bullseye-v2    # Legacy compatibility alias
+kingpin/php-docker:8.5-fpm-trixie-v2      # Explicit trixie tag
+kingpin/php-docker:8.5-fpm-bookworm-v2    # Backward-compatible alias
+kingpin/php-docker:8.5-fpm-bullseye-v2    # Legacy compatibility alias
 ```
 
 ### Why This Change?
@@ -82,7 +82,7 @@ If you encounter issues:
 2. **Use v1 images** (still on Bookworm):
    ```bash
    # v1 images remain on Debian Bookworm
-   docker pull kingpin/php-docker:8.3-fpm-bookworm
+   docker pull kingpin/php-docker:8.5-fpm-bookworm
    ```
 
 3. **Report the issue**:
@@ -111,7 +111,7 @@ A: No current plans. v1 remains on Bookworm for maximum stability and compatibil
 
 ---
 
-> **ℹ️ Note on Deprecated Versions**: PHP 7.x and 8.1 are no longer actively built. If you're using these versions, please also review the [deprecated images guide](deprecated-images.md) for upgrade paths to PHP 8.2 or 8.3.
+> **ℹ️ Note on Deprecated Versions**: PHP 7.x and 8.1 are no longer actively built. If you're using these versions, please also review the [deprecated images guide](deprecated-images.md) for upgrade paths to PHP 8.2 or newer.
 
 ## Should You Migrate?
 
@@ -166,11 +166,11 @@ Start by testing v2 images in development or staging:
 
 ```bash
 # Pull v2 image
-docker pull kingpin/php-docker:8.3-fpm-alpine-v2
+docker pull kingpin/php-docker:8.5-fpm-alpine-v2
 
 # Test your application
 docker run --rm -v $(pwd):/var/www/html \
-  kingpin/php-docker:8.3-fpm-alpine-v2 php -v
+  kingpin/php-docker:8.5-fpm-alpine-v2 php -v
 ```
 
 ### Step 2: Update docker-compose.yml
@@ -181,14 +181,14 @@ Change image tags from v1 to v2:
 # Before (v1)
 services:
   php-fpm:
-    image: kingpin/php-docker:8.3-fpm-alpine
+    image: kingpin/php-docker:8.5-fpm-alpine
     volumes:
       - ./src:/var/www/html
 
 # After (v2)
 services:
   php-fpm:
-    image: kingpin/php-docker:8.3-fpm-alpine-v2
+    image: kingpin/php-docker:8.5-fpm-alpine-v2
     volumes:
       - ./src:/var/www/html
 ```
@@ -216,11 +216,11 @@ Both v1 and v2 use the same directory structure and permissions, but verify:
 
 ```bash
 # Check directory permissions
-docker run --rm kingpin/php-docker:8.3-fpm-alpine-v2 \
+docker run --rm kingpin/php-docker:8.5-fpm-alpine-v2 \
   ls -la /var/www/html /tmp
 
 # Verify PHP configuration
-docker run --rm kingpin/php-docker:8.3-fpm-alpine-v2 \
+docker run --rm kingpin/php-docker:8.5-fpm-alpine-v2 \
   php --ini
 ```
 
@@ -270,7 +270,7 @@ All environment variables from v1 work identically in v2:
 # These work the same in both v1 and v2
 docker run -e PHP_MEMORY_LIMIT=512M \
   -e PHP_MAX_EXECUTION_TIME=600 \
-  kingpin/php-docker:8.3-fpm-alpine-v2
+  kingpin/php-docker:8.5-fpm-alpine-v2
 ```
 
 ### Volume Mounts
@@ -289,7 +289,7 @@ All pre-installed extensions are identical between v1 and v2:
 
 ```bash
 # Same extensions available
-docker run --rm kingpin/php-docker:8.3-cli-alpine-v2 php -m
+docker run --rm kingpin/php-docker:8.5-cli-alpine-v2 php -m
 ```
 
 ### User and Permissions
@@ -298,7 +298,7 @@ Both versions run as `appuser` (UID 1000) by default:
 
 ```bash
 # Same user behavior
-docker run --rm kingpin/php-docker:8.3-fpm-alpine-v2 whoami
+docker run --rm kingpin/php-docker:8.5-fpm-alpine-v2 whoami
 # Output: appuser
 ```
 
@@ -312,10 +312,10 @@ docker run --rm kingpin/php-docker:8.3-fpm-alpine-v2 whoami
 
 ```bash
 # Don't do this with v2:
-docker run --entrypoint /bin/sh kingpin/php-docker:8.3-fpm-alpine-v2
+docker run --entrypoint /bin/sh kingpin/php-docker:8.5-fpm-alpine-v2
 
 # Instead, use CMD:
-docker run --rm kingpin/php-docker:8.3-fpm-alpine-v2 sh -c "php -v"
+docker run --rm kingpin/php-docker:8.5-fpm-alpine-v2 sh -c "php -v"
 ```
 
 ### Issue: Custom Scripts Not Running
@@ -329,7 +329,7 @@ docker run --rm kingpin/php-docker:8.3-fpm-alpine-v2 sh -c "php -v"
 Example Dockerfile:
 
 ```dockerfile
-FROM kingpin/php-docker:8.3-fpm-alpine-v2
+FROM kingpin/php-docker:8.5-fpm-alpine-v2
 
 # Add init script
 COPY my-init-script.sh /etc/cont-init.d/99-my-init
@@ -373,7 +373,7 @@ chmod +x s6-services/myworker/run
 Then in your Dockerfile:
 
 ```dockerfile
-FROM kingpin/php-docker:8.3-fpm-alpine-v2
+FROM kingpin/php-docker:8.5-fpm-alpine-v2
 COPY s6-services/ /etc/services.d/
 ```
 
@@ -412,7 +412,7 @@ If you encounter issues, rolling back is simple:
 # Change tag back to v1
 services:
   php-fpm:
-    image: kingpin/php-docker:8.3-fpm-alpine  # Remove -v2 suffix
+    image: kingpin/php-docker:8.5-fpm-alpine  # Remove -v2 suffix
 ```
 
 Then redeploy:
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 7fc5c18..f568d98 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -18,10 +18,10 @@ Common issues and solutions for PHP Docker images (v1 and v2).
 For CLI variants, provide a command:
 ```bash
 # Keep container running
-docker run -d kingpin/php-docker:8.3-cli-alpine tail -f /dev/null
+docker run -d kingpin/php-docker:8.5-cli-alpine tail -f /dev/null
 
 # Or run a long-running script
-docker run -d kingpin/php-docker:8.3-cli-alpine php worker.php
+docker run -d kingpin/php-docker:8.5-cli-alpine php worker.php
 ```
 
 For FPM variants, check logs:
@@ -42,7 +42,7 @@ id -u  # Usually 1000
 # Run with matching UID
 docker run -u $(id -u):$(id -g) \
   -v $(pwd):/app \
-  kingpin/php-docker:8.3-cli-alpine php script.php
+  kingpin/php-docker:8.5-cli-alpine php script.php
 ```
 
 Or change ownership of mounted directory:
@@ -55,7 +55,7 @@ For docker-compose:
 ```yaml
 services:
   php:
-    image: kingpin/php-docker:8.3-fpm-alpine-v2
+    image: kingpin/php-docker:8.5-fpm-alpine-v2
     user: "1000:1000"  # Match your host UID:GID
     volumes:
       - ./src:/var/www/html
@@ -69,10 +69,10 @@ services:
 
 ```bash
 # List installed extensions
-docker run --rm kingpin/php-docker:8.3-cli-alpine php -m
+docker run --rm kingpin/php-docker:8.5-cli-alpine php -m
 
 # If missing, create custom Dockerfile
-FROM kingpin/php-docker:8.3-fpm-alpine-v2
+FROM kingpin/php-docker:8.5-fpm-alpine-v2
 RUN install-php-extensions swoole pcntl
 ```
 
@@ -90,7 +90,7 @@ Common extensions not included by default:
 
 ```bash
 # Via environment variable
-docker run -e PHP_MEMORY_LIMIT=1G kingpin/php-docker:8.3-cli-alpine php script.php
+docker run -e PHP_MEMORY_LIMIT=1G kingpin/php-docker:8.5-cli-alpine php script.php
 
 # Or with docker-compose
 services:
@@ -113,7 +113,7 @@ php -d memory_limit=1G script.php
 1. **Check OPcache settings:**
 ```bash
 docker run -e PHP_OPCACHE_MEMORY_CONSUMPTION=256 \
-  kingpin/php-docker:8.3-fpm-alpine-v2
+  kingpin/php-docker:8.5-fpm-alpine-v2
 ```
 
 1. **Enable JIT (PHP 8.0+):**
@@ -126,13 +126,13 @@ opcache.jit=1255
 1. **Use Alpine for smaller footprint:**
 ```bash
 # Alpine is lighter than Bookworm
-docker pull kingpin/php-docker:8.3-fpm-alpine-v2
+docker pull kingpin/php-docker:8.5-fpm-alpine-v2
 ```
 
 1. **Profile your code:**
 ```bash
 # Install xdebug for profiling
-FROM kingpin/php-docker:8.3-fpm-alpine-v2
+FROM kingpin/php-docker:8.5-fpm-alpine-v2
 RUN install-php-extensions xdebug
 ```
 
@@ -180,16 +180,16 @@ services:
 
 ```bash
 # Wrong - v1 tag (no s6-overlay)
-docker run kingpin/php-docker:8.3-fpm-alpine
+docker run kingpin/php-docker:8.5-fpm-alpine
 
 # Correct - v2 tag (has s6-overlay)
-docker run kingpin/php-docker:8.3-fpm-alpine-v2
+docker run kingpin/php-docker:8.5-fpm-alpine-v2
 ```
 
 If building custom images:
 ```dockerfile
 # Ensure base image is v2
-FROM kingpin/php-docker:8.3-fpm-alpine-v2  # Note the -v2 suffix
+FROM kingpin/php-docker:8.5-fpm-alpine-v2  # Note the -v2 suffix
 ```
 
 ### Custom Init Scripts Not Running (v2)
@@ -199,7 +199,7 @@ FROM kingpin/php-docker:8.3-fpm-alpine-v2  # Note the -v2 suffix
 **Solution:** v2 uses s6-overlay's init system. Place scripts correctly:
 
 ```dockerfile
-FROM kingpin/php-docker:8.3-fpm-alpine-v2
+FROM kingpin/php-docker:8.5-fpm-alpine-v2
 
 # For one-time initialization
 COPY my-init.sh /etc/cont-init.d/99-my-init
@@ -238,7 +238,7 @@ chmod +x s6-services/worker/run
 
 In Dockerfile:
 ```dockerfile
-FROM kingpin/php-docker:8.3-fpm-alpine-v2
+FROM kingpin/php-docker:8.5-fpm-alpine-v2
 COPY s6-services/ /etc/services.d/
 ```
 
@@ -252,7 +252,7 @@ COPY s6-services/ /etc/services.d/
 
 1. **Check network connectivity:**
 ```bash
-docker run --rm kingpin/php-docker:8.3-cli-alpine ping -c 3 db-host
+docker run --rm kingpin/php-docker:8.5-cli-alpine ping -c 3 db-host
 ```
 
 1. **Verify database host:**
@@ -294,7 +294,7 @@ sudo lsof -i :9000
 sudo netstat -tulpn | grep 9000
 
 # Use different port
-docker run -p 9001:9000 kingpin/php-docker:8.3-fpm-alpine-v2
+docker run -p 9001:9000 kingpin/php-docker:8.5-fpm-alpine-v2
 ```
 
 ## Extension-Specific Issues
@@ -309,10 +309,10 @@ docker run -p 9001:9000 kingpin/php-docker:8.3-fpm-alpine-v2
 
 ```bash
 # Check GD support
-docker run --rm kingpin/php-docker:8.3-cli-alpine php -r "print_r(gd_info());"
+docker run --rm kingpin/php-docker:8.5-cli-alpine php -r "print_r(gd_info());"
 
 # Use bookworm if more format support needed
-docker run --rm kingpin/php-docker:8.3-cli-bookworm php -r "print_r(gd_info());"
+docker run --rm kingpin/php-docker:8.5-cli-bookworm php -r "print_r(gd_info());"
 ```
 
 ### Redis Extension Not Working
@@ -321,14 +321,14 @@ docker run --rm kingpin/php-docker:8.3-cli-bookworm php -r "print_r(gd_info());"
 
 **Verify extension is loaded:**
 ```bash
-docker run --rm kingpin/php-docker:8.3-cli-alpine php -m | grep redis
+docker run --rm kingpin/php-docker:8.5-cli-alpine php -m | grep redis
 ```
 
 If loaded but still not working, check Redis server connection:
 ```bash
 # Test Redis connectivity
 docker run --rm --link redis:redis \
-  kingpin/php-docker:8.3-cli-alpine \
+  kingpin/php-docker:8.5-cli-alpine \
   php -r "var_dump((new Redis())->connect('redis', 6379));"
 ```
 
@@ -339,24 +339,24 @@ docker run --rm --link redis:redis \
 For v2 images, enable s6-overlay debug output:
 
 ```bash
-docker run -e S6_VERBOSITY=2 kingpin/php-docker:8.3-fpm-alpine-v2
+docker run -e S6_VERBOSITY=2 kingpin/php-docker:8.5-fpm-alpine-v2
 ```
 
 ### Check PHP Configuration
 
 ```bash
 # View all PHP settings
-docker run --rm kingpin/php-docker:8.3-cli-alpine php -i
+docker run --rm kingpin/php-docker:8.5-cli-alpine php -i
 
 # Check specific setting
-docker run --rm kingpin/php-docker:8.3-cli-alpine \
+docker run --rm kingpin/php-docker:8.5-cli-alpine \
   php -r "echo ini_get('memory_limit');"
 
 # List loaded extensions
-docker run --rm kingpin/php-docker:8.3-cli-alpine php -m
+docker run --rm kingpin/php-docker:8.5-cli-alpine php -m
 
 # View php.ini location
-docker run --rm kingpin/php-docker:8.3-cli-alpine php --ini
+docker run --rm kingpin/php-docker:8.5-cli-alpine php --ini
 ```
 
 ### Interactive Shell Access
@@ -368,7 +368,7 @@ Enter running container for debugging:
 docker exec -it <container-id> sh
 
 # Or start container with shell
-docker run --rm -it kingpin/php-docker:8.3-cli-alpine sh
+docker run --rm -it kingpin/php-docker:8.5-cli-alpine sh
 ```
 
 ### Container Resource Limits
@@ -394,7 +394,7 @@ Enable PHP error display (development only):
 docker run \
   -e PHP_DISPLAY_ERRORS=On \
   -e PHP_ERROR_REPORTING=E_ALL \
-  kingpin/php-docker:8.3-fpm-alpine-v2
+  kingpin/php-docker:8.5-fpm-alpine-v2
 ```
 
 ## Getting More Help
@@ -404,7 +404,7 @@ If issues persist:
 1. **Check GitHub Issues:** [github.com/kingpin/php-docker/issues](https://github.com/kingpin/php-docker/issues)
 2. **Review s6-overlay docs:** [github.com/just-containers/s6-overlay](https://github.com/just-containers/s6-overlay)
 3. **Open a new issue with:**
-   - Image tag used (e.g., `8.3-fpm-alpine-v2`)
+   - Image tag used (e.g., `8.5-fpm-alpine-v2`)
    - Full error message and logs
    - Minimal reproduction case (docker-compose.yml or Dockerfile)
    - Steps to reproduce
@@ -415,7 +415,7 @@ When reporting bugs, include:
 
 ```bash
 # Image information
-docker inspect kingpin/php-docker:8.3-fpm-alpine-v2 | grep -A 5 "Created"
+docker inspect kingpin/php-docker:8.5-fpm-alpine-v2 | grep -A 5 "Created"
 
 # Container logs
 docker logs <container-id> 2>&1
diff --git a/extras/php_test.php b/extras/php_test.php
index b18d516..b350f19 100644
--- a/extras/php_test.php
+++ b/extras/php_test.php
@@ -25,29 +25,29 @@
  * Usage Examples (using ghcr.io/kingpin/php-docker images):
  *
  * 1. CLI (Alpine):
- * docker run --rm -v "$(pwd)/php_test.php:/app/php_test.php:ro" ghcr.io/kingpin/php-docker:8.3-cli-alpine php /app/php_test.php
+ * docker run --rm -v "$(pwd)/php_test.php:/app/php_test.php:ro" ghcr.io/kingpin/php-docker:8.5-cli-alpine php /app/php_test.php
  *
  * 2. CLI (v1 - Debian Bookworm):
- * docker run --rm -v "$(pwd)/php_test.php:/app/php_test.php:ro" ghcr.io/kingpin/php-docker:8.3-cli-bookworm php /app/php_test.php
+ * docker run --rm -v "$(pwd)/php_test.php:/app/php_test.php:ro" ghcr.io/kingpin/php-docker:8.5-cli-bookworm php /app/php_test.php
  *
  * 3. CLI (v2 - Debian Trixie with s6-overlay):
- * docker run --rm -v "$(pwd)/php_test.php:/app/php_test.php:ro" ghcr.io/kingpin/php-docker:8.3-cli-trixie-v2 php /app/php_test.php
+ * docker run --rm -v "$(pwd)/php_test.php:/app/php_test.php:ro" ghcr.io/kingpin/php-docker:8.5-cli-trixie-v2 php /app/php_test.php
  * # Note: :bookworm-v2 also works (points to same Trixie-built image)
  *
  * 4. Web (Apache v1):
- * docker run --rm -d -p 8080:80 -v "$(pwd)/php_test.php:/var/www/html/php_test.php:ro" ghcr.io/kingpin/php-docker:8.3-apache-bookworm
+ * docker run --rm -d -p 8080:80 -v "$(pwd)/php_test.php:/var/www/html/php_test.php:ro" ghcr.io/kingpin/php-docker:8.5-apache-bookworm
  * # Then access: http://localhost:8080/php_test.php
  *
  * 5. Web (FPM v2 - via CLI to check environment):
  * # Note: Testing FPM properly requires a web server (like Nginx) configured to talk to it.
  * # This example just runs the CLI binary *inside* the FPM container to check extensions.
- * docker run --rm -v "$(pwd)/php_test.php:/app/php_test.php:ro" ghcr.io/kingpin/php-docker:8.3-fpm-trixie-v2 php /app/php_test.php
+ * docker run --rm -v "$(pwd)/php_test.php:/app/php_test.php:ro" ghcr.io/kingpin/php-docker:8.5-fpm-trixie-v2 php /app/php_test.php
  *
  * 6. CI/CD (Example assertion - v1):
- * docker run --rm -v "$(pwd)/php_test.php:/app/php_test.php:ro" ghcr.io/kingpin/php-docker:8.3-cli-bookworm php /app/php_test.php | grep "SAPI: cli"
+ * docker run --rm -v "$(pwd)/php_test.php:/app/php_test.php:ro" ghcr.io/kingpin/php-docker:8.5-cli-bookworm php /app/php_test.php | grep "SAPI: cli"
  *
  * 7. CI/CD (Example assertion - v2 with s6 check):
- * docker run --rm -v "$(pwd)/php_test.php:/app/php_test.php:ro" ghcr.io/kingpin/php-docker:8.3-cli-trixie-v2 php /app/php_test.php | grep "s6-overlay.*Detected"
+ * docker run --rm -v "$(pwd)/php_test.php:/app/php_test.php:ro" ghcr.io/kingpin/php-docker:8.5-cli-trixie-v2 php /app/php_test.php | grep "s6-overlay.*Detected"
  *
  * # Example with an existing container
  * docker exec <container_name> php /path/to/php_test.php
diff --git a/extras/test-build.sh b/extras/test-build.sh
index effab73..64562dc 100755
--- a/extras/test-build.sh
+++ b/extras/test-build.sh
@@ -2,9 +2,9 @@
 set -e
 
 # Usage: ./test-build.sh {v1|v2|both} <tag>
-# Example: ./test-build.sh v1 8.3-fpm-alpine
-# Example: ./test-build.sh v2 8.3-fpm-alpine  (builds as 8.3-fpm-alpine-v2)
-# Example: ./test-build.sh both 8.3-fpm-alpine
+# Example: ./test-build.sh v1 8.5-fpm-alpine
+# Example: ./test-build.sh v2 8.5-fpm-alpine  (builds as 8.5-fpm-alpine-v2)
+# Example: ./test-build.sh both 8.5-fpm-alpine
 
 IMAGE_NAME="php-docker"
 
@@ -13,20 +13,20 @@ show_usage() {
     echo ""
     echo "Arguments:"
     echo "  v1|v2|both  - Which Dockerfile variant(s) to build"
-    echo "  <tag>       - Base tag (e.g., 8.3-fpm-alpine or 8.1-cli-bookworm or 8.2-fpm-trixie)"
+    echo "  <tag>       - Base tag (e.g., 8.5-fpm-alpine or 8.2-cli-bookworm or 8.4-fpm-trixie)"
     echo ""
     echo "Examples:"
-    echo "  $0 v1 8.3-fpm-alpine           # Builds ${IMAGE_NAME}:8.3-fpm-alpine"
-    echo "  $0 v2 8.3-fpm-alpine           # Builds ${IMAGE_NAME}:8.3-fpm-alpine-v2"
+    echo "  $0 v1 8.5-fpm-alpine           # Builds ${IMAGE_NAME}:8.5-fpm-alpine"
+    echo "  $0 v2 8.5-fpm-alpine           # Builds ${IMAGE_NAME}:8.5-fpm-alpine-v2"
     echo "  $0 v2 8.2-fpm-trixie           # Builds ${IMAGE_NAME}:8.2-fpm-trixie-v2"
-    echo "  $0 both 8.3-fpm-alpine         # Builds both variants"
+    echo "  $0 both 8.5-fpm-alpine         # Builds both variants"
     exit 1
 }
 
 parse_tag() {
     local tag=$1
     
-    # Extract PHP version (e.g., 8.3, 8.1, 7)
+    # Extract PHP version (e.g., 8.5, 8.2, 7)
     local php_version=$(echo "$tag" | grep -oE '^[0-9]+(\.[0-9]+)?' || echo "")
     
     # Extract variant (fpm or cli)

From e9965f588703473e5c072be39d1bad6d0c2bac72 Mon Sep 17 00:00:00 2001
From: KingPin <28669+KingPin@users.noreply.github.com>
Date: Sun, 17 May 2026 00:20:54 -0400
Subject: [PATCH 05/10] docs: announce PHP 8.2 deprecation after 2026-12-31

Upstream PHP security support for 8.2 ends 2026-12-31, after which a
base image vulnerability would have no patch path. Document the
removal date now (~7 months ahead) so anyone pinned to 8.2-* tags has
time to migrate.

Also adds a forward-looking deprecation schedule table covering 8.2
through 8.5 so future EOL handling follows the same documented
policy (remove from matrix when upstream security support ends;
existing tags stay pullable).
---
 CLAUDE.md                 |  2 ++
 README.md                 | 15 ++++++++++++++-
 docs/deprecated-images.md | 14 ++++++++++++++
 3 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 713da5e..a9d8b7f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -6,6 +6,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 Multi-architecture PHP Docker image builder. Two parallel Dockerfile variants (v1 and v2) produce images for PHP 8.2, 8.3, 8.4, 8.5 across alpine/bookworm (v1) and alpine/trixie (v2), with fpm and cli types. Published to Docker Hub, GHCR, and Quay.io.
 
+Deprecation policy: PHP versions are removed from the build matrix when upstream security support ends ([php.net schedule](https://www.php.net/supported-versions.php)). PHP 8.2 is scheduled for removal after 2026-12-31.
+
 ## Local Build Commands
 
 ```bash
diff --git a/README.md b/README.md
index c7a0714..8bb3b30 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@ See [v1 vs v2 comparison](#v1-vs-v2-comparison) below for details.
 ## Features
 
 - **Multi-Architecture Support**: Works on `amd64`, `arm64/aarch64` and `arm32v7/armhf` platforms
-- **Multiple PHP Versions**: PHP 8.2, 8.3, 8.4, and 8.5 (actively built); PHP 7.x, 8.0, and 8.1 deprecated
+- **Multiple PHP Versions**: PHP 8.2, 8.3, 8.4, and 8.5 (actively built); PHP 7.x, 8.0, and 8.1 deprecated. PHP 8.2 is scheduled for removal after 2026-12-31 when upstream security support ends — see [deprecation schedule](#deprecation-schedule).
 - **Multiple Server Types**: CLI, FPM, and Apache
 - **Base OS Options**: Alpine (lightweight) and Debian (v1: Bookworm, v2: Trixie with Bookworm-compatible tags)
 - **Extensive Extensions**: 30+ PHP extensions pre-installed
@@ -341,6 +341,19 @@ Both v1 and v2 variants are available for all combinations below:
 
 > **Note:** v1 Debian images use Bookworm. v2 Debian images use Trixie, with `:bookworm-v2` tags as compatibility aliases pointing to the same Trixie-built images.
 
+### Deprecation Schedule
+
+PHP versions are removed from the build matrix when upstream security support ends ([php.net schedule](https://www.php.net/supported-versions.php)). Existing image tags remain pullable from registries indefinitely; only **new** builds stop.
+
+| Version | Upstream security ends | Planned removal |
+|---------|------------------------|-----------------|
+| 8.2     | 2026-12-31             | After 2026-12-31 |
+| 8.3     | 2027-12-31             | After 2027-12-31 |
+| 8.4     | 2028-12-31             | After 2028-12-31 |
+| 8.5     | 2029-12-31             | After 2029-12-31 |
+
+If you're pinned to a `8.2-*` tag, plan to bump to 8.3 or newer before the end of 2026.
+
 ### Deprecated Tags (v1 only)
 
 The following tags are deprecated and will not be built going forward, but remain available in registries for backwards compatibility:
diff --git a/docs/deprecated-images.md b/docs/deprecated-images.md
index 19e2678..8ed1621 100644
--- a/docs/deprecated-images.md
+++ b/docs/deprecated-images.md
@@ -168,9 +168,23 @@ docker pull kingpin/php-docker:8.1-fpm-alpine
 ## Support Policy
 
 - **Active Builds**: PHP 8.2, 8.3, 8.4, 8.5 (receive regular updates)
+- **Scheduled for Deprecation**: PHP 8.2 — removed after 2026-12-31 when upstream security support ends
 - **Deprecated**: PHP 7.x and 8.1 (images frozen, no updates)
 - **Removed**: None (all previously published images remain available)
 
+### Upcoming Deprecations
+
+PHP versions are removed from the build matrix when [upstream security support](https://www.php.net/supported-versions.php) ends. Existing image tags remain pullable from registries indefinitely.
+
+| Version | Upstream security ends | Planned removal from matrix |
+|---------|------------------------|-----------------------------|
+| 8.2     | 2026-12-31             | After 2026-12-31            |
+| 8.3     | 2027-12-31             | After 2027-12-31            |
+| 8.4     | 2028-12-31             | After 2028-12-31            |
+| 8.5     | 2029-12-31             | After 2029-12-31            |
+
+**If you're pinned to `8.2-*` tags**, plan to migrate to 8.3 or newer before end of 2026. PHP 8.2 → 8.3 is generally a low-risk bump; review the [PHP 8.3 migration guide](https://www.php.net/manual/en/migration83.php).
+
 ## Image Digests (Last Published)
 
 For reproducible builds, you can pin to specific digests. Contact the maintainer or check registry APIs for exact digest values of the last published builds.

From 56483d539a01f90635d61d0d050d477c941fd20e Mon Sep 17 00:00:00 2001
From: KingPin <28669+KingPin@users.noreply.github.com>
Date: Sun, 17 May 2026 11:16:04 -0400
Subject: [PATCH 06/10] fix(test-build): recognize apache tags in parse_tag

parse_tag matched only fpm|cli, so any apache tag (documented in the
script's own usage examples and used in CI for *-apache-bookworm
combos) silently fell back to the default fpm. Add apache to the
regex so the script builds the requested image type.
---
 extras/test-build.sh | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/extras/test-build.sh b/extras/test-build.sh
index 64562dc..bc3e4f9 100755
--- a/extras/test-build.sh
+++ b/extras/test-build.sh
@@ -29,8 +29,8 @@ parse_tag() {
     # Extract PHP version (e.g., 8.5, 8.2, 7)
     local php_version=$(echo "$tag" | grep -oE '^[0-9]+(\.[0-9]+)?' || echo "")
     
-    # Extract variant (fpm or cli)
-    local variant=$(echo "$tag" | grep -oE '(fpm|cli)' || echo "fpm")
+    # Extract variant (fpm, cli, or apache)
+    local variant=$(echo "$tag" | grep -oE '(fpm|cli|apache)' || echo "fpm")
     
     # Extract base OS (alpine, trixie, bookworm, bullseye)
     local baseos=$(echo "$tag" | grep -oE '(alpine|trixie|bookworm|bullseye)' || echo "alpine")

From 738d25051a834899b69ec8730683a2c95afb433d Mon Sep 17 00:00:00 2001
From: KingPin <28669+KingPin@users.noreply.github.com>
Date: Sun, 17 May 2026 11:16:31 -0400
Subject: [PATCH 07/10] docs(local-build): correct test-build.sh paths and drop
 deprecated 8.1 example

The helper script lives at extras/test-build.sh, not at the repo
root, so the documented commands fail when copy-pasted from a clean
checkout. Replace ./test-build.sh references with ./extras/test-build.sh
throughout.

Also swap the 8.1-cli-alpine example for 8.5-cli-alpine (8.1 is
deprecated and not built by the matrix) and add a one-line note
clarifying that a v2 bookworm tag resolves to a trixie-built image
via the bookworm-v2 compatibility alias.
---
 docs/local-build.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/docs/local-build.md b/docs/local-build.md
index 3c8c1ba..7192231 100644
--- a/docs/local-build.md
+++ b/docs/local-build.md
@@ -32,13 +32,13 @@ The repository includes a helper script for building images locally.
 
 ```bash
 # Build v1 variant
-./test-build.sh v1 8.5-fpm-alpine
+./extras/test-build.sh v1 8.5-fpm-alpine
 
 # Build v2 variant
-./test-build.sh v2 8.5-fpm-alpine
+./extras/test-build.sh v2 8.5-fpm-alpine
 
 # Build both variants
-./test-build.sh both 8.5-fpm-alpine
+./extras/test-build.sh both 8.5-fpm-alpine
 ```
 
 ### How It Works
@@ -56,12 +56,12 @@ The script automatically:
 
 ```bash
 # Build different PHP versions
-./test-build.sh v2 8.1-cli-alpine
-./test-build.sh v2 8.2-fpm-bookworm
-./test-build.sh v2 8.5-apache-bookworm
+./extras/test-build.sh v2 8.5-cli-alpine
+./extras/test-build.sh v2 8.2-fpm-bookworm
+./extras/test-build.sh v2 8.5-apache-bookworm   # v2 Debian builds on trixie; bookworm-v2 is an alias
 
 # Build both v1 and v2
-./test-build.sh both 8.5-cli-alpine
+./extras/test-build.sh both 8.5-cli-alpine
 ```
 
 ### Testing Built Images
@@ -256,7 +256,7 @@ COPY s6-services/ /etc/services.d/
 ### Typical Development Cycle
 
 1. **Make changes** to Dockerfile.v1 or Dockerfile.v2
-2. **Build locally** using `test-build.sh`
+2. **Build locally** using `extras/test-build.sh`
 3. **Run smoke tests** to verify functionality
 4. **Test your application** with the new image
 5. **Commit changes** and push to GitHub
@@ -266,7 +266,7 @@ COPY s6-services/ /etc/services.d/
 
 ```bash
 # Build both variants
-./test-build.sh both 8.5-fpm-alpine
+./extras/test-build.sh both 8.5-fpm-alpine
 
 # Run quick tests
 for variant in "" "-v2"; do

From 01f34c544a5fa9017500fdf9e77158c7369fbb0e Mon Sep 17 00:00:00 2001
From: KingPin <28669+KingPin@users.noreply.github.com>
Date: Sun, 17 May 2026 11:17:18 -0400
Subject: [PATCH 08/10] docs: correct out-of-date claims flagged in PR #36
 review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CLAUDE.md:
- Include apache in the type list (apache is built on Debian bases).
- Bump example tags from 8.3 to 8.5 to match the rest of the docs.
- Replace the broken smoke-test command (/extras/php_test.php is not
  baked into the image) with the bind-mount form used in the script's
  own docstring.
- Stop hard-coding "s6-overlay v3.2.1.0"; CI resolves the latest
  release at build time, v3.2.1.0 is just the Dockerfile ARG default.

docs/migration.md:
- Drop the bullseye-v2 alias example. The publish job only creates
  bookworm-v2 aliases for v2/trixie builds; bullseye-v2 tags are not
  published. Add a note pointing bullseye users to bookworm-v2.

docs/ci.md:
- Correct "Fails fast if any variant fails" — the matrix runs with
  fail-fast: false so all combinations run to completion.
- Correct the Branch Testing section: the push trigger is restricted
  to main, so non-main work runs via pull_request or workflow_dispatch,
  not via push events.
---
 CLAUDE.md         | 15 ++++++++-------
 docs/ci.md        | 12 ++++++------
 docs/migration.md |  5 +++--
 3 files changed, 17 insertions(+), 15 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index a9d8b7f..b78c575 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-Multi-architecture PHP Docker image builder. Two parallel Dockerfile variants (v1 and v2) produce images for PHP 8.2, 8.3, 8.4, 8.5 across alpine/bookworm (v1) and alpine/trixie (v2), with fpm and cli types. Published to Docker Hub, GHCR, and Quay.io.
+Multi-architecture PHP Docker image builder. Two parallel Dockerfile variants (v1 and v2) produce images for PHP 8.2, 8.3, 8.4, 8.5 across alpine/bookworm (v1) and alpine/trixie (v2), with fpm, cli, and apache types (apache only on Debian — not Alpine). Published to Docker Hub, GHCR, and Quay.io.
 
 Deprecation policy: PHP versions are removed from the build matrix when upstream security support ends ([php.net schedule](https://www.php.net/supported-versions.php)). PHP 8.2 is scheduled for removal after 2026-12-31.
 
@@ -12,14 +12,15 @@ Deprecation policy: PHP versions are removed from the build matrix when upstream
 
 ```bash
 # Build a single image locally
-./extras/test-build.sh v1 8.3-fpm-alpine
-./extras/test-build.sh v2 8.3-fpm-alpine    # tags as php-docker:8.3-fpm-alpine-v2
-./extras/test-build.sh both 8.3-fpm-alpine   # builds both variants
+./extras/test-build.sh v1 8.5-fpm-alpine
+./extras/test-build.sh v2 8.5-fpm-alpine    # tags as php-docker:8.5-fpm-alpine-v2
+./extras/test-build.sh both 8.5-fpm-alpine   # builds both variants
 
 # v2 requires BuildKit (test-build.sh sets DOCKER_BUILDKIT=1 automatically)
 
-# Smoke test installed extensions
-docker run --rm php-docker:8.3-fpm-alpine php /extras/php_test.php
+# Smoke test installed extensions (php_test.php is not baked into the image — bind-mount it)
+docker run --rm -v "$(pwd)/extras/php_test.php:/app/php_test.php:ro" \
+  php-docker:8.5-fpm-alpine php /app/php_test.php
 ```
 
 Tag format: `<php-version>-<type>-<baseos>` (e.g., `8.4-cli-trixie`, `8.2-fpm-bookworm`).
@@ -40,7 +41,7 @@ Key matrix rules:
 
 **v1 (Dockerfile.v1)**: Simple single-stage build. No init system. Base images from ECR (`public.ecr.aws/docker/library/php`). Suited for single-process containers.
 
-**v2 (Dockerfile.v2)**: s6-overlay v3.2.1.0 for process supervision. OCI labels. Handles Debian Trixie t64 library transitions. BuildKit required. Production multi-process workloads.
+**v2 (Dockerfile.v2)**: s6-overlay for process supervision (version is configurable via the `S6_OVERLAY_VERSION` build arg; CI resolves the latest release from GitHub at build time, the Dockerfile default is currently `v3.2.1.0`). OCI labels. Handles Debian Trixie t64 library transitions. BuildKit required. Production multi-process workloads.
 
 Both install 30+ PHP extensions via `install-php-extensions` (with retry/backoff logic) and include Composer, image optimization tools (gifsicle, jpegoptim, optipng, pngquant).
 
diff --git a/docs/ci.md b/docs/ci.md
index fca5b2b..b164bf8 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -41,7 +41,7 @@ matrix:
   - v2: s6-overlay validation
   - FPM: PHP-FPM functionality
 - Uses GitHub Actions cache for faster builds
-- Fails fast if any variant fails
+- Does **not** fail-fast: every variant runs even if one fails, so a single broken combination doesn't mask others (`strategy.fail-fast: false`)
 
 #### 2. publish
 
@@ -119,12 +119,12 @@ When you open a PR, CI will:
 
 ### Branch Testing
 
-Pushing to any branch (not just `main`) will:
-1. Trigger build-and-test job
-2. Run all smoke tests
-3. **Will NOT publish** images
+The `push` trigger is restricted to `main` — pushing to a feature branch does **not** by itself run CI. Non-main work is tested via:
 
-Only merging to `main` triggers publishing.
+1. **Pull requests**: open a PR against any branch; the PR fast-path matrix runs build-and-test (testing newest + oldest PHP only, currently 8.5 + 8.2)
+2. **`workflow_dispatch`**: manually trigger a run from the Actions tab on any ref
+
+Either path runs build-and-test but **will NOT publish** images. Only merging to `main` (via push or PR merge) triggers the publish job.
 
 ## Security Scanning
 
diff --git a/docs/migration.md b/docs/migration.md
index 4641909..7ac8e4f 100644
--- a/docs/migration.md
+++ b/docs/migration.md
@@ -18,12 +18,13 @@ v2 Debian-based images have migrated from **Debian Bookworm** to **Debian Trixie
 All v2 Debian images now use Trixie as the base, with multiple compatible tags:
 
 ```bash
-# These all reference the SAME trixie-built image:
+# These both reference the SAME trixie-built image:
 kingpin/php-docker:8.5-fpm-trixie-v2      # Explicit trixie tag
 kingpin/php-docker:8.5-fpm-bookworm-v2    # Backward-compatible alias
-kingpin/php-docker:8.5-fpm-bullseye-v2    # Legacy compatibility alias
 ```
 
+> **Note:** v2 only publishes `*-trixie-v2` and `*-bookworm-v2` aliases. No `*-bullseye-v2` aliases are created — projects pinned to a v1 bullseye tag should migrate to bookworm-v2 (or trixie-v2 directly).
+
 ### Why This Change?
 
 1. **Upstream Alignment**: PHP official images moved to Trixie

From 782f7d1e6be88b3c4902c64249b225721d9b9727 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Sun, 17 May 2026 15:25:14 +0000
Subject: [PATCH 09/10] fix(docs): correct MD060 table column style errors to
 pass markdownlint CI

Agent-Logs-Url: https://github.com/KingPin/php-docker/sessions/b37e91db-3114-4f2c-87f6-23029b6c2797

Co-authored-by: KingPin <28669+KingPin@users.noreply.github.com>
---
 README.md           | 14 +++++++-------
 docs/ci.md          |  2 +-
 docs/local-build.md |  2 +-
 docs/migration.md   |  2 +-
 4 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 8bb3b30..9f2ca29 100644
--- a/README.md
+++ b/README.md
@@ -35,7 +35,7 @@ The following environment variables are applied at container startup by the s6-o
 ### 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 |
@@ -43,7 +43,7 @@ The following environment variables are applied at container startup by the s6-o
 ### 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 |
@@ -51,14 +51,14 @@ The following environment variables are applied at container startup by the s6-o
 ### 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 |
@@ -66,7 +66,7 @@ The following environment variables are applied at container startup by the s6-o
 ### Other Settings
 
 | Variable | Default | Description |
-|----------|---------|-------------|
+| ---------- | --------- | ------------- |
 | `PHP_DATE_TIMEZONE` | `UTC` | Default timezone |
 | `PHP_SESSION_GC_MAXLIFETIME` | `1440` | Session garbage collection max lifetime |
 | `PHP_OPCACHE_MAX_ACCELERATED_FILES` | `10000` | OPCache maximum number of files |
@@ -345,8 +345,8 @@ Both v1 and v2 variants are available for all combinations below:
 
 PHP versions are removed from the build matrix when upstream security support ends ([php.net schedule](https://www.php.net/supported-versions.php)). Existing image tags remain pullable from registries indefinitely; only **new** builds stop.
 
-| Version | Upstream security ends | Planned removal |
-|---------|------------------------|-----------------|
+| Version | Upstream security ends | Planned removal  |
+|---------|------------------------|------------------|
 | 8.2     | 2026-12-31             | After 2026-12-31 |
 | 8.3     | 2027-12-31             | After 2027-12-31 |
 | 8.4     | 2028-12-31             | After 2028-12-31 |
diff --git a/docs/ci.md b/docs/ci.md
index b164bf8..c7e0226 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -70,7 +70,7 @@ matrix:
 To enable publishing, configure these GitHub repository secrets:
 
 | Secret | Description | Used For |
-|--------|-------------|----------|
+| -------- | ------------- | ---------- |
 | `DOCKERHUB_USERNAME` | Docker Hub username | Docker Hub login |
 | `DOCKERHUB_TOKEN` | Docker Hub access token | Docker Hub authentication |
 | `QUAY_USERNAME` | Quay.io username | Quay.io login |
diff --git a/docs/local-build.md b/docs/local-build.md
index 7192231..62eaa33 100644
--- a/docs/local-build.md
+++ b/docs/local-build.md
@@ -128,7 +128,7 @@ docker buildx build \
 Both Dockerfile.v1 and Dockerfile.v2 accept these build arguments:
 
 | Argument | Description | Example |
-|----------|-------------|---------|
+| ---------- | ------------- | --------- |
 | `VERSION` | Full version string | `8.5-fpm-alpine` |
 | `PHPVERSION` | PHP version only | `8.5` |
 | `BASEOS` | Base OS | `alpine` or `bookworm` |
diff --git a/docs/migration.md b/docs/migration.md
index 7ac8e4f..694b025 100644
--- a/docs/migration.md
+++ b/docs/migration.md
@@ -61,7 +61,7 @@ If you're currently using:
 Key system library updates (time64 transition):
 
 | Library | Bookworm | Trixie |
-|---------|----------|--------|
+| --------- | ---------- | -------- |
 | libpng | `libpng16-16` | `libpng16-16t64` |
 | libmagickwand | `libmagickwand-6.q16-6` | `libmagickwand-6.q16-7t64` |
 | libvips | `libvips42` | `libvips42t64` |

From 5b8931586c14332f1efd7c1ec9bd64e0e942dd9d Mon Sep 17 00:00:00 2001
From: KingPin <28669+KingPin@users.noreply.github.com>
Date: Sun, 17 May 2026 22:35:06 -0400
Subject: [PATCH 10/10] docs: align table pipes to satisfy markdownlint MD060

markdownlint v0.40.0 introduced MD060 (table-column-style) which
requires column-aligned pipes across header, separator, and data rows.
Reformatted env-var, deprecation-schedule, required-secrets,
build-arguments, and trixie-library tables to align column widths.
---
 README.md           | 50 ++++++++++++++++++++++-----------------------
 docs/ci.md          | 12 +++++------
 docs/local-build.md | 10 ++++-----
 docs/migration.md   | 12 +++++------
 4 files changed, 42 insertions(+), 42 deletions(-)

diff --git a/README.md b/README.md
index 9f2ca29..ef95d51 100644
--- a/README.md
+++ b/README.md
@@ -34,43 +34,43 @@ The following environment variables are applied at container startup by the s6-o
 
 ### 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 |
+| 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 |
+| 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 |
+| 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 |
+| 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 |
-| `PHP_SESSION_GC_MAXLIFETIME` | `1440` | Session garbage collection max lifetime |
-| `PHP_OPCACHE_MAX_ACCELERATED_FILES` | `10000` | OPCache maximum number of files |
-| `PHP_OPCACHE_REVALIDATE_FREQ` | `0` | How often to check script timestamps |
+| Variable                            | Default | Description                             |
+|-------------------------------------|---------|-----------------------------------------|
+| `PHP_DATE_TIMEZONE`                 | `UTC`   | Default timezone                        |
+| `PHP_SESSION_GC_MAXLIFETIME`        | `1440`  | Session garbage collection max lifetime |
+| `PHP_OPCACHE_MAX_ACCELERATED_FILES` | `10000` | OPCache maximum number of files         |
+| `PHP_OPCACHE_REVALIDATE_FREQ`       | `0`     | How often to check script timestamps    |
 
 ### Example usage
 
diff --git a/docs/ci.md b/docs/ci.md
index c7e0226..9b51991 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -69,12 +69,12 @@ matrix:
 
 To enable publishing, configure these GitHub repository secrets:
 
-| Secret | Description | Used For |
-| -------- | ------------- | ---------- |
-| `DOCKERHUB_USERNAME` | Docker Hub username | Docker Hub login |
-| `DOCKERHUB_TOKEN` | Docker Hub access token | Docker Hub authentication |
-| `QUAY_USERNAME` | Quay.io username | Quay.io login |
-| `QUAY_ROBOT_TOKEN` | Quay.io robot account token | Quay.io authentication |
+| Secret               | Description                 | Used For                  |
+|----------------------|-----------------------------|---------------------------|
+| `DOCKERHUB_USERNAME` | Docker Hub username         | Docker Hub login          |
+| `DOCKERHUB_TOKEN`    | Docker Hub access token     | Docker Hub authentication |
+| `QUAY_USERNAME`      | Quay.io username            | Quay.io login             |
+| `QUAY_ROBOT_TOKEN`   | Quay.io robot account token | Quay.io authentication    |
 
 **Note:** `GITHUB_TOKEN` is automatically provided by GitHub Actions for GHCR.
 
diff --git a/docs/local-build.md b/docs/local-build.md
index 62eaa33..2f9e0c3 100644
--- a/docs/local-build.md
+++ b/docs/local-build.md
@@ -127,11 +127,11 @@ docker buildx build \
 
 Both Dockerfile.v1 and Dockerfile.v2 accept these build arguments:
 
-| Argument | Description | Example |
-| ---------- | ------------- | --------- |
-| `VERSION` | Full version string | `8.5-fpm-alpine` |
-| `PHPVERSION` | PHP version only | `8.5` |
-| `BASEOS` | Base OS | `alpine` or `bookworm` |
+| Argument     | Description         | Example                |
+|--------------|---------------------|------------------------|
+| `VERSION`    | Full version string | `8.5-fpm-alpine`       |
+| `PHPVERSION` | PHP version only    | `8.5`                  |
+| `BASEOS`     | Base OS             | `alpine` or `bookworm` |
 
 ## Running Smoke Tests Locally
 
diff --git a/docs/migration.md b/docs/migration.md
index 694b025..5318def 100644
--- a/docs/migration.md
+++ b/docs/migration.md
@@ -60,13 +60,13 @@ If you're currently using:
 
 Key system library updates (time64 transition):
 
-| Library | Bookworm | Trixie |
-| --------- | ---------- | -------- |
-| libpng | `libpng16-16` | `libpng16-16t64` |
+| Library       | Bookworm                | Trixie                     |
+|---------------|-------------------------|----------------------------|
+| libpng        | `libpng16-16`           | `libpng16-16t64`           |
 | libmagickwand | `libmagickwand-6.q16-6` | `libmagickwand-6.q16-7t64` |
-| libvips | `libvips42` | `libvips42t64` |
-| libavif | `libavif15` | `libavif16t64` |
-| libmemcached | `libmemcached11` | `libmemcached11t64` |
+| libvips       | `libvips42`             | `libvips42t64`             |
+| libavif       | `libavif15`             | `libavif16t64`             |
+| libmemcached  | `libmemcached11`        | `libmemcached11t64`        |
 
 > **Note:** The `t64` suffix indicates [time64](https://wiki.debian.org/ReleaseGoals/64bit-time) support for 32-bit architectures. This does not affect x86_64 or arm64 users.