[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                                          |
-------------------------------------------------+-------------------------

Comment (by costdev):

 > The big question:
 > Should `wp_trigger_error()` be a `trigger_error()` wrapper or a milder
 verbiage form of `_doing_it_wrong()`?

 Thinking outside the context of "we shouldn't be using `_doing_it_wrong()`
 here", I think a wrapper for PHP's `trigger_error()` makes sense.
 `_doing_it_wrong()` is informing extenders of incorrect usage, whereas
 `wp_trigger_error()` could trigger errors for any reason, so I think
 `WP_DEBUG` is a sufficient guard without the need for an additional filter
 included in [https://github.com/WordPress/wordpress-develop/pull/5122 PR
 5122].

 I'm not sure that a `$where`/`$function_name` parameter is appropriate for
 `wp_trigger_error()`. `_doing_it_wrong()` states: "Marks something as
 being incorrectly called", whereas errors can be triggered anywhere,
 including the root-level of a file (such as [https://github.com/costdev
 /wordpress-develop/blob/e2780e87feafc55a1658092549d4d870f202e97e/src/wp-
 admin/link-parse-opml.php#L81 here]). If we do include it, I'd suggest we
 don't make it a required first parameter as this distances it from
 `trigger_error()` which most extenders will have in mind when calling
 `wp_trigger_error()`, and they may not want/need a function name to be
 included. `trigger_error()` will already include the file and line number.

 An initial lean implementation with "minimum requirements" could be:
 1. Accepts `string $message, int $error_level = E_USER_NOTICE`.
 2. Bails if `WP_DEBUG` is disabled.
 3. Fires a `wp_trigger_error_run` action to align with
 `_deprecated_function()`, `_deprecated_constructor()`,
 `_deprecated_class()`, `_deprecated_argument()`, `_deprecated_hook()`, and
 `_doing_it_wrong()`.
 4. Triggers the error.

 If an invalid error level is passed, PHP will already output an error
 which will only occur when we've already ensured that `WP_DEBUG` is
 enabled, so I don't think we need the reset included in
 [https://github.com/WordPress/wordpress-develop/pull/5144 PR 5144].

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