Proposal: Criteria for Removing “Beta Support” from Each PHP 8+ Version


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.


Officially WordPress Core currently provides “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. 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:
    • 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.
  • 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

Dev Chat Summary, May 10, 2023

The WordPress Developers Chat meeting took place on May 10, 2023 at 20:00 UTC in the core channel of Make WordPress Slack.

Key Links

Highlighted Posts

Here’s an overview of updates in TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. between May 1 and May 8, 2023:

  • 24 commits
  • 56 contributors
  • 46 tickets created
  • 9 tickets reopened
  • 49 tickets closed
  • and 5 new contributors in this period 🎉 Welcome!
  • What’s new for developers? (May 2023): Check out this nifty guide to some of the latest WordPress updates, especially suited for extenders or contributors who would like to learn more about developing with WordPress.
  • WP Briefing: Episode 55: Happy Anniversary, WordPress!: Take a look back on the past 20 years and how the open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. community has grown WordPress into what it is today.
  • What’s new in Gutenberg 15.7? (03 May): This is of the best places to see what’s new in the 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, as well as what’s in store for the future of CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress..
  • @webcommsat shared: It is day two of the “#WP20 From Blogs to Blocks” campaign. We have had a request from #marketing to highlight this in #core and encourage more devs to take part too: https://github.com/WordPress/Marketing-Team/issues/220.

Release Updates

  • WordPress 6.2.1 RC1 is now available: Help test this first minor releaseMinor Release A set of releases or versions having the same minor version number may be collectively referred to as .x , for example version 5.2.x to refer to versions 5.2, 5.2.1, 5.2.3, and all other versions in the 5.2 (five dot two) branch of that software. Minor Releases often make improvements to existing features and functionality. candidate (RCrelease candidate One of the final stages in the version release cycle, this version signals the potential to be a final release to the public. Also see alpha (beta).) for 6.2 before next week’s final release. See the post for details on what’s been fixed, and watch the #6-2-release-leads channel for additional updates.
  • And a reminder, for those who haven’t submitted feedback for the WP 6.2 release retrospective — @priethor has noted that the original survey deadline has been extended, so please make sure to take this opportunity to help improve future releases!

Maintainers: Component Help Requests

@oglekler indicated a draft patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing. was ready, and requested contributor involvement with #23348: Add a “Contribute” tab to the about page. @audrasjb agreed with the proposed update, but had a question about some of the languages included in the language options. Olga clarified that those were included in mobile apps, but that clarity was needed to avoid this appearing as a mistake.

Open Floor

PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher 8.x Compatibility

@xavivars asked about PHP supported versions, and documentation surrounding it. He pointed out misconceptions that WordPress wouldn’t work under PHP 8.x due to its “beta support” label, and has only upgraded his sites from PHP 7.4 recently due to this misunderstanding. He then posed these questions (paraphrased):

  1. How can the PHP versions documentation page better convey that WordPress does work under PHP 8.x without major issues?
  2. What are the tickets that can help move PHP 8.x support forward, and allow removal of 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. support” tagtag A directory in Subversion. WordPress uses tags to store a single snapshot of a version (3.6, 3.6.1, etc.), the common convention of tags in version control systems. (Not to be confused with post tags.)?
  3. Do others think this is a problem?

@oglekler related the numerous PHP notices encountered when trying out WooCommerce and PHP 8.2, noting that even if WordPress was almost ready, plugins and themes still posed a challenge. @azaozz agreed that Core functions pretty well up to 8.2, and that plugins were the main reason behind the lack of full support. @clorith added that while Core should not have fatal errors, that the deprecation notices it might throw would be indiscernible from plugin errors to most users.

@sergeybiryukov shared two relevant discussions from last month:

@joemcgill asked if the proposal mentioned in the second link was ever published, and if there was enough support to help make it happen. While not published yet, @hellofromtonya confirmed the post is still planned, and that support for the compatibility strategy has been positive. She also noted that lifting PHP 8.0’s “beta support” label was a target for WordPress 6.3. @clorith suggested that the best place to continue discussion would be the #core-php channel.

@azaozz noted that the PHP Compatibility Checker plugin only supports up to PHP 7.4, and questioned if it could be upgraded to support newer PHP versions. @sergeybiryukov mentioned the relevance of the Tide project, and @jeffpaul confirmed that Tide powers the recently updated PHP Compatibility Checker plugin. He added, however, that Tide in turn relies on PHPCompatibilityWP, which does not yet support PHP 8.x, and shared a discussion link toward adding PHP 8.x support.

