Make WordPress Core

Changeset 56530


Ignore:
Timestamp:
09/06/2023 10:06:26 PM (15 months ago)
Author:
hellofromTonya
Message:

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

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

Location:
trunk
Files:
1 added
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/functions.php

    r56522 r56530  
    60416041
    60426042/**
     6043 * Generates a user-level error/warning/notice/deprecation message.
     6044 *
     6045 * Generates the message when `WP_DEBUG` is true.
     6046 *
     6047 * @since 6.4.0
     6048 *
     6049 * @param string $function_name The function that triggered the error.
     6050 * @param string $message       The message explaining the error.
     6051 * @param int    $error_level   Optional. The designated error type for this error.
     6052 *                              Only works with E_USER family of constants. Default E_USER_NOTICE.
     6053 */
     6054function wp_trigger_error( $function_name, $message, $error_level = E_USER_NOTICE ) {
     6055
     6056    // Bail out if WP_DEBUG is not turned on.
     6057    if ( ! WP_DEBUG ) {
     6058        return;
     6059    }
     6060
     6061    /**
     6062     * Fires when the given function triggers a user-level error/warning/notice/deprecation message.
     6063     *
     6064     * Can be used for debug backtracking.
     6065     *
     6066     * @since 6.4.0
     6067     *
     6068     * @param string $function_name The function that was called.
     6069     * @param string $message       A message explaining what has been done incorrectly.
     6070     * @param int    $error_level   The designated error type for this error.
     6071     */
     6072    do_action( 'wp_trigger_error_run', $function_name, $message, $error_level );
     6073
     6074    if ( ! empty( $function_name ) ) {
     6075        $message = sprintf( '%s(): %s', $function_name, $message );
     6076    }
     6077
     6078    /*
     6079     * If the message appears in the browser, then it needs to be escaped.
     6080     * Note the warning in the `trigger_error()` PHP manual.
     6081     * @link https://www.php.net/manual/en/function.trigger-error.php
     6082     */
     6083    $message = esc_html( $message );
     6084
     6085    trigger_error( $message, $error_level );
     6086}
     6087
     6088/**
    60436089 * Determines whether the server is running an earlier than 1.5.0 version of lighttpd.
    60446090 *
Note: See TracChangeset for help on using the changeset viewer.