feat: add PHP 8.5 support and refresh docs

[KingPin]

Summary

• Adds PHP 8.5 to the build matrix (push, PR fast-path, publish, and v2 trixie includes in docker-ci.yml).
• Refreshes example tags throughout the docs from 8.3-... to 8.5-... so docs track the newest actively-built version.
• Adds a forward-looking deprecation schedule announcing PHP 8.2 removal after 2026-12-31 (upstream security-support end), with a generalised policy: drop from matrix when upstream security support ends; existing tags remain pullable.
• Corrects stale CI matrix snippets in docs/ci.md to match the real workflow.
• Adds CLAUDE.md project guide for AI assistants working in this repo.

Commits

1. feat: add PHP 8.5 to build matrix — full matrix + PR fast-path + publish + v2 trixie includes.
2. docs: add CLAUDE.md project guide for AI assistants — first commit of CLAUDE.md.
3. docs(ci): correct example matrices to match actual workflow — docs/ci.md snippets aligned with docker-ci.yml.
4. docs: bump example tags to PHP 8.5 and refresh supported-version prose — README, docs/, extras/ (8.3 row in tags table preserved as a real supported version).
5. docs: announce PHP 8.2 deprecation after 2026-12-31 — schedule table + policy note in README, docs/deprecated-images.md, CLAUDE.md.

Test plan

• CI matrix runs cleanly across all 8.5/8.4/8.3/8.2 × v1/v2 × fpm/cli/apache × alpine/bookworm-or-trixie combinations.
• PR fast-path (8.5 + 8.2) completes on this PR.
• public.ecr.aws/docker/library/php:8.5-* base images are pullable and install-php-extensions handles 8.5 (validated by the CI build itself; no local build was run before this PR).
• Markdown link check (docs-ci.yml) passes on the changed docs.
• Spot-check: README "Deprecation Schedule" section renders cleanly on GitHub.

Notes for reviewer

• The 8.3 row in the README tags table is intentionally preserved — only example tags were bumped, not the supported-version table.
• Dockerfile.v1 / Dockerfile.v2 still default ARG VERSION=8.3-cli-alpine. Deliberately not touched here because it's a behaviour change for docker build . without --build-arg. Can be a follow-up if desired.

[Copilot]

Pull request overview

Adds PHP 8.5 to the CI build/publish matrix and updates repository documentation/examples to reference the newest actively-built tags, while also documenting a PHP version deprecation policy/schedule.

Changes:

• Extend GitHub Actions CI (PR fast-path + full matrix + publish) to include PHP 8.5.
• Refresh docs/examples to use 8.5-* tags and add a deprecation schedule/policy note (incl. PHP 8.2 removal after 2026-12-31).
• Add CLAUDE.md repo guidance for AI assistants and update CI documentation snippets to match the workflow.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
.github/workflows/docker-ci.yml	Adds PHP 8.5 to PR fast-path + full build/publish matrices (incl. v2/trixie includes).
README.md	Updates example tags to 8.5 and adds a deprecation schedule section/policy note.
extras/test-build.sh	Updates usage/docs examples; script logic still needs to correctly parse apache tags.
extras/php_test.php	Refreshes run examples to use 8.5 tags.
docs/ci.md	Updates CI matrix examples; some workflow behavior descriptions still diverge from actual triggers/fail-fast config.
docs/deprecated-images.md	Updates migration guidance wording and adds upcoming deprecation schedule table.
docs/local-build.md	Updates local build examples to 8.5; script path references appear incorrect.
docs/migration.md	Updates example tags to 8.5; includes a bullseye-v2 alias claim that doesn’t match current CI publishing behavior.
docs/troubleshooting.md	Refreshes example tags to 8.5.
CLAUDE.md	Adds project/CI guidance; several statements/examples are out of sync with current repo behavior and this PR’s doc refresh.

Comments suppressed due to low confidence (3)

