[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 hellofromTonya):

 Replying to [comment:20 flixos90]:
 > I would like us to come up with a clear method of differentiating
 between when to use `_doing_it_wrong()` vs when to use
 `wp_trigger_error()` though. I think it's clear the first one is to
 indicate to developers that they are doing something wrong. So by
 definition `wp_trigger_error()` probably covers the rest of errors. It
 would be great to come up with a list of examples, either anecdotally or
 maybe there are `_doing_it_wrong()` instances in core where we feel they
 should use `wp_trigger_error()` instead. Having such examples would help
 us better define the scope of when the new function should be used.

 I agree.

 The way I think of `_doing_it_wrong()` is:
 When extenders invoke a function incorrectly, causing it to bail out and
 not run as expected. The message exists to alert developers: Hey, you're
 doing xyz wrong, your code won't work, and please fix your code. Examples:

 * A function won't run because the required array key or structure was not
 passed to it.
 * An incompatible data type is passed which can't be type juggled or
 handled: `WP_Style_Engine_Processor::add_store()`.
 * Something isn't supported: `wp_cache_flush_runtime()`.

 For all other cases, `wp_trigger_error()` is available. Examples:

 * PHP 8.x deprecations: functionality will continue to work as it did
 previously: magic methods in `WP_User_Query`,
 `WP_Text_Diff_Renderer_Table`,
 * PHP error parity: `wp_strip_all_tags()`.
 * Changes that are or could be automatically handled: Request `wp-includes
 /class-requests.php`.
 * Something went wrong which may or may not be due to incorrect code
 (maybe invalid data or user input): `_filter_block_template_part_area()`,
 `WP_Theme_JSON::get_user_data()`, `WP_Theme_JSON::set_spacing_size()`,
 * An extension may not be available on the server:
 `prep_atom_text_construct()`.

 There are many cases of strict type checks using `_doing_it_wrong()` which
 could include automatic handling and use `wp_trigger_error()`. For
 example, there are many "strict" data type checks such as for `string`
 that could handle scalars or even `null`. Rather than bailing out if not a
 string, if it's a scalar, handle it, trigger `wp_trigger_error()`, and
 keep going.

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