Ticket #4361: functions.diff

functions.php

@@ -485 +485 @@
                 fclose( $fp );
 }
 
+/**
+ * wp_mark_deprecated() - Marks a function as deprecated and informs when it has been used.
+ *
+ * There is a hook that will be called that can be used to get the backtrace up to what file
+ * and function called the deprecated function. That behavior is not defined here, because of
+ * preformance.
+ *
+ * The current behavior is to trigger an user error if WP_DEBUG is defined and is true. In later
+ * versions, this behavior could be changed to a more reasonable and less drastic approach of
+ * letting the user know that deprecated functions were used. However, normal usage will NOT
+ * trigger these errors, so only those that purposefully enable WP_DEBUG will see them.
+ *
+ * This function could be used in every place, including hooks that allows for calling the function.
+ * The common use will be for functions but can be for hooks, parameters, etc that is deprecated.
+ *
+ * @link http://trac.wordpress.org/ticket/4361 History of this function
+ *
+ * @package WordPress
+ * @package Debug
+ * @since 2.4
+ *
+ * @uses do_action() Calls 'deprecated_function_run' and passes the function name and what to use instead.
+ * @uses apply_filters() Calls 'deprecated_function_trigger_error' and expects boolean value of true to do trigger or false to not trigger error.
+ *
+ * @param string $used The function that was called
+ * @param string $seeinstead The function that should have been called
+ */
+function wp_mark_deprecated($used, $seeinstead) {
+        // Allow plugin to overwrite the error => forward thinking
+        $outputError = true;
+
+        // We can't know if another function will trigger this function before plugins.php is included.
+        // Test anyway. Small performance lost is okay since this function should not be called at all.
+        if( function_exists('do_action') ) {
+                do_action('deprecated_function_run', $function, $seeinstead);
+
+                // Allow plugin to filter the output error trigger
+                $outputError = apply_filters( 'deprecated_function_trigger_error', $outputError );
+        }
+
+        if( $outputError && defined('WP_DEBUG') && true === WP_DEBUG )
+                trigger_error( printf( __("%s is <strong>deprecated</strong>! Use %s instead."), $function, $seeinstead );
+}
+
 function do_enclose( $content, $post_ID ) {
         global $wpdb;
         include_once( ABSPATH . WPINC . '/class-IXR.php' );