---

Update on August 1, 2023: Added requirement to publish Make/CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. post that details the compatibility change for the release (added to the “Beta Support” removal process section). Props @chanthaboune.

Update on April 9, 2025: Use of the “compatible with exceptions” label has been retired. Full info here.

Update on July 8, 2025: The “Enough sites” criteria has been adjusted. The three-month incubation period has been dropped, and the betaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. label can be removed from the current major version retrospectively. Full info here.

---

Officially WordPress Core currently provides “beta support” (or “beta compatibility”) for PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher 8.0, 8.1, and 8.2, as per the compatibility table in the handbook. The term “beta support” was first used in 2020 for WordPress 5.6 and PHP 8.0, though no criteria were set for determining when it could be removed. When should WordPress Core be considered compatible with a specific PHP version? Could it be compatible even with known and documented incompatible exceptions? This proposal is being set forth by a group of trusted contributors (see the props list below) who have consistently focused on the overall forward and backward compatibility of WordPress in the context of PHP as a way to outline any criteria, data, or roadmap needed to answer these questions.

The scope and goals of this proposal are:

• Set the criteria for determining when WordPress Core has reached compatibility with a specific PHP version that WordPress supports.
• Once the criteria are met, then the “beta support” classification can be removed for that WordPress version and beyond.
• Set a phased approach for moving from “beta support” → to compatible with exceptions (optional) → to fully compatible.

The proposal starts with an understanding of what “compatibility” means, then dissects the meaning to identify indicators, and finally uses the indicators to build decision-making criteria.

What is outside the scope of this proposal?

• Theme or pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party compatibility. There is no guarantee that any theme or plugin a site owner uses is compatible with or safe to upgrade to a PHP version. Rather, this proposal is for WordPress Core itself.
• List of supported PHP versions. It is not for determining which PHP versions WordPress should support, e.g. PHP EOL (End of Life), raising the minimum supported PHP version, etc.

Quick navigation

1. What compatibility means
2. Identifying indicators
3. Proposed compatibility criteria
4. “Beta Support” removal process
5. Conclusion

1. What compatibility means

Because of the nature of WordPress usage and the commitment to our user base, compatibility is to be considered in the eyes of those users. The goal is to elevate the broader ecosystem to a state that is compatible with PHP 8. That requires that the Core software not just be compatible on its own, but also provides defenses against common problems seen in the transition to PHP 8, while continuing to function on older versions of PHP.

~ What does compatibility mean here? from WordPress and PHP 8.0 by @desrosj

Building upon the above quote, compatibility means:

WordPress Core’s compatibility with a specific PHP version happens when enough sites run without issues (a) in the ways users configure and use their sites (b) while also continuing to function on all older PHP versions WordPress supports.

Notice this description intentionally focuses on users with emphasis on the ways users use WordPress. WordPress is committed to being user-first. Technical decisions (including compatibility) should first focus on users and thus usage.

Is full 100% compatibility required before removing “beta support”?

No. This proposal does not require a full 100% compatibility requirement for removing “beta support”. Instead, it takes a more pragmatic phased approach.

Some PHP version features or changes are breaking changes that (a) may require more effort and time to fully resolve or (b) may not be fully resolvable due to various reasons such as external dependencies, backward compatibility, etc.

Imagine the scenario where the bulk of WordPress Core is compatible with a specific PHP version but there are one or more incompatibilities yet to be resolved. Should those incompatibilities blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. removing “beta support”? Or could those be accepted and documented as exceptions?

This proposal proposes the following phases:

• “beta support”
• compatible with documented exceptions
• full compatibility

Reaching full 100% compatibility may not always be possible or it may take extensive amount of time. This should not block the removal of the “beta support” label. If one version is blocked, then all versions after that version are also blocked. By taking a phased approach, the project retains flexibility to take decisions that are best for users and the broader ecosystem.

2. Identifying indicators

In dissecting the above meaning, the keys to achieve compatibility reside in:

• Enough sites: enough sites running on a given PHP version over enough time.
• Issues: all known compatibility issues resolved or accepted as incompatible.
• BC: compatibility changes are backward compatible with all earlier PHP versions WordPress supports.

Enough sites: What does a minimum threshold of sites signify?

Enough sites should indicate a variety of different usages. Usages are important.

It can indicate WordPress itself runs with different technical stacks of themes, plugins, configurations, and hosted environments.

WordPress is never used in isolation (without any theme or plugins), so WordPress itself being able to run on PHP 8 does not indicate “full” compatibility…

The state of PHP 8 support within the broader ecosystem (plugins, themes, etc.) is impossible to know.

~ WordPress and PHP 8.0 by @desrosj

