[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:15 costdev]:
 > 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.

 The file and line number will reference where `trigger_error()` is invoked
 within `wp_trigger_error()`, which makes debugging more difficult.

 Passing the function's name adds it to the start of the error message to
 help with debug efforts. If it's not needed or not within a function
 scope, then an empty string can be passed instead.

 For example:

 {{{#!php
 function wp_trigger_error( $function_name, $message, $error_level =
 E_USER_NOTICE ) {

         if ( '' !== $function_name ) {
                 $message = sprintf( '%s(): %s', $function_name, $message
 );
         }

         trigger_error( $message, $error_level );
 }

 function test_triggering_error() {
     wp_trigger_error( __FUNCTION__, 'message should include the function
 that triggered the error.' );
 }

 wp_trigger_error( '', 'Message should not include the function as this is
 not within a function scope.' );

 test_triggering_error();
 }}}


 which results in:

 {{{
 Notice: Message should not include the function as this is not within a
 function scope. in /var/www/src/wp-includes/functions.php on line 6078

 Notice: test_triggering_error(): message should include the function that
 triggered the error. in /var/www/src/wp-includes/functions.php on line
 6078
 }}}

 Notice the file and line number are in `wp_trigger_error()` and not where
 the error is triggered. See it in action https://3v4l.org/3I4KF.

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