Build/Tools: Update PHPCompatibilityWP to 3.0.0-alpha2

[rodrigosprimo]

This ticket proposes updating PHPCompatibilityWP from ~2.1.3 to 3.0.0-alpha2. WordPress currently uses PHPCompatibilityWP ~2.1.3 (resolves to 2.1.8), which depends on PHPCompatibility 9.3.5, released in December 2019. This means the PHP compatibility checks have very limited coverage for PHP 8+ changes.

PHPCompatibilityWP ​3.0.0-alpha2 was released in December 2025 and depends on PHPCompatibility ​10.0.0-alpha2, which provides more comprehensive coverage for PHP 8+ compatibility checks.

Why update

Without this update, WordPress has very little automated detection for PHP 8+ compatibility issues.

About the alpha status

PHPCompatibility 10.0.0 does not have a stable release yet, and there is no timeline for one. However, @jrf (the lead maintainer of PHPCompatibility and PHPCompatibilityWP) actively recommends using version 3.0.0-alpha2 of PHPCompatibilityWP:

• She recently opened a PR to do the same change that I'm proposing here for YoastCS: ​Yoast/yoastcs#426.
• There are a few comments she left recommending both PHPCompatibility 10.0.0@alpha and PHPCompatibilityWP 3.0.0@alpha: ​PHPCompatibilityWP#84, ​PHPCompatibilityWP#40 and ​PHPCompatibility#2017.
• She discussed this topic with @desrosj before and recommended that WP should start using PHPCompatibilityWP 3.0.0@alpha.

Also, the ​PHPCompatibility GitHub README documents ^10.0.0@dev as the recommended version.

The alpha status reflects that sniff coverage for all new PHP syntaxes isn't yet complete. However, the alpha is substantially more complete than the 6+ year old stable release.

Discussion points

Running the compat check with the updated version surfaces 124 new violations (47 errors, 77 warnings) across 44 files. I checked them, and they fall into the following categories:

1. Violations blocked by existing tickets: the largest group (40 errors) is NewHTMLEntitiesFlagsDefault.NotSet, which is already tracked in #53465. utf8_encode deprecations (3) are tracked in #55603. These can be temporarily excluded or annotated with references to the blocking tickets.

2. Intentional use of #[\SensitiveParameter]: 33 warnings for NewAttributes.PHPNativeAttributeFound. The use of this attribute is intentional (see #57304). It is silently ignored on PHP < 8.2 and active on 8.2+. I suggest this sniff be excluded in phpcompat.xml.dist.

3. Version-guarded deprecated calls: functions like curl_close(), imagedestroy(), xml_parser_free(), and finfo_close() are called inside PHP_VERSION_ID < 80000 or function_exists() guards. PHPCompatibility flags them because it doesn't check for the existence of such guards (see ​PHPCompatibility/PHPCompatibility#301). There is existing prior art for handling these with inline phpcs:ignore annotations and I think this should be the approach used.

4. Third-party bundled library issues: violations in Requests, SimplePie, getID3, and Snoopy that need exclusions in phpcompat.xml.dist as previously done for other files in those libraries. For Requests, these violations were already addressed upstream in ​Requests#988 (merged in v2.0.16); WordPress currently bundles 2.0.11, so the exclusions would be temporary until the bundled copy is updated. The best path for the other libraries will need further investigation.

5. Error code changes in v10: some existing exclusions and inline annotations need updating because PHPCompatibility 10.0 renamed error codes for functions that are both deprecated and removed (e.g. *Deprecated → *DeprecatedRemoved). See ​PHPCompatibility#1186 and ​#1199.

Additionally, besides updating the PHPCompatibilityWP version constraint, composer.json needs "minimum-stability": "dev" and "prefer-stable": true because PHPCompatibilityWP's own dependencies use @dev stability flags. This affects Composer's resolution behavior for the entire project, though prefer-stable ensures stable versions are chosen when available.

I'd appreciate feedback on whether updating to an alpha version of PHPCompatibilityWP is acceptable for Core, and if so, whether the suggested approaches for handling the new violations are reasonable. If there's agreement on the general direction, I'm willing to prepare a patch.

[rodrigosprimo]

After posting the ticket, I noticed a few things that could be corrected or that I missed. Adding them here as a comment, as it seems I don't have permission to edit the ticket description.

Corrections and clarifications:

1. The description says "The alpha status reflects that sniff coverage for all new PHP syntaxes isn't yet complete." That's not accurate. The alpha status is about preventing false positives and false negatives on new PHP syntaxes in pre-existing sniffs, not about adding coverage for new syntaxes.

2. Point 5 in the description says "PHPCompatibility 10.0 renamed error codes". To clarify: the error codes weren't explicitly renamed. PHPCompatibility 10.0 adds data about functions that were removed in PHP 8+. Functions that were previously only known to be deprecated now correctly show as both deprecated and removed, which changes the error code from Deprecated to DeprecatedRemoved.

Additions:

