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

Timestamp:

06/25/2016 07:56:19 PM (8 years ago)

Author:

boonebgorges

Message:

Allow action and filter hooks to be deprecated.

When a filter or action hook is deprecated, the corresponding apply_filters()
or do_action() calls should be switched out with apply_filters_deprecated()
or do_action_deprecated(). The latter functions will throw a deprecation
before invoking the original hook.

Props solarissmoke, SergeyBiryukov, DrewAPicture.
Fixes #10441.

File:

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

trunk/src/wp-includes/functions.php

@@ -3894 +3894 @@
 
 /**
+ * Marks a deprecated action or filter hook as deprecated and throws a notice.
+ *
+ * Use the 'deprecated_hook_run' action to get the backtrace describing where the
+ * deprecated hook was called.
+ *
+ * Default behavior is to trigger a user error if WP_DEBUG is true.
+ *
+ * This function is called by the do_action_deprecated() and apply_filters_deprecated()
+ * functions, and so generally does not need to be called directly.
+ *
+ * @since 4.6.0
+ * @access private
+ *
+ * @param string $hook        The hook that was used.
+ * @param string $version     The version of WordPress that deprecated the hook.
+ * @param string $replacement Optional. The hook that should have been used.
+ * @param string $message     Optional. A message regarding the change.
+ */
+function _deprecated_hook( $hook, $version, $replacement = null, $message = null ) {
+    /**
+     * Fires when a deprecated hook is called.
+     *
+     * @since 4.6.0
+     *
+     * @param string $hook        The hook that was called.
+     * @param string $replacement The hook that should be used as a replacement.
+     * @param string $version     The version of WordPress that deprecated the argument used.
+     * @param string $message     A message regarding the change.
+     */
+    do_action( 'deprecated_hook_run', $hook, $replacement, $version, $message );
+
+    /**
+     * Filter whether to trigger deprecated hook errors.
+     *
+     * @since 4.6.0
+     *
+     * @param bool $trigger Whether to trigger deprecated hook errors. Requires
+     *                      `WP_DEBUG` to be defined true.
+     */
+    if ( WP_DEBUG && apply_filters( 'deprecated_hook_trigger_error', true ) ) {
+        $message = empty( $message ) ? '' : ' ' . $message;
+        if ( ! is_null( $replacement ) ) {
+            trigger_error( sprintf( __( '%1$s is <strong>deprecated</strong> since version %2$s! Use %3$s instead.' ), $hook, $version, $replacement ) . $message );
+        } else {
+            trigger_error( sprintf( __( '%1$s is <strong>deprecated</strong> since version %2$s with no alternative available.' ), $hook, $version ) . $message );
+        }
+    }
+}
+
+/**
  * Mark something as being incorrectly called.
  *