General: Introduce wp_trigger_error().
Introduces wp_trigger_error() as a wrapper around PHP's native trigger_error(). As a wrapper, it's lean and not opinionated about the message. It accepts an E_USER family error level, meaning it is not limited to only notices.
Where _doing_it_wrong() intends to loudly alert developers "Hey you're doing it wrong - fix it", wp_trigger_error() is not opinionated and does not add wording. Rather, it passes the given message to trigger_error().
wp_trigger_error() is meant for every trigger_error() instance. It can be used:
- in
_doing_it_wrong() and each _deprecated_*() function.
- for PHP 8.x deprecations.
- for PHP error parity.
- for less severe "doing it wrong" instance that do not require bailing out.
- when a component or extension is not available on the server
- for instances where it's not clear if a plugin's or theme's code is the root cause.
- and more.
Technical details:
- Does not trigger the error if
WP_DEBUG is not true.
- Includes
wp_trigger_error_run action to allow hooking in for backtracing and deeper debug.
- Accepts an E_USER error level, but defaults to
E_USER_NOTICE.
- Requires a function name, though can be an empty string. As the output message generated by
trigger_error() references the file and line number where it was invoked, passing the function's name provides more information where the error/warning/notice/deprecation happened. It's intended to help with debug.
- A WordPress version number is not included.
- As messages can appear in the browser, the message is escaped using
esc_html(). As noted in the PHP manual: "HTML entities in message are not escaped. Use htmlentities() on the message if the error is to be displayed in a browser."
References:
Props azaozz, hellofromTonya, flixos90, costdev, peterwilsoncc, oglekler, mukesh27.
See #57686.