Usages can also indicate a variety of the WordPress functionality is being used by users. Why is this important? It can indicate how much of the WordPress Core’s source code is being run on a specific PHP version with the different technical stacks.

Issues: What does “issues” signify?

If the number of sites running on a specific PHP version continues to grow over time, then an inference could be made that the sites run without issue. How so? The thinking is: why would the usage grow over time if there are compatibility issues blocking sites from running on the version? Using that logic, the growth of “enough sites” over time can indicate there are no known compatibility “issues”.

Historically, WordPress relies on users to provide feedback and report issues. Thus, the “issues” indicator also means all known compatibility issues are resolved or excluded. (Note: In TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress., the phpNN keyword convention (e.g. php80, php81, and php82) identifies a PHP compatibility issue or task. A new php-compatibility focus is also proposed for further help with identifying compatibility tickets.)

Thus, “issues” can be considered as a combination of the growth of enough sites over time and all reported and known compatibility issues are resolved or accepted as incompatible.

What is resolved?

A known issue is resolved by various actions including fixed, closed, accepted as not impacting compatibility, or documenting as being incompatible.

Backward compatibility: How does backward compatibility relate to PHP versions?

Users and user confidence. WordPress has a long history of prioritizing backward compatibility (also known as BC and back compatback compat Backward compatibility - a desire to ensure that plugins and themes do not break under new releases - is a driving philosophy of WordPress. While it is a commonly accepted software development practice to break compatibility in major releases, WordPress strives to avoid this at all costs. Any backward incompatible change is carefully considered by the entire core development team and announced, with affected plugins often contacted. It should be noted that external libraries, such as jQuery, do have backward incompatible changes between major releases, which is often going to be a greater concern for developers.) to ensure WordPress runs for users regardless of which PHP version they are using. In this way, users can upgrade to a newer PHP version with the confidence their site will continue to function.

PHP 8 introduces many breaking changes, meaning the changes in the language do not work on versions older than PHP 8. To make WordPress compatible with PHP 8, changes must also stay compatible with all PHP versions it supports.

How can backward compatibility be determined?

Each change must not change the previously intended behavior or code usage (e.g. function names or signatures, input types or data structures, return types or data structures, etc.) and must work on all WordPress supported PHP versions.

The adopted approach is to add automated tests prior to the compatibility change and then ensure the change does not alter the behavior or code usage.

3. Proposed compatibility criteria

Using the above indicators, let’s build criteria for determining when a WordPress version is compatible with a specific PHP version.

All of these indicators must be true for a specific PHP version:

• Enough sites: At least 10% (i.e. usage percentage) of all WordPress sites running on a specific or newer PHP version for at least 3 months.
  • The usage percentage is calculated by combining usages of the target version plus all newer versions. For example, the PHP 8.0 % of usage is the sum of usage from 8.0, 8.1, 8.2, etc.
• Issues:
  • All reported and known compatibility issues are resolved.
  • All accepted incompatibilities are documented as exceptions from full compatibility.
• BC: Full backward compatibility is maintained for all older PHP versions WordPress supports, demonstrated with automated tests for each compatibility change.

The criteria in action for WordPress 6.3

Let’s see the proposed compatibility criteria in action. Could the “beta support” label be removed in WordPress 6.3 for different PHP 8 versions?

As of June 19, 2023:

• Enough sites:
  • PHP 8.0: 13.49% (+8.92% from PHP 8.1 +1.41% from PHP 8.2 = 23.82% ✅ )
  • PHP 8.1: 8.92% (+1.41% from PHP 8.2 = 10.33% ✅ )
  • PHP 8.2: 1.41%
• Issues:
  • Current list of reported issues:
    • PHP 8.0: 24 open Trac tickets
    • PHP 8.1: 18 open Trac tickets (plus the PHP 8.0 tickets)
    • PHP 8.2: 11 open Trac tickets (plus the PHP 8.0 and 8.1 tickets)
  • Possible Incompatibilities for acceptance consideration:
    • Named parameters: Should WordPress be fully-compatible with named parameters? There are backward compatibility (BC) considerations to consider. Once WordPress is compatible with a specific PHP version, the names of function/method parameters can never change as any changes would be a BC break (See Trac 57838).
    • Explicitly setting default value of the flags parameter for htmlentities() et all (See Trac 53465).
• BC: there are no known unresolved backward compatibility issues, though there is not a specific keyword available for tracking.

PHP 8.0 and 8.1 meet the minimum “enough sites” criteria, but have open tickets that need to be resolved to pass the “issues” criteria. Once each is resolved or accepted as incompatible, then it is possible for WordPress 6.3 to be declared compatible (possibly with incompatibility exceptions) with PHP 8.0 and 8.1.

Why not use the automated test suites as the compatibility indicator?

