Add PHP 8.2-8.5 version support upgrade skill and audit engine by noruzzamans · Pull Request #3 · Fueled/.github

noruzzamans · 2026-09-25T08:42:29Z

Description of the Change

Following the initiative outlined by @jeffpaul in #2, the architectural consultation with @dkotter, and the direction set by WooCommerce's PHP version support update, this pull request introduces a standardized, reusable AI Agent skill conforming to the @10up/agent-skills / agentskills.io specification to automate auditing and preparing open-source repositories for modern PHP support.

This skill is designed as the foundational precursor to streamline the PHP upgrade across the suite of 24 downstream repositories linked to #2 (including safe-redirect-manager, distributor, ElasticPress, classifai, safe-svg, etc.).

📁 Bundled Skill Architecture

skills/php-version-upgrade/
├── SKILL.md                                  # Core procedure, phase checklists, and execution guardrails
├── scripts/
│   └── audit_php_versions.mjs                # Standalone Node.js ESM scanner (single repo & batch mode)
└── references/
    ├── detection-and-tooling-matrix.md       # Configuration mappings for headers, Composer, linters, & CI
    ├── php82-85-deprecations.md              # Technical remediation catalog for PHP 8.2–8.5 deprecations
    ├── legacy-shims-catalog.md               # Catalog of obsolete polyfills and dead conditional blocks (< 8.2)
    └── targeted-modernizations.md            # Guardrails distinguishing high-value fixes from cosmetic churn

⚙️ Key Operational Capabilities

Automated Audit Engine (audit_php_versions.mjs):
- Pure Node.js ESM (zero external npm dependencies, Node 18+ native).
- Audits plugin/theme headers (Requires PHP), readme.txt, composer.json (require.php), phpcs.xml (testVersion), static analysis, and GitHub Actions CI matrices.
- Scans code patterns for dynamic properties, deprecated ${var} interpolation, utf8_encode(), auto_detect_line_endings, and obsolete polyfills native in PHP 8.0+.
- Features --batch mode for automated scanning across multiple repositories and --json for programmatic agent pipelines.
Dynamic Version Parameterization (Maintainer Guidance):
- Fully parameterized via CLI flags (--min=<version> and --max=<version>) with default baseline (8.2 and 8.5).
- Interactive agent invocation protocol prompting for custom boundaries, ensuring future-proof reusability (e.g., bumping to 8.3 or targeting 8.1).
- Dynamic CI matrix generation and version-aware legacy polyfill/shim pruning.
Deterministic Metadata & Tooling Standards:
- Elevates minimum runtime requirement floor to target minimum (default: 8.2) and maximum testing ceiling to target maximum (default: 8.5).
- Harmonizes PHPCS compatibility runtime (--runtime-set testVersion <min>-<max>) and PHPStan/Psalm targets.
- Synchronizes CI matrices (['8.2', '8.3', '8.4', '8.5']) with experimental: true for pre-GA PHP 8.5 containers.
Strict Non-Refactoring Guardrails:
- Strictly enforces Jeffrey Paul's rule: avoid unnecessary refactoring solely to adopt newer PHP syntax.
- Prohibits bulk parameter typing on public hooks, wholesale constructor promotion, or speculative match expression rewrites, ensuring surgical PR diffs and minimal maintainer friction.

Closes #2

How to test the Change

Verify script execution in a single repository (Default Boundaries):
```
node skills/php-version-upgrade/scripts/audit_php_versions.mjs /path/to/plugin
```
Confirm structured terminal report displays detected metadata, code pattern risks, and remediation action items.

Verify dynamic version parameterization (Custom Boundaries):

node skills/php-version-upgrade/scripts/audit_php_versions.mjs /path/to/plugin --min=8.3 --max=8.5

Verify JSON output mode:

node skills/php-version-upgrade/scripts/audit_php_versions.mjs /path/to/plugin --json

Verify batch mode across multiple plugins:

node skills/php-version-upgrade/scripts/audit_php_versions.mjs --batch=/path/to/plugins-dir

Verify skill documentation completeness:
Review SKILL.md and the 4 modular guides in references/ to ensure all procedures align with Fueled and 10up engineering standards.

Changelog Entry

Added - Reusable AI Agent skill and audit engine for PHP version support upgrades with dynamic parameterization.

Credits

Props @noruzzamans, @jeffpaul, @dkotter

Checklist:

