Create a skill for PHP 8.2–8.5 support upgrades

Is your feature related to a problem? Please describe.

Create a reusable skill for Fueled (and 10up) open source projects that analyzes a repository and prepares it to support PHP 8.2 through PHP 8.5. Note that 8.2 was selected as its still receiving security fixes through year and and is still a reasonable percent of usage across our plugins.

Following the direction outlined in WooCommerce's PHP version support update, the skill should:

Detect the project's current minimum and maximum supported PHP versions
Raise the minimum supported version to PHP 8.2
Raise the maximum supported/tested version to PHP 8.5
Update relevant version declarations and compatibility configuration, such as composer.json, plugin metadata, PHPCompatibility, static analysis, and other tooling
Ensure CI tests the supported PHP 8.2–8.5 range
Identify dependencies or code that may be incompatible with PHP 8.2–8.5, including newer PHP deprecations
Identify compatibility shims, conditionals, or other code supporting PHP versions below 8.2 that can now be removed or simplified
Highlight targeted opportunities to take advantage of PHP 8.2+ where doing so meaningfully improves the code, without refactoring solely to use newer syntax
Update relevant documentation indicating the supported PHP range

The skill should produce or recommend the changes necessary to make the repository confidently support PHP 8.2 through 8.5, and flag anything requiring manual review rather than silently assuming compatibility.

Designs

Running the skill against a repository should leave it declaring PHP 8.2 as its minimum, testing through PHP 8.5, and provide a clear set of any additional compatibility or modernization changes needed.

Describe alternatives you've considered

No response

Code of Conduct

I agree to follow this project's Code of Conduct

@jeffpaul

Hi @jeffpaul,

Following up on our discussion in 10up/safe-redirect-manager#466, I would love to help author this reusable PHP 8.2–8.5 upgrade skill for the Fueled and 10up ecosystem!

To ensure seamless, deterministic compatibility across the entire suite of 24 downstream repositories you linked to this initiative (including classic plugins, block-based tools, multisite distribution, and cloud/AI integrations), I've mapped out an enterprise-grade architectural specification following the @10up/agent-skills / agentskills.io standard:

📁 Proposed 6-File Skill Bundle

skills/php-version-upgrade/
├── SKILL.md                                  # Core procedure, phase checklists, and execution guardrails
├── scripts/
│   └── audit_php_versions.mjs                # Deterministic Node.js CLI script (single & batch mode)
└── references/
    ├── detection-and-tooling-matrix.md       # Location & regex mappings for headers, Composer, linters, & CI
    ├── php82-85-deprecations.md              # Technical reference for PHP 8.2–8.5 breaking changes & notices
    ├── legacy-shims-catalog.md               # Catalog of obsolete polyfills and dead conditional blocks (< 8.2)
    └── targeted-modernizations.md            # Guardrails for high-value improvements (Strictly avoids fluff refactorings)

⚙️ Core Operational Highlights

Deterministic Discovery (audit_php_versions.mjs):
- Automatically inspects composer.json (require.php), plugin headers (Requires PHP:), readme.txt, PHPCS compatibility runtime (testVersion), PHPStan/Psalm configs, and GitHub Actions workflow matrices (.github/workflows/*.yml).
- Supports both single-plugin auditing and --batch mode across repositories.
Metadata & Tooling Harmonization:
- Elevates minimum requirement to 8.2 and maximum testing ceiling to 8.5.
- Aligns PHPCompatibility (--runtime-set testVersion 8.2-8.5) and PHPStan target versions.
- Synchronizes CI matrices ([ '8.2', '8.3', '8.4', '8.5' ]) with experimental handling for PHP 8.5 where container images are pending.
Legacy Shim & Dead Code Pruning:
- Detects obsolete conditional blocks (e.g. version_compare( PHP_VERSION, '8.1', '<' ), auto_detect_line_endings) and polyfills for functions native to PHP 8.0–8.1 (str_contains, str_starts_with, etc.).
Targeted Value-Add Modernization (Zero Fluff):
- Strictly enforces the rule: no unnecessary refactoring solely for modern syntax. Highlights only high-impact improvements (e.g. readonly properties, native return types) while preserving surgical review friction.
Human-in-the-Loop Audit Report:
- Flags external dependency incompatibilities or ambiguous dynamic properties (#[\AllowDynamicProperties]) requiring maintainer review.

I have set up the local clone, and can validate the detection engine across the linked repositories before submitting the upstream PR. Does this architectural direction align with your expectations?

@dkotter

@dkotter how does the approach above sound to you?

Overall this looks pretty solid. The one thing I'd suggest is while we are looking to bump our minimum PHP version to 8.2 and "tested up to" PHP version to 8.5, it would probably be nice to keep this a bit more generic so it works on other versions.

In my head I imagined this as a skill you invoke and then it asks what your minimum and maximum PHP versions are and it will proceed from those. This ensures the skill will work when we bump our minimum to PHP 8.3, as an example. Or if we (or someone else) wants to bump to PHP 8.1 instead of forcing 8.2.

@dkotter

Hi @dkotter,

Thank you so much for the feedback! That makes total sense—keeping the skill generic and parameterized will make it far more reusable and future-proof across different repositories and future upgrade cycles.

Following your guidance, here is how I am planning to structure it:

Interactive Version Prompts: When the skill is invoked, it will prompt for the target min and max PHP versions (with 8.2 and 8.5 as sensible defaults for our current initiative). This way, if someone wants to target 8.1 or bump to 8.3 later, they can just specify it.
Dynamic CLI Flags in the Audit Engine: Update audit_php_versions.mjs to accept --min=<version> and --max=<version> arguments (e.g. --min=8.3 --max=8.5), defaulting to 8.2/8.5 if not provided.
Dynamic Rule & Matrix Generation:
- Dynamically build the CI matrix for workflows between the selected min and max versions.
- Synchronize Requires PHP, composer.json, and PHPCS testVersion to the chosen boundaries.
- Evaluate obsolete polyfills and legacy version shims dynamically against the specified minimum version.

Does this direction look right to you, or do you have any additional thoughts or suggestions on this?

If this looks good, I'll be happy to apply these changes directly to draft PR #3!

@noruzzamans

@noruzzamans Looks good to me, happy to review something when it's ready. Thanks!

Hey I guess I am late to this, but I did want to submit what I had anyway in case another alternative is of interest. It leverages phpcompatibility-wp.

This PR is what I used to test it: 10up/Ad-Refresh-Control#238

Feel free to close if you already have what you need.

Navigation Menu

Repository navigation

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

Is your feature related to a problem? Please describe.

Designs

Describe alternatives you've considered

Code of Conduct

📁 Proposed 6-File Skill Bundle

⚙️ Core Operational Highlights

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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

Description

Is your feature related to a problem? Please describe.

Designs

Describe alternatives you've considered

Code of Conduct

Activity

noruzzamans commented on Sep 25, 2026

📁 Proposed 6-File Skill Bundle

⚙️ Core Operational Highlights

jeffpaul commented on Sep 25, 2026

dkotter commented on Sep 25, 2026

noruzzamans commented on Sep 25, 2026

dkotter commented on Sep 25, 2026

PypWalters commented on Oct 2, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions