PHP 8.4 | `wp_trigger_error(): fix trigger_error() with E_USER_ERROR is deprecated (Trac 62061)

[jrfnl]

PHP 8.4 deprecates the use of trigger_errror() with E_USER_ERROR as the error level, as there are a number of gotchas to this way of creating a Fatal Error (finally blocks not executing, destructors not executing). The recommended replacements are either to use exceptions or to do a hard exit.

WP has its own wp_trigger_error() function, which under the hood calls trigger_error(). If passed E_USER_ERROR as the $error_level, this will hit the PHP 8.4 deprecation.

Now, there were basically three options:

• Silence the deprecation until PHP 9.0 and delay properly solving this until then. This would lead to an awkward solution, as prior to PHP 8.0, error silencing would apply to all errors, while, as of PHP 8.0, it will no longer apply to fatal errors. It also would only buy us some time and wouldn't actually solve anything.
• Use exit($status) when wp_trigger_error() is called with E_USER_ERROR. This would make the code untestable and would disable handling of these errors via custom error handlers, which makes this an undesirable solution.
• Throw an exception when wp_trigger_error() is called with E_USER_ERROR. This makes for the most elegant solution with the least BC-breaking impact, though it does open it up to the error potential being "caught" via a try-catch. In my opinion, that's not actually a bad thing and is likely to only happen for those errors which can be worked around, in which case, it's a bonus that that's now possible.

So, this commit implements the third option. It introduces a new WP_Exception class and starts using that in the wp_trigger_error() function is the $error_level is set to E_USER_ERROR.

This change is covered by pre-existing tests, which have been updated to expect the exception instead of a PHP error.

Now, why did I not use WP_Error ?

Well, for one, this would lead to completely different behaviour as WP_Error doesn't extend Exception, which means that the program would not be stopped, but would continue running, which would be a much bigger breaking change and carries security risks. WP_Error also doesn't natively trigger displaying/logging of the error message, so in that case, it would still need an exit with the error message, bringing us back to point 2 above.

Basically, WP_Error is an arcane left-over from the PHP 4 days, before PHP natively supported try-catch statements with Exceptions. If it were up to me, we'd burn it with fire, but considering how much would break if we would (any and all plugins/themes/Core checks which check a function return value for is_wp_error() instead of using try-catch), that's not really an option.

Having said that, I would strongly recommend, going forward, to not allow any new code to return a WP_Error and to encourage the use of dedicated exception classes instead (for new code). I'd recommend for additional exception classes to be placed in a new wp-includes/exceptions directory and for these, in principle, to extend WP_Exception.

Note: this change will need to be mentioned in the WP 6.7 dev-note!

Ref:

• https://wiki.php.net/rfc/deprecations_php_8_4#deprecate_passing_e_user_error_to_trigger_error
• https://www.php.net/manual/en/migration80.incompatible.php

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

---

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

[github-actions[bot]]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props jrf.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions[bot]]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• The Plugin and Theme Directories cannot be accessed within Playground.
• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance, it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[hellofromtonya]

Committed via https://core.trac.wordpress.org/changeset/59107 ✅

But I missed props in the commit for @costdev 🤦‍♀️ Manually added ✅

[jrfnl]

Thanks @hellofromtonya! Just noting here that this change will need a mention in the field guide/miscellaneous dev notes for WP 6.7.