I agree to follow this project's Code of Conduct.
I have updated the documentation accordingly.
I have added Critical Flows, Test Cases, and/or End-to-End Tests to cover my change.
All new and existing tests pass.

noruzzamans · 2026-09-25T16:10:27Z

Hi @dkotter and @jeffpaul,

Following our discussion on #2, this pull request has been updated with full dynamic parameterization and is now marked Ready for Review!

Summary of Updates:

Interactive Invocation (SKILL.md): Configured to prompt for target min (default: 8.2) and max (default: 8.5) PHP versions, ensuring the skill remains flexible for future upgrades (e.g. PHP 8.3) or custom baselines.
Dynamic CLI Arguments (scripts/audit_php_versions.mjs): Supports --min=<version> and --max=<version> flags for custom single and batch repository audits.
Dynamic CI Matrix & Shim Pruning: Matrix generation and obsolete polyfill/shim checks automatically adapt relative to the target versions specified.
Verification: Syntax verified with node --check and tested locally across single repositories (safe-redirect-manager, distributor) as well as batch mode.

Looking forward to your review and feedback whenever you have a moment!

dkotter · 2026-09-30T13:16:15Z

+  - phpstan.neon*
+  - .github/workflows/*.yml
+metadata:
+  author: Fueled & 10up


There does not need to be any references to 10up. That can be cleaned up to just be Fueled across all files

dkotter · 2026-09-30T13:16:30Z

+  - .github/workflows/*.yml
+metadata:
+  author: Fueled & 10up
+  version: "1.1.0"


Since this hasn't been released yet, any reason for this not to be 1.0.0?

dkotter · 2026-09-30T13:17:01Z

+## 🎯 Interactive Invocation & Version Configuration
+
+When invoking this skill, determine the target version boundaries:
+- **Target Minimum PHP Version Floor (`targetMin`):** `8.2` (Default for current Fueled/10up initiative)


Suggested change

- **Target Minimum PHP Version Floor (`targetMin`):** `8.2` (Default for current Fueled/10up initiative)

- **Target Minimum PHP Version Floor (`targetMin`):** `8.2`

dkotter · 2026-09-30T13:17:09Z

+
+When invoking this skill, determine the target version boundaries:
+- **Target Minimum PHP Version Floor (`targetMin`):** `8.2` (Default for current Fueled/10up initiative)
+- **Target Maximum Tested PHP Version Ceiling (`targetMax`):** `8.5` (Default for current Fueled/10up initiative)


Suggested change

- **Target Maximum Tested PHP Version Ceiling (`targetMax`):** `8.5` (Default for current Fueled/10up initiative)

- **Target Maximum Tested PHP Version Ceiling (`targetMax`):** `8.5`

dkotter · 2026-09-30T13:17:58Z

+
+## When to Use
+
+- Updating a Fueled or 10up open-source repository to modernize PHP requirements.


Any particularly reason this needs to mention Fueled or 10up here? I'd make this generic for any codebase, open source or not, owned by Fueled or not

dkotter · 2026-09-30T13:21:20Z

@@ -0,0 +1,164 @@
+# PHP 8.2–8.5 Deprecations and Incompatibilities Reference


I'd maybe include down to PHP 8 here, not just PHP 8.2+

dkotter · 2026-09-30T13:21:58Z

@@ -0,0 +1,76 @@
+# Legacy Shims and Dead Code Catalog
+
+When elevating the minimum supported PHP runtime floor to **PHP 8.2**, legacy conditional branches, compatibility shims, and polyfills for features introduced in PHP 8.0 and 8.1 become dead code.


Suggested change

When elevating the minimum supported PHP runtime floor to **PHP 8.2**, legacy conditional branches, compatibility shims, and polyfills for features introduced in PHP 8.0 and 8.1 become dead code.

When elevating the minimum supported PHP runtime floor to **PHP 8.2+**, legacy conditional branches, compatibility shims, and polyfills for features introduced in PHP 8.0 and 8.1 become dead code.

dkotter · 2026-09-30T13:23:07Z

@@ -0,0 +1,183 @@
+# Detection and Tooling Configuration Matrix
+
+This reference specifies the deterministic configuration, metadata, and continuous integration settings required when upgrading a WordPress plugin or theme repository to support **PHP 8.2 through PHP 8.5**.


So a lot still here references PHP 8.2 as the minimum, though someone can set a different minimum. If we want to keep referencing a specific minimum, I'd set that to PHP 8, not 8.2 so it's more flexible

…-8.5

noruzzamans · 2026-10-01T17:15:50Z

Thanks for the thorough review and great suggestions, @dkotter! All feedback points have been addressed in commit a07b4b0:

Initial Release Versioning: Reset SKILL.md version to 1.0.0.
Generic Invocation: Removed the (Default for current Fueled/10up initiative) annotations on targetMin and targetMax.
Codebase Generalization: Removed all organization-specific mentions across SKILL.md and references/targeted-modernizations.md to ensure the skill is completely generic for any WordPress plugin, theme, or library.
PHP 8.0–8.5 Coverage: Expanded the deprecation catalog down to PHP 8.0 (covering PHP 8.0 non-numeric string comparisons, internal TypeError/ValueError semantics, removed legacy functions, and PHP 8.1 null deprecations & #[\ReturnTypeWillChange]), renaming the guide to references/php80-85-deprecations.md.
Flexible Baseline Floor: Updated references/detection-and-tooling-matrix.md to reference PHP 8.0 as the flexible baseline floor example instead of hardcoded 8.2.
Legacy Shims Catalog: Updated minimum floor to PHP 8.2+ and documented tiered pruning rules for PHP 8.0+ and 8.1+ shims.

Ready for re-review!

noruzzamans added 2 commits September 25, 2026 14:41

Add PHP version upgrade skill and automated audit engine

d40231f

Improve workflow matrix detection in audit script

aa5ed9a

noruzzamans mentioned this pull request Sep 25, 2026

Create a skill for PHP 8.2–8.5 support upgrades #2

Open

1 task done

Add dynamic version parameterization to upgrade skill and audit engine

cf3b98f

noruzzamans marked this pull request as ready for review September 25, 2026 16:10

dkotter suggested changes Sep 30, 2026

View reviewed changes

Generalize upgrade skill and expand deprecation references to PHP 8.0…

a07b4b0

…-8.5

Navigation Menu

Repository navigation

Add PHP 8.2-8.5 version support upgrade skill and audit engine - #3

Add PHP 8.2-8.5 version support upgrade skill and audit engine#3
noruzzamans wants to merge 4 commits into
Fueled:trunkfrom
noruzzamans:feature/php-version-upgrade-skill

noruzzamans commented Sep 25, 2026 •

edited

Loading

Uh oh!

noruzzamans commented Sep 25, 2026

Uh oh!

dkotter Sep 30, 2026

Uh oh!

dkotter Sep 30, 2026

Uh oh!

dkotter Sep 30, 2026

Uh oh!

dkotter Sep 30, 2026

Uh oh!

dkotter Sep 30, 2026

Uh oh!

dkotter Sep 30, 2026

Uh oh!

dkotter Sep 30, 2026

Uh oh!

dkotter Sep 30, 2026

Uh oh!

noruzzamans commented Oct 1, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	- Target Minimum PHP Version Floor (`targetMin`): `8.2` (Default for current Fueled/10up initiative)
	- Target Minimum PHP Version Floor (`targetMin`): `8.2`

	- Target Maximum Tested PHP Version Ceiling (`targetMax`): `8.5` (Default for current Fueled/10up initiative)
	- Target Maximum Tested PHP Version Ceiling (`targetMax`): `8.5`


		## When to Use

		- Updating a Fueled or 10up open-source repository to modernize PHP requirements.

		@@ -0,0 +1,164 @@
		# PHP 8.2–8.5 Deprecations and Incompatibilities Reference

		@@ -0,0 +1,76 @@
		# Legacy Shims and Dead Code Catalog

		When elevating the minimum supported PHP runtime floor to PHP 8.2, legacy conditional branches, compatibility shims, and polyfills for features introduced in PHP 8.0 and 8.1 become dead code.

		@@ -0,0 +1,183 @@
		# Detection and Tooling Configuration Matrix

		This reference specifies the deterministic configuration, metadata, and continuous integration settings required when upgrading a WordPress plugin or theme repository to support PHP 8.2 through PHP 8.5.

Conversation

noruzzamans commented Sep 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of the Change

📁 Bundled Skill Architecture

⚙️ Key Operational Capabilities

How to test the Change

Changelog Entry

Credits

Checklist:

Uh oh!

noruzzamans commented Sep 25, 2026

Summary of Updates:

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

noruzzamans commented Oct 1, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

noruzzamans commented Sep 25, 2026 •

edited

Loading