PHP 8.4 | `wp_trigger_error(): fix trigger_error() with E_USER_ERROR is deprecated (Trac 62061)#7376
PHP 8.4 | `wp_trigger_error(): fix trigger_error() with E_USER_ERROR is deprecated (Trac 62061)#7376jrfnl wants to merge 1 commit intoWordPress:trunkfrom
Conversation
…is deprecated
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 `Exception`s. 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
|
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 Core Committers: Use this line as a base for the props when committing in SVN: To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
Test using WordPress PlaygroundThe 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
For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation. |
| array( 'http', 'https' ) | ||
| ); | ||
|
|
||
| if ( E_USER_ERROR === $error_level ) { |
There was a problem hiding this comment.
Since this is to handle a PHP 8.4 deprecation and the minimum PHP for WordPress Core hasn't reached that yet, should we add an inline comment to explain why this error level is handled differently?
There was a problem hiding this comment.
Well, if this PR is accepted, the E_USER_ERROR error level will be handled differently for all supported PHP versions, not just for PHP 8.4, so I wonder if adding a comment wouldn't just cause more confusion.
And aside from the PHP 8.4 deprecation, which creates a sense of urgency to handle this, this could just be considered a form of code modernization (moving away from old-fashioned trigger_error() to more modern Exceptions) and as a prelim to keeping the code testable, as on PHPUnit 10+ we wouldn't be able to "expect" errors like this anymore anyway.
| require ABSPATH . WPINC . '/class-wp-token-map.php'; | ||
| require ABSPATH . WPINC . '/formatting.php'; | ||
| require ABSPATH . WPINC . '/meta.php'; | ||
| require ABSPATH . WPINC . '/class-wp-exception.php'; |
There was a problem hiding this comment.
Could this class be used earlier? Any harm in moving it up to "Include files required for initialization.section, such as afterclass-wp-fatal-error-handler.php`?
There was a problem hiding this comment.
Could this class be used earlier?
It currently isn't, but yes, in the future, it could be.
Any harm in moving it up to "Include files required for initialization." section, such as after
class-wp-fatal-error-handler.php?
No harm at all and in that case, maybe it should even be before class-wp-fatal-error-handler.php, in case that class wants to use the exception (or handle it in some way).
Having said that, the current loading order is based on when it is needed (at this time) and is still "early", i.e. in the "// Load early WordPress files." section, so this is before WPDB is initialized, before translations are loaded, before plugins are loaded etc.
Maybe the "move it even earlier" should only happen if and when the need arises for the code to be loaded earlier ? That would make the case for why it should be loaded earlier directly related to the change which created the need for it to be loaded earlier. Does that make sense ?
There was a problem hiding this comment.
No harm at all and in that case, maybe it should even be before
class-wp-fatal-error-handler.php, in case that class wants to use the exception (or handle it in some way)
I agree.
Maybe the "move it even earlier" should only happen if and when the need arises for the code to be loaded earlier ? That would make the case for why it should be loaded earlier directly related to the change which created the need for it to be loaded earlier. Does that make sense ?
It does, but ... 😉
Thinking it makes more sense to put it with the fatal error handler, while making it available earlier as you noted.
I don't think there's an immediate cognitive correlation of its current placement to why it's there. But putting it before the fatal error handler could (maybe) make that correlation. What do I mean? Well, when I read its location, I wondered: hmm, what if the classes / code above needed it? "Grouping" it with the fatal error handler in those initialization file loads caught my attention.
As you noted, there's no harm in it being in either spot.
There was a problem hiding this comment.
I'll relocate it in the commit itself. No need to change it here.
There was a problem hiding this comment.
I don't think there's an immediate cognitive correlation of its current placement to why it's there.
Well, there is a correlation. The function which uses the new class is defined in the functions.php file, which is why the class file is included right before the functions.php file, but yes, that may not be an obvious connection for the casual onlooker.
Thinking it makes more sense to put it with the fatal error handler, while making it available earlier as you noted.
Sounds good to me.
hellofromtonya
left a comment
There was a problem hiding this comment.
The changes LGTM though will relocate loading the new exception file before the fatal error, as discussed.
Preparing the commit now 👍
|
Committed via https://core.trac.wordpress.org/changeset/59107 ✅ But I missed props in the commit for @costdev 🤦♀️ Manually added ✅ |
|
Thanks @hellofromtonya! Just noting here that this change will need a mention in the field guide/miscellaneous dev notes for WP 6.7. |
PHP 8.4 deprecates the use of
trigger_errror()withE_USER_ERRORas the error level, as there are a number of gotchas to this way of creating aFatal Error(finallyblocks not executing, destructors not executing). The recommended replacements are either to use exceptions or to do a hardexit.WP has its own
wp_trigger_error()function, which under the hood callstrigger_error(). If passedE_USER_ERRORas the$error_level, this will hit the PHP 8.4 deprecation.Now, there were basically three options:
exit($status)whenwp_trigger_error()is called withE_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.wp_trigger_error()is called withE_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 atry-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_Exceptionclass and starts using that in thewp_trigger_error()function is the$error_levelis set toE_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_Errordoesn't extendException, 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 anexitwith the error message, bringing us back to point 2 above.Basically,
WP_Erroris an arcane left-over from the PHP 4 days, before PHP natively supportedtry-catchstatements withExceptions. 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 foris_wp_error()instead of usingtry-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_Errorand to encourage the use of dedicated exception classes instead (for new code). I'd recommend for additional exception classes to be placed in a newwp-includes/exceptionsdirectory and for these, in principle, to extendWP_Exception.Note: this change will need to be mentioned in the WP 6.7 dev-note!
Ref:
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.