To help address @xavivars‘s second question, @ironprogrammer shared links to PHP 8 items in the 6.3 milestone:

@ironprogrammer also pointed at a related topic that might help move PHP support-related discussions forward: #57345: Bump the minimum required PHP version to 7.2. @webcommsat indicated a possible need for #marketing team support to facilitate this work, which was confirmed by @sereedmedia.

Update Error Messages

@pbiron raised the following ticket, #57999: Don’t show error message when there is nothing to update, requesting patch testing and design feedback. He asked if the idea of the ticket was sound, and which of the proposed patches would be preferred.

@oglekler suggested adding screenshots for the proposed patches. @presskopp added screenshots of existing Core behavior, and @pbiron additionally requested before/after shots for each of the patches. @ironprogrammer also suggested pinging the #design channel for awareness.

Screen Options and Help Panel Modernization

@oglekler asked for attention to be drawn to #21583: Improve discoverability and visual design of Screen Options and Help Panels, and remarked that modernizing these panels would also benefit accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility).

@ironprogrammer referred to @joedolson previously suggesting some shared UI relevance between this ticket and WP Features Notifications, and asked if there had been any discussion about this. @oglekler asked how these were related. Brian provided the link to a recent Notifications feature post, noting that the maintainers should be able to help answer questions. Joe further clarified that the Notifications feature is looking to add another panel in the same vicinity as Screen Options/Help, and called for holistic consideration of how each of these are implemented.

Before moving to the next item, @ironprogrammer pointed out that because Design Team time is often limited, addressing these related WP adminadmin (and super admin) UIUI User interface concerns at the same time could be a worthwhile collaboration.

“Roll Back” UI String

@kebbet requested feedback and 6.3 milestone consideration for ticket #58282: Change wording where `roll back` is used, asking if more user-friendly terms should be considered. There were several positive emoji reactions to the ticket, and @audrasjb swiftly added it to the 6.3 milestone.

Next Meeting

The next meeting will be on May 17, 2023 at 20:00 UTC.

Are you interested in helping draft Dev Chat summaries? Volunteer at the start of the next meeting on the #core Slack channel.

Props @audrasjb and @xavivars for peer review of this summary, and to everyone who participated in the Dev Chat.

#6-3, #6-2, #dev-chat, #meeting, #php-8-0, #summary

WordPress and PHP 8.0


Update on November 24, 2020: Added a call out in the “Strict type/value validations for internal functions” section that there are still scenarios where WP CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. could potentially pass invalidinvalid A resolution on the bug tracker (and generally common in software development, sometimes also notabug) that indicates the ticket is not a bug, is a support request, or is generally invalid. types to PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher core functions, especially where values are passed through filters. Props @hellofromtonya.


PHP 8.0 is in the final stages of its release cycle. As of the publish date of this post, version 8.0 RC5 has been released, and the final release of PHP 8.0.0 is scheduled for November 26, 2020.

As the expected changes in PHP 8 were made known earlier this year, WordPress Core contributorsCore Contributors Core contributors are those who have worked on a release of WordPress, by creating the functions or finding and patching bugs. These contributions are done through Trac. https://core.trac.wordpress.org. worked to identify potential compatibility issues within the code base. This includes a call to test earlier in the release cycle.

WordPress Core aims to be compatible with PHP 8.0 in the 5.6 release (currently scheduled for December 8, 2020).

However, PHP 8.0 is a major version update with a large number of changes that break backwards compatibility, and many features that were deprecated within the PHP 7.x feature releases have been officially removed.

What does compatibility mean here?

Significant effort has been put towards making WordPress 5.6 compatible with PHP 8 on its own, but it is very likely that there are still undiscovered issues remaining.

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.

It also should be acknowledged that 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. For that reason, WordPress 5.6 should be considered “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. compatible” with PHP 8.

“Beta compatibility”

Calling WordPress 5.6 “beta compatible” is a good first step. Doing so acknowledges the hard work that has been done to get WordPress running on PHP 8 without major issues and achieve passing PHPUnit tests. It also honors the project’s commitment to being compatible with the new versions of PHP when they are released.

At the same time Core cannot claim “full compatibility” because the process to achieve that state takes a larger amount of time within the greater ecosystem. That’s where WordPress Core needs help.

