[wp-trac] [WordPress Trac] #57686: Introduce wp_trigger_error() to compliment _doing_it_wrong()

[WordPress Trac]

#57686: Introduce wp_trigger_error() to compliment _doing_it_wrong()
-------------------------------------------------+-------------------------
 Reporter:  azaozz                               |       Owner:
                                                 |  hellofromTonya
     Type:  enhancement                          |      Status:  assigned
 Priority:  normal                               |   Milestone:  6.4
Component:  General                              |     Version:
 Severity:  normal                               |  Resolution:
 Keywords:  needs-dev-note has-patch has-unit-   |     Focuses:
  tests commit                                   |
-------------------------------------------------+-------------------------

Comment (by hellofromTonya):

 In [changeset:"56530" 56530]:
 {{{
 #!CommitTicketReference repository="" revision="56530"
 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 [https://www.php.net/manual/en/function.trigger-
 error.php 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:
 * [https://www.php.net/manual/en/function.trigger-error.php PHP manual for
 `trigger_error()`].
 * [https://www.php.net/manual/en/errorfunc.constants.php E_USER constants
 (error level) in the PHP manual].

 Props azaozz, hellofromTonya, flixos90, costdev, peterwilsoncc, oglekler,
 mukesh27.
 See #57686.
 }}}

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/57686#comment:27>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform