Introduce _doing_it_wrong(). See #15824.

westi · westi · commit 052f67d71f22 · 2010-12-15T11:29:50.000Z
git-svn-id: https://develop.svn.wordpress.org/trunk@16939 602fd350-edb4-49c9-b593-d223f7449a82
diff --git a/wp-includes/functions.php b/wp-includes/functions.php
@@ -4453,3 +4453,37 @@ function show_admin_bar( $show ) {
 	$show_admin_bar = (bool) $show;
 }
 
+/**
+ * Marks something as being incorrectly called.
+ *
+ * There is a hook doing_it_wrong_run that will be called that can be used
+ * to get the backtrace up to what file and function called the deprecated
+ * function.
+ *
+ * The current behavior is to trigger an user error if WP_DEBUG is true.
+ * *
+ * @package WordPress
+ * @subpackage Debug
+ * @since 3.1.0
+ * @access private
+ *
+ * @uses do_action() Calls 'doing_it_wrong_run' and passes the function arguments.
+ * @uses apply_filters() Calls 'doing_it_wrong_trigger_error' and expects boolean value of true to do
+ *   trigger or false to not trigger error.
+ *
+ * @param string $function The function that was called
+ * @param string $message Optional. The function that should have been called
+ * @param string $version Optional. The version of WordPress that deprecated the function
+ */
+function _doing_it_wrong( $function, $message, $version = null ) {
+
+	do_action( 'doing_it_wrong_run', $function, $message, $version );
+
+	// Allow plugin to filter the output error trigger
+	if ( WP_DEBUG && apply_filters( 'doing_it_wrong_trigger_error', true ) ) {
+		if ( is_null( $version ) )
+			trigger_error( sprintf( __('%1$s was called with an argument that is <strong>incorrect</strong> - %2$s'), $function, $message ) );
+		else
+			trigger_error( sprintf( __('%1$s was called with an argument that is <strong>incorrect</strong> since version %2$s - %3$s'), $function, $version, $message ) );
+	}
+}
