[wp-trac] [WordPress Trac] #64634: Build/Tools: Update PHPCompatibilityWP to 3.0.0-alpha2

[WordPress Trac]

#64634: Build/Tools: Update PHPCompatibilityWP to 3.0.0-alpha2
-------------------------------+-----------------------------
 Reporter:  rodrigosprimo      |      Owner:  (none)
     Type:  enhancement        |     Status:  new
 Priority:  normal             |  Milestone:  Awaiting Review
Component:  Build/Test Tools   |    Version:
 Severity:  normal             |   Keywords:
  Focuses:  php-compatibility  |
-------------------------------+-----------------------------
 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
 [https://github.com/PHPCompatibility/PHPCompatibilityWP/releases/tag/3.0.0-alpha2
 3.0.0-alpha2] was released in December 2025 and depends on
 PHPCompatibility
 [https://github.com/PHPCompatibility/PHPCompatibility/releases/tag/10.0.0-alpha2
 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: [https://github.com/Yoast/yoastcs/pull/426
 Yoast/yoastcs#426].
 * There are a few comments she left recommending both PHPCompatibility
 10.0.0 at alpha and PHPCompatibilityWP 3.0.0 at alpha:
 [https://github.com/PHPCompatibility/PHPCompatibilityWP/issues/84#issuecomment-3591642658
 PHPCompatibilityWP#84],
 [https://github.com/PHPCompatibility/PHPCompatibilityWP/issues/40#issuecomment-3632877563
 PHPCompatibilityWP#40] and
 [https://github.com/PHPCompatibility/PHPCompatibility/issues/2017#issuecomment-3612954618
 PHPCompatibility#2017].
 * She discussed this topic with @desrosj before and recommended that WP
 should start using PHPCompatibilityWP 3.0.0 at alpha.

 Also, the [https://github.com/PHPCompatibility/PHPCompatibility?tab
 =readme-ov-file#composer-project-based-installation PHPCompatibility
 GitHub README] documents `^10.0.0 at 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
 [https://github.com/PHPCompatibility/PHPCompatibility/issues/301
 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
 [https://github.com/WordPress/Requests/pull/988 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
 [https://github.com/PHPCompatibility/PHPCompatibility/pull/1186
 PHPCompatibility#1186] and
 [https://github.com/PHPCompatibility/PHPCompatibility/pull/1199 #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.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/64634>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform