Changeset 56530 for trunk/src/wp-includes/functions.php

Timestamp:

09/06/2023 10:06:26 PM (13 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:

• ​PHP manual for `trigger_error()`.
• ​E_USER constants (error level) in the PHP manual.

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

File:

• trunk/src/wp-includes/functions.php (modified) (1 diff)

trunk/src/wp-includes/functions.php

@@ -6041 +6041 @@
 
 /**
+ * Generates a user-level error/warning/notice/deprecation message.
+ *
+ * Generates the message when `WP_DEBUG` is true.
+ *
+ * @since 6.4.0
+ *
+ * @param string $function_name The function that triggered the error.
+ * @param string $message       The message explaining the error.
+ * @param int    $error_level   Optional. The designated error type for this error.
+ *                              Only works with E_USER family of constants. Default E_USER_NOTICE.
+ */
+function wp_trigger_error( $function_name, $message, $error_level = E_USER_NOTICE ) {
+
+    // Bail out if WP_DEBUG is not turned on.
+    if ( ! WP_DEBUG ) {
+        return;
+    }
+
+    /**
+     * Fires when the given function triggers a user-level error/warning/notice/deprecation message.
+     *
+     * Can be used for debug backtracking.
+     *
+     * @since 6.4.0
+     *
+     * @param string $function_name The function that was called.
+     * @param string $message       A message explaining what has been done incorrectly.
+     * @param int    $error_level   The designated error type for this error.
+     */
+    do_action( 'wp_trigger_error_run', $function_name, $message, $error_level );
+
+    if ( ! empty( $function_name ) ) {
+        $message = sprintf( '%s(): %s', $function_name, $message );
+    }
+
+    /*
+     * If the message appears in the browser, then it needs to be escaped.
+     * Note the warning in the `trigger_error()` PHP manual.
+     * @link https://www.php.net/manual/en/function.trigger-error.php
+     */
+    $message = esc_html( $message );
+
+    trigger_error( $message, $error_level );
+}
+
+/**
  * Determines whether the server is running an earlier than 1.5.0 version of lighttpd.
  *