1. Another reason to update is that PHPCompatibility 10.0 fixes bugs in pre-existing sniffs, some of which affect WP Core. For example, there is currently a ​workaround in `phpcompat.xml.dist` to exclude a false positive for $this in static closures in script-loader.php (see ​PHPCompatibility#1481). This bug is fixed in 10.0.0-alpha1, so the workaround can be removed with this update.

2. I forgot to mention and include a link to the ​PHPCompatibility 10.0 upgrade guide, which is a useful reference for this update.

3. Regarding the Composer stability settings: using "minimum-stability": "dev" and "prefer-stable": true (which affects Composer's resolution behavior for the entire project) is one of the options. Another approach is to explicitly require PHPCompatibilityWP's own dependencies in require-dev:

"phpcompatibility/phpcompatibility-wp": "3.0.0-alpha2",
"phpcompatibility/php-compatibility": "10.0.0-alpha2",
"phpcompatibility/phpcompatibility-paragonie": "2.0.0-alpha2"

This way, only the PHPCompatibility packages are allowed to use unstable versions, without affecting other dependencies.

[desrosj]

@rodrigosprimo Thanks for opening this detailed report! I think that tackling these next steps will help support this update. I think this will help chunk through everything that needs to happen here.

• Note on the open issues for item 1 that this ticket is blocked by resolving those (unless temporary ignore statements are added, which I would like to avoid wherever possible).
• For item 4, please create a ticket for updating Requests to the latest version. Feel free to refer to this ticket and add context as to why updating is related.

I have yet to perform a deep dive into any of these points, but I wanted to give some quick, surface-level feedback to help push this along.

Given the surrounding circumstances and adoption of the 3.0.0alpha2 version, I am supportive of using this version once other outstanding issues are addressed. @johnbillion or @jorbin, do you have any objections to that?

The rest of your suggestions seem reasonable at first glance. I do think that I prefer your suggestion of adding the package's dependencies to the composer.json file over changing minimum-stability to dev is preferred.

Starting a pull request addressing the smaller ones here will also help to surface the violations being reported without having to run the scan. Items 2, 3, and 5 in the report description as well as 1 and 3 in your follow up is a great start. Then the PR can just be updated with the fixes merged to trunk through the other tickets.

Adding 2nd-opinion because it would be good to get thoughts from a few more contributors.

[johnbillion]

Yes I'm generally in favour. When is 3.0.0 stable planned?

This PR updates the PHPCompatibilityWP Composer dependency from ~2.1.3 to 3.0.0-alpha2 (which includes PHPCompatibility 10.0.0-alpha2) and addresses the new violations surfaced by the updated sniffs.

Changes are split into separate commits for easier review:

1. Update PHPCompatibilityWP to 3.0.0-alpha2: composer.json changes with explicit version pins for phpcompatibility/php-compatibility-wp, phpcompatibility/php-compatibility and phpcompatibility/phpcompatibility-paragonie.
2. Update phpcompat.xml.dist error codes: PHPCompatibility v10 adds removal data for functions/constants/directives removed in PHP 8+, changing their error codes from *Deprecated to *DeprecatedRemoved. Update the existing exclusion rules to match.
3. Update phpcompat.xml.dist exclusions: Add file-level exclusions for third-party bundled libraries (SimplePie, getID3, Snoopy, PHP AI Client) following the approach used in https://core.trac.wordpress.org/ticket/63168#comment:16. Also add a rule-level exclusion for the intentional use of #[\SensitiveParameter] (https://core.trac.wordpress.org/ticket/57304) and remove the workaround for PHPCompatibility#1481.
4. Update inline phpcs:ignore annotations: Add or update annotations in WordPress Core files for version-guarded deprecated function calls and function_exists/defined-guarded new function usage.
5. TEMP: Temporarily exclude violations tracked in separate tickets: This is a temporary commit to allow the PHP compatibility scan to pass. It excludes NewHTMLEntitiesFlagsDefault.NotSet (waiting for https://core.trac.wordpress.org/ticket/53465) and adds phpcs:ignore annotations for utf8_encode (https://core.trac.wordpress.org/ticket/55603). This commit should not be merged as-is; the plan is to wait for a decision on https://core.trac.wordpress.org/ticket/53465 and https://core.trac.wordpress.org/ticket/55603 before updating PHPCompatibilityWP.

Trac ticket: https://core.trac.wordpress.org/ticket/64634

[rodrigosprimo]

Thanks for the feedback, @desrosj.

Here's an update on the action items:

Requests library update: The Requests update from 2.0.11 to 2.0.17 has been committed in [61769] (#64752). Thanks for quickly reviewing it!

PR for the smaller items: [PR #11217](​https://github.com/WordPress/wordpress-develop/pull/11217) addresses items 2, 3, and 5 from the ticket description, plus follow-up items 1 and 3 from your comment. See the PR description for a summary of each commit.

For the third-party library violations (item 3), I used file-level exclusions in phpcompat.xml.dist rather than inline phpcs:ignore annotations, following the approach used in [63168#comment:16](https://core.trac.wordpress.org/ticket/63168#comment:16). This ensures the exclusions survive future library updates, but has the downside that we might miss other violations that might be introduced by these libraries in the same file for the same excluded sniff. The affected libraries are SimplePie, getID3, Snoopy, and the recently added Nyholm/Psr7. All violations are either version-guarded code (unreachable on the PHP versions where the deprecation applies) or deprecated function usage that the upstream library hasn't addressed yet.

The PR also includes a temporary commit to exclude violations tracked in separate tickets: NewHTMLEntitiesFlagsDefault.NotSet (#53465) and utf8_encode (#55603). This commit is not meant to be merged as-is; the plan is to wait for a decision on those tickets first. I've added a note to both tickets mentioning that this ticket is blocked by them.

---

@johnbillion, there is no planned date for the 3.0.0 stable release yet. PHPCompatibilityWP 3.0.0 depends on PHPCompatibility 10.0.0 stable, and there is no set timeline for that release, AFAIK.