Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 13 additions & 10 deletions .phpcs.xml.dist
Original file line number Diff line number Diff line change
Expand Up @@ -61,19 +61,22 @@
<rule ref="Generic.CodeAnalysis.UnusedFunctionParameter"/>
<rule ref="Generic.Commenting.Todo"/>

<!-- Check for PHP cross-version compatibility. -->
<!--
To enable this, the PHPCompatibilityWP standard needs
to be installed.
See the readme for installation instructions:
https://github.com/PHPCompatibility/PHPCompatibilityWP
For more information, also see:
https://github.com/PHPCompatibility/PHPCompatibility
Check for PHP cross-version compatibility.

testVersion must stay in sync with the "Requires PHP" header in plugin.php.
It is what actually proves the floor: nothing else enforces it, since
composer.json declares no `require` php constraint and no config.platform.php.
The floor was wrong before this was switched on: the header claimed 7.0
while general.php used a `: void` return type (7.1+), so the plugin fatally
failed to parse on the version it advertised.

The open-ended "7.4-" form checks against 7.4 and every version above it,
so it catches both features too new for the floor and constructs removed in
later PHP.
-->
<!--
<config name="testVersion" value="5.2-"/>
<config name="testVersion" value="7.4-"/>
<rule ref="PHPCompatibilityWP"/>
-->

<!--
To get the optimal benefits of using WPCS, we should add a couple of
Expand Down
13 changes: 10 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,14 @@ composer run check # lint + test
`.phpcs.xml.dist` scans `plugin.php` and `lib/` (PHP only), so no paths are needed.
`tests/` is deliberately **not** scanned — see the comment in the ruleset.

The ruleset also runs **PHPCompatibilityWP** at `testVersion` `7.4-`, which is what
actually proves the `Requires PHP: 7.4` header in `plugin.php`. Nothing else enforces
that floor: `composer.json` declares no `require` php constraint and no
`config.platform.php`. **The two values must be changed together** — raising or lowering
one without the other silently re-opens the contradiction that issue #25 fixed. Note the
floor is a *runtime* claim about where the plugin may be installed; it is unrelated to
the PHP the test suite needs (PHPUnit 12 wants 8.3+).

**PHPCS currently passes clean — `composer run lint` exits 0 with zero errors and zero
warnings.** Keep it that way: any non-zero exit is a genuine regression.

Expand Down Expand Up @@ -110,9 +118,8 @@ None outstanding. All nine items from the original audit are fixed — see
## Known quirks

- No PHPStan config, no JS build pipeline (no blocks or interactive JS).
- `plugin.php` header declares `Requires PHP: 7.0`, but `lib/functions/general.php`
uses a `: void` return type (PHP 7.1+), so the plugin actually fatals on 7.0. The
declared floor is wrong. Tracked separately.
- The `Requires PHP` header and the PHPCS `testVersion` are a second pair that must stay
in sync by hand — see the note under **Commands → PHP**.
- `settings.php` and `general.php` each hard-code the literal
`ucsc-communications-functionality-settings` independently — one as the menu slug,
one in a `strpos()` screen check — with no shared constant. They must stay in sync
Expand Down
38 changes: 38 additions & 0 deletions ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -231,6 +231,44 @@ deliberate 1000-iteration guard in `have_rows()` that throws instead of hanging

## Resolved after the audit

### ~~`Requires PHP` header understated the real floor~~
**Status:** ✅ Fixed — [#25](https://github.com/ucsc/ucsc-communications-functionality/issues/25)
**Files:** `plugin.php`, `.phpcs.xml.dist`, `composer.json`

`plugin.php` declared `Requires PHP: 7.0`, but `lib/functions/general.php` declares
`ucsccomms_enqueue_admin_styles(): void` — a return type added in PHP 7.1. On 7.0 that
is a parse error, so the plugin did not merely misbehave on its advertised floor, it
fatalled on activation. `: void` was the *only* construct above 7.0 in the codebase, so
the true floor was 7.1.

Nothing enforced the claim either: no `require` php constraint in `composer.json`, no
`config.platform.php`, `"platform": {}` in the lock, and the `PHPCompatibilityWP` block
in `.phpcs.xml.dist` commented out since the ruleset was first written.

**Fixed by:** setting the header to **7.4**, adding
`phpcompatibility/phpcompatibility-wp` to `require-dev`, and switching on the ruleset
block with `testVersion` `7.4-`. The open-ended form also catches constructs *removed*
in later PHP, not just ones too new for the floor.

**7.4 over 8.1** was a deliberate call: it is the conservative claim, safely true of the
current code, and it keeps the widest install compatibility. Both are past EOL as of
August 2026 (7.4 since Nov 2022, 8.1 since Dec 2025), so neither is an endorsement — the
header is a statement about where the plugin *parses and runs*, not about what anyone
should be hosting on.

**`composer run lint` still exits 0** — the new standard produced zero findings against
the 204 lines of plugin code. That the sniff genuinely fires was mutation-checked:
setting `testVersion` to `7.0-` reports
`PHPCompatibility.FunctionDeclarations.NewReturnTypeDeclarations.voidFound` on
`general.php:25`, which is precisely the bug this issue described.

The floor is a runtime constraint and is independent of the test toolchain: PHPUnit ^12.5
needs PHP 8.3+ and CI runs it on 8.3/8.4, but PHPCompatibility proves the 7.4 floor
statically, with no 7.4 runtime anywhere. Conflating the two is what pushes projects back
onto PHPUnit 9.6 for no benefit.

---

### ~~Empty `src/` PSR-4 mapping~~
**Status:** ✅ Fixed — [#24](https://github.com/ucsc/ucsc-communications-functionality/issues/24)
**File:** `composer.json`
Expand Down
1 change: 1 addition & 0 deletions composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@

"require-dev": {
"dealerdirect/phpcodesniffer-composer-installer": "^1.1",
"phpcompatibility/phpcompatibility-wp": "^2.1",
"phpunit/phpunit": "^12.5",
"wp-coding-standards/wpcs": "^3.1"
},
Expand Down
215 changes: 214 additions & 1 deletion composer.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion plugin.php
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
* Description: Custom functionality for UCSC Communications and Marketing Website.
* Version: 1.0.5
* Requires at least: 6.1
* Requires PHP: 7.0
* Requires PHP: 7.4
* Author: UC Santa Cruz
* Author URI: https://github.com/ucsc
* License: GPL-3.0-or-later
Expand Down