All 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 and theme developers, as well as hosting communities, are called on to make their code compatible with PHP 8. This will allow WordPress to attain truly “full compatibility” sooner, and without end users having to carry the burden.

It’s also worth noting that all known compatibility issues that were identified through automated testing or static analysis have been addressed, except those detailed further down in this post. Automated test coverage of WordPress Core needs much improvement, and some problems will require manual testing of WordPress on PHP 8 under varying conditions to discover.

For the reasons above, it is highly recommended that you thoroughly test your site before upgrading to PHP 8.


Below is a breakdown of why the PHP 8 update is a bit different than other more recent PHP updates, and the changes that directly affect WordPress in PHP 8.0 that developers need to be aware of.

PHP release types

The release process that the PHP project currently follows was proposed and established back in 2010. This process outlines strict guidelines around when certain types of changes can be made. The process is structured around the idea of “major releases”, and follows semantic versioning.

The current major release of PHP is 7. Over the last 5 years, there have been 4 feature releases for the PHP 7 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. (7.1, 7.2, 7.3, and 7.4), and over 130 security/bug fix releases to these feature releases.

Feature releases

Though new features and bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. fixes are allowed in feature releases, backwards compatibility and 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. compatibility must be maintained. These rules dictating what types of changes are allowed, lower the likelihood that sites will break when upgrading to new feature releases within the same major release of PHP.

When older features are deprecated within these releases, they remain functional. It’s common practice for deprecated features to trigger errors (usually E_WARNING, E_NOTICE, or E_DEPRECATED level), informing developers that the feature is deprecated. Deprecated features can only be removed in a future major release.

Major releases

Like feature releases, bug fixes and new features can be added in major releases. However, old features can be removed entirely, maintaining backwards compatibility and API compatibility is not required.

As of PHP 8 RC4, there are 48 changes to core PHP that break backwards compatibility, and 166 throughout PHP 8 overall (extensions, libraries, etc.).

What this means for developers

Sites that are consistently updating to the latest versions of PHP and addressing issues with each feature release are usually less likely to experience problems when updating to a new major version.

New features in PHP 8 are not compatible with PHP 7 or PHP 5 and usually cause fatal errors.

While making your plugin or theme PHP 8 compatible is strongly encouraged, using features added in PHP 8 is not recommended in distributed plugins and themes unless Requires PHP is set to 8.0 in the headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. section of the main file (plugins) or style.css file (themes).

Changes in PHP 8

Below is a non-exhaustive breakdown of select changes in PHP 8.0 that plugin and theme developers need to be aware of and should accommodate in their code.

Named parameters

PHP 8 introduces the ability to pass arguments to a function by the parameter name instead of the parameter position. This is advantageous in several ways, but to name a few:

  • The argument’s meaning becomes self documenting.
  • The arguments become order-independent.
  • Default values can be skipped arbitrarily.

As an example, let’s take a look at retrieving a term as an associative array using get_term().

<?php
// PHP < 8.0
$my_term = get_term( 1, '', ARRAY_A );

// PHP >= 8.0
$my_term = get_term( output: ARRAY_A, term: 1 );

Note that the arguments in the second example are defined out of order, and because the arguments are not processed in order, the optional parameters using the default value, are no longer required.

Named parameters also work with PHP’s internal functions.

<?php
// Using positional arguments:
array_fill( 0, 100, 50 );

// Using named arguments:
array_fill( start_index: 0, count: 100, value: 50 );

This is a very simplistic overview of the named parameters feature. Please read the full Request for Comments (RFC) on the PHP website for a complete breakdown, which details the impact on variadic functions, func_get_args() and related functions, as well as call_user_func_array() and related functions.

Named parameters and WordPress

The named parameter feature introduces a significant backwards compatibility consideration for all PHP code going forward. With the introduction of this feature, parameter names become a part of the API contract and any changes to their names in future WordPress releases will break backwards compatibility, causing a fatal error when code is invoking a function using an outdated parameter name.

An active review of the function signatures throughout WordPress Core has been proposed to ensure that all parameter names are descriptive, accurate, and do not use reserved keywords to avoid any potential for confusion, but it will not be a part of WordPress 5.6.

Using named parameters when calling WordPress functions and class methods is explicitly not supported and highly discouraged until this audit can be completed, as during the audit, parameter names are subject to change without notice. When this audit has been completed, it will be announced in a future developer note.

