Ticket #10441: 10441.2.diff

src/wp-includes/functions.php

@@ -3865 +3865 @@
 }
 
 /**
+ * Marks an action or filter hook as deprecated and informs when it has been used.
+ *
+ * There is a hook deprecated_hook_run that will be called that can be used
+ * to get the backtrace up to what file and function was used for the callback.
+ *
+ * The current behavior is to trigger a user error if WP_DEBUG is true.
+ *
+ * This function is to be used for every hook that is deprecated, when any callback is
+ * attacked to the hook, as determined by has_action() or has_filter(), and shall be
+ * called before the hook is fired.
+ *
+ * @since 4.6.0
+ *
+ * @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.
  *
  * There is a hook doing_it_wrong_run that will be called that can be used

src/wp-includes/plugin.php

@@ -655 +655 @@
         return remove_all_filters($tag, $priority);
 }
 
+/**
+ * Fires functions attached to a deprecated filter hook.
+ *
+ * Wraps apply_filters().
+ *
+ * @since 4.4.0
+ *
+ * @see _deprecated_hook()
+ *
+ * @param string $tag         The name of the filter hook.
+ * @param array  $args        Array of additional function arguments to be passed to apply_filters().
+ * @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 apply_filters_deprecated( $tag, $args, $version, $replacement = false, $message = null ) {
+        if ( ! has_filter( $tag ) ) {
+                return;
+        }
+
+        _deprecated_hook( $tag, $version, $replacement, $message );
+
+        return apply_filters_ref_array( $tag, $args );
+}
+
+/**
+ * Fires functions attached to a deprecated action hook.
+ *
+ * Wraps do_action().
+ *
+ * @since 4.6.0
+ *
+ * @see _deprecated_hook()
+ *
+ * @param string $tag         The name of the filter hook.
+ * @param array  $args        Array of additional function arguments to be passed to do_action().
+ * @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 do_action_deprecated( $tag, $args, $version, $replacement = false, $message = null ) {
+        if ( ! has_action( $tag ) ) {
+                return;
+        }
+
+        _deprecated_hook( $tag, $version, $replacement, $message );
+
+        do_action_ref_array( $tag, $args );
+}
+
 //
 // Functions for handling plugins.
 //

tests/phpunit/includes/testcase.php

@@ -309 +309 @@
                 }
                 add_action( 'deprecated_function_run', array( $this, 'deprecated_function_run' ) );
                 add_action( 'deprecated_argument_run', array( $this, 'deprecated_function_run' ) );
+                add_action( 'deprecated_hook_run', array( $this, 'deprecated_function_run' ) );
                 add_action( 'doing_it_wrong_run', array( $this, 'doing_it_wrong_run' ) );
                 add_action( 'deprecated_function_trigger_error', '__return_false' );
                 add_action( 'deprecated_argument_trigger_error', '__return_false' );
+                add_action( 'deprecated_hook_trigger_error',     '__return_false' );
                 add_action( 'doing_it_wrong_trigger_error',      '__return_false' );
         }
 

tests/phpunit/tests/actions.php

@@ -356 +356 @@
                 $this->assertTrue( doing_filter( 'testing_nested' ) );
                 $this->assertFalse( doing_filter( 'something_else' ) );
         }
+
+        /**
+         * @ticket 10441
+         * @expectedDeprecated tests_do_action_deprecated
+         */
+        public function test_do_action_deprecated() {
+                $p = new WP_Post( (object) array( 'post_title' => 'Foo' ) );
+
+                add_action( 'tests_do_action_deprecated', array( __CLASS__, 'deprecated_action_callback' ) );
+                do_action_deprecated( 'tests_do_action_deprecated', array( $p ), '4.6' );
+                remove_action( 'tests_do_action_deprecated', array( __CLASS__, 'deprecated_action_callback' ) );
+
+                $this->assertSame( 'Bar', $p->post_title );
+        }
+
+        public static function deprecated_action_callback( $p ) {
+                $p->post_title = 'Bar';
+        }
+
+        /**
+         * @ticket 10441
+         * @expectedDeprecated tests_do_action_deprecated
+         */
+        public function test_do_action_deprecated_with_multiple_params() {
+                $p1 = new WP_Post( (object) array( 'post_title' => 'Foo1' ) );
+                $p2 = new WP_Post( (object) array( 'post_title' => 'Foo2' ) );
+
+                add_action( 'tests_do_action_deprecated', array( __CLASS__, 'deprecated_action_callback_multiple_params' ), 10, 2 );
+                do_action_deprecated( 'tests_do_action_deprecated', array( $p1, $p2 ), '4.6' );
+                remove_action( 'tests_do_action_deprecated', array( __CLASS__, 'deprecated_action_callback_multiple_params' ), 10, 2 );
+
+                $this->assertSame( 'Bar1', $p1->post_title );
+                $this->assertSame( 'Bar2', $p2->post_title );
+        }
+
+        public static function deprecated_action_callback_multiple_params( $p1, $p2 ) {
+                $p1->post_title = 'Bar1';
+                $p2->post_title = 'Bar2';
+        }
+
+        /**
+         * @ticket 10441
+         * @expectedDeprecated tests_apply_filters_deprecated
+         */
+        public function test_apply_filters_deprecated() {
+                $p = 'Foo';
+
+                add_filter( 'tests_apply_filters_deprecated', array( __CLASS__, 'deprecated_filter_callback' ) );
+                $p = apply_filters_deprecated( 'tests_apply_filters_deprecated', array( $p ), '4.6' );
+                remove_filter( 'tests_apply_filters_deprecated', array( __CLASS__, 'deprecated_filter_callback' ) );
+
+                $this->assertSame( 'Bar', $p );
+        }
+
+        public static function deprecated_filter_callback( $p ) {
+                $p = 'Bar';
+                return $p;
+        }
+
+        /**
+         * @ticket 10441
+         * @expectedDeprecated tests_apply_filters_deprecated
+         */
+        public function test_apply_filters_deprecated_with_multiple_params() {
+                $p1 = 'Foo1';
+                $p2 = 'Foo2';
+
+                add_filter( 'tests_apply_filters_deprecated', array( __CLASS__, 'deprecated_filter_callback_multiple_params' ), 10, 2 );
+                $p1 = apply_filters_deprecated( 'tests_apply_filters_deprecated', array( $p1, $p2 ), '4.6' );
+                remove_filter( 'tests_apply_filters_deprecated', array( __CLASS__, 'deprecated_filter_callback_multiple_params' ), 10, 2 );
+
+                $this->assertSame( 'Bar1', $p1 );
+
+                // Not passed by reference, so not modified.
+                $this->assertSame( 'Foo2', $p2 );
+        }
+
+        public static function deprecated_filter_callback_multiple_params( $p1, $p2 ) {
+                $p1 = 'Bar1';
+                $p2 = 'Bar2';
+
+                return $p1;
+        }
 }