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

 Hmm, `esc_html()` for the message being passed to `trigger_error()` is not
 the right approach.

 Why? Messages (like the ones generated from the `_deprecated_*()` and
 `_doing_it_wrong()` functions have HTML in them. When they appear in the
 browser, they visually look different. When they appear in the logs, the
 HTML tags are escaped, making them difficult to read and understand.

 == Example:

 Consider the following:
 {{{#!php
 add_action( 'init', 'test_escaping_of_trigger_error' );
 function test_escaping_of_trigger_error() {
         _doing_it_wrong( __FUNCTION__, 'A non-empty string is required for
 blah.', '6.4' );
 }
 }}}

 === Before: without esc_html()
 Before using `esc_html()`, the Notice reads as follows and the included
 HTML tags are respected in the browser:

 The HTML markup:
 {{{
 <b>Notice</b>
 :  Function test_escaping_of_trigger_error was called
 <strong>incorrectly</strong>. A non-empty string is required for blah.
 Please see <a href="https://wordpress.org/documentation/article/debugging-
 in-wordpress/">Debugging in WordPress</a> for more information. (This
 message was added in version 6.4.) in <b>/var/www/src/wp-
 includes/functions.php</b> on line <b>6027</b><br>
 }}}

 How it looks in the browser:
 >**Notice**: Function test_escaping_of_trigger_error was called
 **incorrectly**. A non-empty string is required for blah. Please see
 [https://wordpress.org/documentation/article/debugging-in-wordpress/
 Debugging in WordPress] for more information. (This message was added in
 version 6.4.) in **/var/www/src/wp-includes/functions.php** on line
 **6027**

 How it appears in the server logs:
 >[07-Sep-2023 17:47:06 UTC] PHP Notice:  Function
 test_escaping_of_trigger_error was called <strong>incorrectly</strong>. A
 non-empty string is required for blah. Please see <a
 href="https://wordpress.org/documentation/article/debugging-in-
 wordpress/">Debugging in WordPress</a> for more information. (This message
 was added in version 6.4.) in /var/www/src/wp-includes/functions.php on
 line 6027

 === After: With esc_html()
 Compare to when the message is passed through `esc_html()`:

 The HTML markup:
 {{{
 <b>Notice</b>
 :  Function test_escaping_of_trigger_error was called
 <strong>incorrectly</strong>. A non-empty string is required
 for blah. Please see <a
 href="https://wordpress.org/documentation/article/debugging-in-
 wordpress/">Debugging in WordPress</a> for more information.
 (This message was added in version 6.4.) in <b>/var/www/src/wp-
 includes/functions.php</b> on line <b>6027</b><br>
 }}}

 How it looks in the browser:
 >**Notice**: Function test_escaping_of_trigger_error was called
 <strong>incorrectly</strong>. A non-empty string is required for blah.
 Please see <a href="https://wordpress.org/documentation/article/debugging-
 in-wordpress/">Debugging in WordPress</a> for more information. (This
 message was added in version 6.4.) in **/var/www/src/wp-
 includes/functions.php** on **line 6027**

 How it appears in the server logs:
 >[07-Sep-2023 17:53:09 UTC] PHP Notice:  Function
 test_escaping_of_trigger_error was called
 <strong>incorrectly</strong>. A non-empty string is required
 for blah. Please see <a
 href="https://wordpress.org/documentation/article/debugging-in-
 wordpress/">Debugging in WordPress</a> for more information.
 (This message was added in version 6.4.) in /var/www/src/wp-
 includes/functions.php on line 6027

 == Which escaping approach?

 A different escaping approach than `esc_html()` is needed. Which one?

 Maybe `wp_kses_post()`? @flixos90 @azaozz @costdev what do you think?

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