If you choose to take advantage of named parameters when using WordPress Core functions and classes before that time, you do so at your own risk.

Additionally, PHP Core has been reviewing their own parameter names in anticipation of the PHP 8 release. Because the PHP documentation has not yet been updated to reflect PHP 8 changes, some of the parameter names currently detailed in the documentation may also change.

To follow or contribute to this review, see #51553, and #50531 on TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress..

Strict type/value validations for internal functions

When support for scalar type declarations was added in PHP 7.0, a new (optional) per-file directive to enforce strict type checking was also added. Including declare( strict_types = 1 ); at the top of a file would ensure that strict type checking is performed on all arguments and return values where scalar types were declared.

When configured, strict type checking also extends to extensions and internal PHP functions invoked within the file. In strict mode, when the type of a value passed does not match the type expected, a Fatal error: Uncaught TypeError is triggered.

However, when strict type checking was not enabled, the behavior of internal functions when receiving an unexpected type was very inconsistent. Some threw a warning and returned NULL, some returned false and threw a TypeError with strict types on, and others generated a TypeError (even if strict_types was not declared).

Starting in PHP 8, a TypeError will be consistently thrown for all internal PHP functions when invalid parameter types are passed, even when strict type checking is not declared.

Additionally, some PHP core functions which did not have type declarations previously, now do. It’s likely that some TypeErrors will be thrown for functions which didn’t even give a warning in older PHP versions.

Type checking for user-defined functions will remain the same. Including declare( strict_types = 1 ); at the top of files is required to enforce strict type checking throughout the file. No WordPress Core code uses strict mode.

An effort to ensure defensive code practices are in place to avoid any potential for invalid types to be passed to WordPress Core function is underway in #51423. Until this is completed, it is possible that some code within WordPress could trigger a TypeError, especially if a value’s type is incorrectly changed through code hooked to a filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output..

Please read the full RFC on the PHP wiki for a complete breakdown of these changes. For more information on this as it relates to WordPress Core, see #51525 on Trac.

Stricter type checks for arithmetic and bitwise operators

In past versions of PHP, applying arithmetic and bitwise operators to arrays, non-overloaded objects, and resources was allowed. However, the behavior was sometimes inconsistent in different scenarios.

Starting in PHP 8, all arithmetic and bitwise operators will throw a TypeError when one of the operands is an array, non-overloaded object, or resource. An exception to this is array + array, which will remain unchanged.

Please read the full RFC on the PHP wiki for a complete breakdown of these changes. For more information on this as it relates to WordPress Core, see #51525 on Trac.

Saner numeric strings

Numeric string handling has been altered to be more intuitive and less
error-prone. Trailing white space is now allowed in numeric strings for
consistency with how leading white space is treated. This mostly affects:

  • The is_numeric() function
  • String-to-string comparisons
  • Type declarations
  • Increment and decrement operations

The concept of a “leading-numeric string” has been mostly dropped; the cases where this remains exist in order to ease migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies.. Strings which emitted an E_NOTICE “A non well-formed numeric value encountered” will now emit an E_WARNING “A non-numeric value encountered” and all strings which emitted an E_WARNING “A non-numeric value encountered” will now throw a TypeError. This mostly affects:

  • Arithmetic operations
  • Bitwise operations

This E_WARNING to TypeError change also affects the E_WARNING “Illegal string offset ‘string'” for illegal string offsets. The behavior of explicit casts to int/float from strings has not been changed.

Please read the full RFC on the PHP wiki for a complete breakdown of these changes.

Non-strict comparisons between numbers and non-numeric strings

Non-strict comparisons between numbers and non-numeric strings now work by casting the number to string and comparing the strings. Comparisons between numbers and numeric strings continue to work as before. Notably, this means that 0 == "not-a-number" is considered false now.

A few other code patterns that may be common in plugins and themes that will be affected:

  • '' < 0 is now considered true (see [48960]).
  • 'not-a-number' > 0 is also now considered true (see [49043]).

Error, warning, and notice changes

A large handful of preexisting errors have been reclassified. Here’s are some that may be commonly encountered:

