From 2653e93e09a6ecc7fa8a47de59bf6be48334829c Mon Sep 17 00:00:00 2001
From: hellofromTonya <hellofromTonya@git.wordpress.org>
Date: Wed, 6 Sep 2023 22:08:18 +0000
Subject: [PATCH] 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 [https://www.php.net/manual/en/function.trigger-error.php 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:
* [https://www.php.net/manual/en/function.trigger-error.php PHP manual for `trigger_error()`].
* [https://www.php.net/manual/en/errorfunc.constants.php E_USER constants (error level) in the PHP manual].

Props azaozz, hellofromTonya, flixos90, costdev, peterwilsoncc, oglekler, mukesh27.
See #57686.
Built from https://develop.svn.wordpress.org/trunk@56530


git-svn-id: http://core.svn.wordpress.org/trunk@56042 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/functions.php | 46 +++++++++++++++++++++++++++++++++++++++
 wp-includes/version.php   |  2 +-
 2 files changed, 47 insertions(+), 1 deletion(-)

diff --git a/wp-includes/functions.php b/wp-includes/functions.php
index 44728a2e41..835fa7190e 100644
--- a/wp-includes/functions.php
+++ b/wp-includes/functions.php
@@ -6039,6 +6039,52 @@ function _doing_it_wrong( $function_name, $message, $version ) {
 	}
 }
 
+/**
+ * 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.
  *
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 2dbf840a0e..308eca88ae 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '6.4-alpha-56529';
+$wp_version = '6.4-alpha-56530';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.