From 4cb0f82e2454a57d79632c632bf3ba76e395d114 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 23:21:21 +0000 Subject: [PATCH 1/2] Put research on a PHP 8.x floor on the roadmap A pending todo holds the brief and the first findings: no performance gain, a few lines of leaner code, modest maintainability gains mostly from native types, and a real cost in sites left behind. It lists the research still needed before deciding. The roadmap's compatibility backlog points to it. Also ignores .claude/ in Prettier: Claude Code agent worktrees are whole checkouts and made format:check flag 110 files. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01KbVuMPN7YTcV27vwsG3LZ2 --- .planning/ROADMAP.md | 9 +++ .../2026-10-14-research-php-8x-floor.md | 73 +++++++++++++++++++ .prettierignore | 3 + 3 files changed, 85 insertions(+) create mode 100644 .planning/todos/pending/2026-10-14-research-php-8x-floor.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index b7e1ac22..ef8e4d0d 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -371,6 +371,15 @@ Planned next: justifies it - consider a SQLite lane if a concrete compatibility risk appears +Under consideration: **raising the PHP floor from 7.4 to 8.x.** Research +first; no decision. See the pending todo +`2026-10-14-research-php-8x-floor.md` for the brief and the first findings. +In short, the 2026-10-14 check found almost no gain: no PHP 8 syntax would +simplify the current code, and only one helper exists because of 7.4. +WordPress core still supports 7.4. Revisit when core raises its own minimum +or 7.4 falls below about 5% of WordPress.org installs; if the floor is +raised, go straight to 8.1. + ## WordPress.org launch status Completed release and launch work: diff --git a/.planning/todos/pending/2026-10-14-research-php-8x-floor.md b/.planning/todos/pending/2026-10-14-research-php-8x-floor.md new file mode 100644 index 00000000..516a60b5 --- /dev/null +++ b/.planning/todos/pending/2026-10-14-research-php-8x-floor.md @@ -0,0 +1,73 @@ +--- +created: 2026-10-14T23:20:00Z +title: Research raising the PHP floor from 7.4 to 8.x +area: compatibility +files: + - bibliography-builder.php + - readme.txt + - phpcs.xml.dist + - .github/workflows/runtime-matrix.yml + - docs/planning/refactor-and-standards-memo.md +--- + +## Problem + +The plugin declares `Requires PHP: 7.4`. PHP 7.4 has been end-of-life since +November 2022, 8.0 since November 2023, and 8.1 since December 2025. The +question is whether a PHP 8.x floor would pay for the sites it leaves behind. +Sites below a raised floor stop getting Borges updates, including security +fixes. + +## First findings (2026-10-14, against `main` after #151) + +- **Performance: no gain.** How fast PHP runs depends on the host's PHP + version, not on the plugin's declared minimum. A site already on 8.x runs + Borges exactly as fast either way. Raising the floor only excludes 7.x + sites. The JIT does not help WordPress-style request handling, and citeproc + formatting runs only in the editor. +- **Leaner code: a few lines.** + - PHPCompatibilityWP (`testVersion 7.4-`, #151) finds zero violations, so + 7.4 has never forced a workaround. + - One helper exists only because of 7.4: `bibliography_builder_is_list_array()` + would become `array_is_list()` (8.1). + - `str_contains()` and similar are already polyfilled by WordPress. + - The arXiv resolver's DOCTYPE guard mentions 7.4 hosts but is sound on any + version; keep it. + - The code has no `switch` statements for `match` to replace, and its data + is arrays, not objects, so `?->` would not help. +- **Maintainability: modest, mostly types.** + - Union types (8.0), enums and `readonly` (8.1) would turn about 100 + `mixed` / `array|…` docblocks into types PHP enforces. Style keys could + become an enum. + - Most of that safety is available now through Psalm tightening (memo + Phase D) without a floor change. + - Two PHP 7.4 runtime-matrix cells would go. + - Dev tooling already needs 8.3 (PHPUnit 12). citeproc-php needs only 7.3. +- **Audience.** + - WordPress core dropped 7.2 and 7.3 in January 2026; 7.4 is its minimum and + 8.3 its recommendation. + - About 62% of WordPress.org-reporting sites run PHP 8.2 or older (late + September 2026). + - No current figure for 7.4 alone was found; get it from the WordPress.org + stats page before deciding. + +## Research still to do + +1. Get the current PHP 7.4, 8.0 and 8.1 shares from WordPress.org stats (and + W3Techs as a cross-check), and follow the trend over two or three quarters. +2. Track WordPress core's own PHP-minimum plans (make.wordpress.org/core). +3. Check what comparable block plugins in the directory require, using the + Veloria directory data. +4. List the type declarations, enums and `readonly` uses that an 8.1 floor + would enable, and estimate the change size; weigh it against Psalm + tightening alone. +5. Decide how to warn sites first: a release note, and possibly an admin + notice on PHP < 8.1 one release ahead (without adding stored settings; the + persistence audit forbids options). + +## Recommendation so far + +Keep 7.4 for now. Revisit when WordPress core moves its minimum to 8.x or 7.4 +drops below about 5% of installs. When raising, go straight to **8.1**: it is +the first version whose features (`array_is_list`, enums, `readonly`) buy +anything here. diff --git a/.prettierignore b/.prettierignore index 58fe6384..c0b9fd8e 100644 --- a/.prettierignore +++ b/.prettierignore @@ -27,3 +27,6 @@ src/**/__snapshots__/ # Benchmark input data. src/benchmarks/fixtures/ + +# Local Claude Code state, including agent worktrees (whole checkouts). +.claude/ From c6ba1bbb07d470d346b4cdc068e14beb917219e0 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 23:21:43 +0000 Subject: [PATCH 2/2] Note that Phase D gets most of a PHP 8.x floor's benefit Psalm tightening enforces the types a PHP 8.x floor would add, in CI rather than on users' servers, so no PHP 7.4 site is cut off. Recorded in the floor todo's recommendation, the roadmap entry, and the memo's Phase D. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01KbVuMPN7YTcV27vwsG3LZ2 --- .planning/ROADMAP.md | 3 ++- .planning/todos/pending/2026-10-14-research-php-8x-floor.md | 4 ++++ docs/planning/refactor-and-standards-memo.md | 2 ++ 3 files changed, 8 insertions(+), 1 deletion(-) diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index ef8e4d0d..4ab86715 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -378,7 +378,8 @@ In short, the 2026-10-14 check found almost no gain: no PHP 8 syntax would simplify the current code, and only one helper exists because of 7.4. WordPress core still supports 7.4. Revisit when core raises its own minimum or 7.4 falls below about 5% of WordPress.org installs; if the floor is -raised, go straight to 8.1. +raised, go straight to 8.1. Meanwhile, the refactor memo's Phase D (Psalm +tightening) gets most of the maintainability benefit with nobody left behind. ## WordPress.org launch status diff --git a/.planning/todos/pending/2026-10-14-research-php-8x-floor.md b/.planning/todos/pending/2026-10-14-research-php-8x-floor.md index 516a60b5..52e0cdb2 100644 --- a/.planning/todos/pending/2026-10-14-research-php-8x-floor.md +++ b/.planning/todos/pending/2026-10-14-research-php-8x-floor.md @@ -67,6 +67,10 @@ fixes. ## Recommendation so far +**Phase D gets most of the maintainability benefit of a PHP 8.x floor with nobody left behind.** Psalm tightening (memo Phase D) gives most of the type safety +an 8.x floor would, without excluding any site, so do Phase D first and judge +the floor on what is left. + Keep 7.4 for now. Revisit when WordPress core moves its minimum to 8.x or 7.4 drops below about 5% of installs. When raising, go straight to **8.1**: it is the first version whose features (`array_is_list`, enums, `readonly`) buy diff --git a/docs/planning/refactor-and-standards-memo.md b/docs/planning/refactor-and-standards-memo.md index 5f0332a1..863fff33 100644 --- a/docs/planning/refactor-and-standards-memo.md +++ b/docs/planning/refactor-and-standards-memo.md @@ -170,6 +170,8 @@ Each ticket below is one PR that can be lifted to the issue tracker on its own. **Phase D: static analysis** +*Why it comes before any PHP floor change:* Phase D gets most of the maintainability benefit of a PHP 8.x floor with nobody left behind. Psalm's stricter levels enforce the same types that PHP 8's native union types and enums would, but in CI, not on the user's server, so no site on PHP 7.4 is cut off. See `.planning/todos/pending/2026-10-14-research-php-8x-floor.md`. + 12. **Psalm level 5** with a baseline. 13. **`checkJs` pilot** on `src/lib/`, non-blocking at first. 14. **Psalm level 4** with a baseline, once level 5 is clean.