Automated tests are an important part of the testing and feedback loopLoop The Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. https://codex.wordpress.org/The_Loop. strategy in software development. A good set of tests can identify problems before the code ships to users.

But as previously noted, users are not running WordPress by itself, but rather as part of a stack of technologies. Knowing the majority of possible usage scenarios (such as an array of different themes and plugins) to use as test data is difficult. Thus, automated testing is part of an overall strategy when combined with the other indicators previously noted.

The automated tests are not included as part of the indicators. Currently the WordPress automated test suites are not yet significant or good enough to indicate with confidence that the source code is fully compatible and meets all of the above criteria.

What is required for the test suites to be considered significant and good enough?

• The vast majority of the code would need to be exercised by the tests.
• A broad set of scenarios for what should (happy path) and shouldn’t (unhappy path) happen in the ways users configure and use WordPress.

Currently, the WordPress Core’s automated test suites do not meet this criteria. For example, using the published code coverage report, less than half of the code is being exercised by tests. (Note: the published code coverage report is misleading as it represents “unclean” code coverage. The actual percentage is significantly lower. Work is ongoing to improve the reporting .) In addition, the test suites need to grow their testing scenarios to include the different ways users use WordPress.

4. “Beta Support” removal process

Once the above criteria are met, then the “beta support” classification can be removed for the next major WordPress release. Since only the most recent major branchbranch A directory in Subversion. WordPress uses branches to store the latest development code for each major release (3.9, 4.0, etc.). Branches are then updated with code for any minor releases of that branch. Sometimes, a major version of WordPress and its minor versions are collectively referred to as a "branch", such as "the 4.0 branch". of WP is supported, previous versions of WP with “beta support” for a PHP version will remain, even if security updates are pushed to older branches after the fact.

The process for each PHP version:

• Verify all of the above criteria are met.
  • Pull the site usage numbers to verify usage meets the criteria.
  • Triagetriage The act of evaluating and sorting bug reports, in order to decide priority, severity, and other factors. all php-compatibility tickets for the PHP version (phpNN keyword) to ensure all tickets are resolved.
  • Verify backward compatibility.
• Gather the list of accepted incompatibilities.
• Identify and resolve dependency needs, such as a MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. change for Site Health to get the “recommended PHP” version via an APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. call.
• When adding the next major releasemajor release A release, identified by the first two numbers (3.6), which is the focus of a full release cycle and feature development. WordPress uses decimaling count for major release versions, so 2.8, 2.9, 3.0, and 3.1 are sequential and comparable in scope. to to the PHP Compatibility and WordPress Versions handbook page, do not add the * next to that specific PHP version. If there are incompatibilities, add ** next to the PHP version and list each incompatibility below the table.
• Publish a Make/Core post that details what the compatibility change means for users and extenders.

5. Conclusion

This post presents a thoroughly referred recommendation for when to remove “beta support” from PHP 8 and newer versions. The criteria were a result of the feedback from several contributors listed below. However, it is only a proposal and is not concrete. Adjustments can be made to this proposal based on feedback from contributors in the comments below. If you have any thoughts, please do leave them below!

Unless there is a need to republish a modified version of this proposal for further feedback, after a consensus is reached and any needed approval from leadership to implement this proposal is received, the following action items would need to be addressed:

• The Make WordPress Core handbook should be updated in the appropriate places to:
  • outline the criteria and process for reviewing each “beta support” PHP version with each WordPress major release.
  • add PHP Compatibility keywords and php-compatibility focus on the Trac handbook page to specify what they are and when to use each. (Status: Done on Aug 2, 2023 ✅)
  • update or add a new major release on the PHP Compatibility and WordPress Versions handbook page, including adding a list of any incompatibilities with a PHP version(s) (Status: Done on Aug 8, 2023 ✅)
• Trac:
  • Add php-compatibility focus, which will be listed in “Contributor Focuses”. (Status: Done on Aug 1, 2023 ✅)
  • Contributors should scrub all tickets for PHP compatibility to (Status: Done as of Aug 8, 2023 ✅)
    • Add the php-compatibility focus with a description of “Relating to PHP forward and backwards compatibility. A phpNN keyword identifies the PHP version that introduced the incompatibility”.
    • Update the PHP version phpNN keyword, if necessary.
    • Determine the ticketticket Created for both bug reports and feature development on the bug tracker. status and next step toward resolution, including: close with a message why, complete, or get consensus on ones to be accepted as incompatible.
• Any other action items identified while discussing this proposal.

Props to @jrf @joemcgill @mikeschroder @desrosj @azaozz @costdev @ironprogrammer @antonvlasenko for contributing to this post through providing feedback and proof-reading.

#php, #php-8-0, #php-compatibility