Warnings converted to error exceptions

  • Attempting to write to a property of a non-object. Previously this
    implicitly created a stdClass object for null, false and empty strings.
  • Attempting to append an element to an array for which the PHP_INT_MAX key is already used.
  • Attempting to use an invalid type (array or object) as an array key or
    string offset.
  • Attempting to write to an array index of a scalar value.
  • Attempting to unpack a non-array/Traversable.

Please read the full RFC on the PHP wiki for more information on these changes.

Notices converted to warnings

  • Attempting to read an undefined variable.
  • Attempting to read an undefined property.
  • Attempting to read an undefined array key.
  • Attempting to read a property of a non-object.
  • Attempting to access an array index of a non-array.
  • Attempting to convert an array to string.
  • Attempting to use a resource as an array key.
  • Attempting to use null, a boolean, or a float as a string offset.
  • Attempting to read an out-of-bounds string offset.
  • Attempting to assign an empty string to a string offset.

Read the full RFC on the PHP wiki for more information.

Build & Test Tool Related Changes

Because WordPress supports PHP 5.6.20 or higher, running the WordPress Core PHPUnit test suite on PHP 8 is not straightforward.

  • PHPUnit >= 9.3 is the only version of PHPUnit that currently supports PHP 8.
  • PHPunit 5.7.x is the last version to include support for PHP 5.6.
  • PHPUnit 8.x changed several methods that do not return values to specify a void return type declaration. However, this return type is not available in PHP < 7.1.

In order to maintain the ability to run the test suite on PHP 5.6 while also allowing the tests to run on PHP 8, the changes to PHPUnit required have been backported into the WordPress Core test suite and Composer is used to manipulate the autoload process for PHPUnit 7.x.

To run the WordPress Core PHPUnit test suite on PHP 8, it is required to use Composer for installation and running.

To help make this easier, a new NPM script has been added to run the test suite within the local Docker environment using the Composer installed version of PHPUnit.

// Run within the local Docker container using version of
// PHPUnit installed within the container.
npm run test:php

// Run within the local Docker container using version of
// PHPUnit installed via Composer.
npm run test:php-composer

For more information on this new command, see #51456. For more information on making the test suite compatible with PHP 8/PHPUnit >= 8, see #46149, #50902, and #50913.

External Libraries

Several external libraries bundled with WordPress Core have been updated to fix PHP 8 compatibility issues. Pull requests have been opened where appropriate to ensure these changes are included in future releases of these libraries.

  • SimplePie has been updated from version 1.5.5 to 1.5.6 (see #51521). Additionally, the WP_Feed_Cache class has been deprecated and will only be loaded for backwards compatibility if SimplePie < 3 is loaded within a plugin (see #51629 and #29204).
  • sodium_compat was updated to avoid an error when attempting to access the MB_OVERLOAD_STRING constant, which has been removed in PHP 8 (see #51399).
  • Text_Diff was updated to fix a “Non-static method cannot be called statically” fatal error (see #51559).

Additional notes

  • create_function() has been removed. The final instance of this function in WordPress has been removed (see #50899).
  • The @ operator will no longer silence fatal errors. Care should be taken that error messages are not displayed in production environments, which can result in information leaks.
  • Following the hash comment operator # immediately with an opening bracket is not supported as a comment anymore since this syntax is now used for attributes.
  • libxml_disable_entity_loader() has been deprecated (see #50898).
  • Resource to object return type changes, including the introduction of the is_gd_image() function.
  • Changes to sorting: if any code relied on a certain sort order based on previous behavior, this may now fail.
  • The parameter/return types for various PHP functions have changed and may have an impact. Subtle changes like that substr() will now always return a string. Previously, this returned string|false.

Summary

As always, reading through the complete upgrade document is highly recommended.

Even as WordPress Core continues to expand its support for new versions of PHP, support for old versions will remain as is for the time being, staying at PHP 5.6.20 and higher until usage numbers show that the impact on users will be minimal.

There is a separate initiative to decrease the usage numbers for older versions of PHP being guided by the Core PHP team through the servehappy initiative. If you wish to help with this effort, please join the #core-php room in the Making WordPress Core Slack instance.

WordPress continues to encourage all users to run the latest and greatest versions of PHP. This includes PHP 8.0 upon its official release.

A full list of tickets related to PHP 8.0 support can be found on Trac.

Props @helen, @jrf, @jeffpaul, @sergeybiryukov, @andraganescu, @omarreiss, @hellofromtonya, and @chanthaboune for peer reviewing.

#5-6, #dev-notes, #php-8-0