extras/test-build.sh:36

• parse_tag() only recognizes fpm or cli for the image type. Passing an *-apache-* tag (e.g., from docs/local-build.md) will be parsed as empty and default to fpm, causing the script to build the wrong image type. Update the type extraction regex/default to include apache so the tag is interpreted correctly.

    # 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 base OS (alpine, trixie, bookworm, bullseye)
    local baseos=$(echo "$tag" | grep -oE '(alpine|trixie|bookworm|bullseye)' || echo "alpine")

docs/local-build.md:65

• This examples block still uses ./test-build.sh instead of ./extras/test-build.sh, so the copy/paste commands won’t work in a clean checkout. Also, the v2 8.5-apache-bookworm example is potentially confusing given CI/published v2 Debian images are trixie-based; consider switching the example to *-trixie (or explicitly explaining that local v2 builds may use bookworm).

```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

# Build both v1 and v2
./test-build.sh both 8.5-cli-alpine

**docs/local-build.md:270**
* This section again references `./test-build.sh`, but the script lives under `extras/test-build.sh`. Please update this command (and any remaining occurrences) so the documented development workflow matches the repo layout.

1. Make changes to Dockerfile.v1 or Dockerfile.v2
2. Build locally using 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
6. CI pipeline will run automated tests

Testing Changes

# Build both variants
./test-build.sh both 8.5-fpm-alpine

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[KingPin]

Addressed the Copilot review in 3 follow-up commits:

56483d5 fix(test-build): recognize apache tags in parse_tag

• extras/test-build.sh:33 — added apache to the variant regex (was silently defaulting to fpm).

738d250 docs(local-build): correct test-build.sh paths and drop deprecated 8.1 example

• docs/local-build.md:42,57,258 — ./test-build.sh → ./extras/test-build.sh throughout.
• docs/local-build.md:65 — swapped the 8.1-cli-alpine example (8.1 is deprecated) for 8.5-cli-alpine, and added a one-line note that v2 bookworm tags are bookworm-v2 aliases for trixie-built images.

01f34c5 docs: correct out-of-date claims flagged in PR #36 review

• CLAUDE.md:7 — overview now includes apache type (with the apache-on-Debian-only caveat).
• CLAUDE.md:14-22 — bumped local-build example tags to 8.5 and replaced the broken smoke-test command with the bind-mount form (/extras/php_test.php was never copied into the image).
• CLAUDE.md:43 — stopped hard-coding "s6-overlay v3.2.1.0"; CI fetches the latest release at build time, v3.2.1.0 is the Dockerfile ARG default only.
• docs/migration.md:24 — removed the bullseye-v2 alias example; only bookworm-v2 aliases are created by the publish job. Added a migration note for bullseye users.
• docs/ci.md:44 — corrected the "Fails fast" claim (matrix runs with fail-fast: false).
• docs/ci.md:122 — corrected the Branch Testing section: push is restricted to main; non-main branches run via pull_request or workflow_dispatch.

Thanks @copilot-pull-request-reviewer for catching all of these — most predated this PR but are now correct.

[Copilot]

Addressed the Copilot review in 3 follow-up commits:

56483d5 fix(test-build): recognize apache tags in parse_tag...

The Documentation CI was still failing with 51 MD060/table-column-style markdownlint errors across 4 files. Fixed in commit 782f7d1:

• README.md env-var table separator rows converted to compact style (| --- |) — fixes missing-space errors at lines 38, 46, 54, 61, 69
• README.md Deprecation Schedule table header+separator col 3 widened by 1 char to align with After 2026-12-31 content — fixes pipe-alignment errors at lines 349–353
• docs/ci.md Required Secrets separator: |--------| → | -------- |
• docs/local-build.md Build Arguments separator: |----------| → | ---------- |
• docs/migration.md library transition separator: |---------| → | --------- |

markdownlint-cli2 now reports 0 errors locally.

[KingPin]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}