WordPress.org

Make WordPress Core

Changeset 37861


Ignore:
Timestamp:
06/25/2016 07:56:19 PM (2 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.

Location:
trunk
Files:
4 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/functions.php

    r37717 r37861  
    38943894
    38953895/**
     3896 * Marks a deprecated action or filter hook as deprecated and throws a notice.
     3897 *
     3898 * Use the 'deprecated_hook_run' action to get the backtrace describing where the
     3899 * deprecated hook was called.
     3900 *
     3901 * Default behavior is to trigger a user error if WP_DEBUG is true.
     3902 *
     3903 * This function is called by the do_action_deprecated() and apply_filters_deprecated()
     3904 * functions, and so generally does not need to be called directly.
     3905 *
     3906 * @since 4.6.0
     3907 * @access private
     3908 *
     3909 * @param string $hook        The hook that was used.
     3910 * @param string $version     The version of WordPress that deprecated the hook.
     3911 * @param string $replacement Optional. The hook that should have been used.
     3912 * @param string $message     Optional. A message regarding the change.
     3913 */
     3914function _deprecated_hook( $hook, $version, $replacement = null, $message = null ) {
     3915    /**
     3916     * Fires when a deprecated hook is called.
     3917     *
     3918     * @since 4.6.0
     3919     *
     3920     * @param string $hook        The hook that was called.
     3921     * @param string $replacement The hook that should be used as a replacement.
     3922     * @param string $version     The version of WordPress that deprecated the argument used.
     3923     * @param string $message     A message regarding the change.
     3924     */
     3925    do_action( 'deprecated_hook_run', $hook, $replacement, $version, $message );
     3926
     3927    /**
     3928     * Filter whether to trigger deprecated hook errors.
     3929     *
     3930     * @since 4.6.0
     3931     *
     3932     * @param bool $trigger Whether to trigger deprecated hook errors. Requires
     3933     *                      `WP_DEBUG` to be defined true.
     3934     */
     3935    if ( WP_DEBUG && apply_filters( 'deprecated_hook_trigger_error', true ) ) {
     3936        $message = empty( $message ) ? '' : ' ' . $message;
     3937        if ( ! is_null( $replacement ) ) {
     3938            trigger_error( sprintf( __( '%1$s is <strong>deprecated</strong> since version %2$s! Use %3$s instead.' ), $hook, $version, $replacement ) . $message );
     3939        } else {
     3940            trigger_error( sprintf( __( '%1$s is <strong>deprecated</strong> since version %2$s with no alternative available.' ), $hook, $version ) . $message );
     3941        }
     3942    }
     3943}
     3944
     3945/**
    38963946 * Mark something as being incorrectly called.
    38973947 *
  • trunk/src/wp-includes/plugin.php

    r37674 r37861  
    654654function remove_all_actions($tag, $priority = false) {
    655655    return remove_all_filters($tag, $priority);
     656}
     657
     658/**
     659 * Fires functions attached to a deprecated filter hook.
     660 *
     661 * When a filter hook is deprecated, the apply_filters() call is replaced with
     662 * apply_filters_deprecated(), which triggers a deprecation notice and then fires
     663 * the original filter hook.
     664 *
     665 * @since 4.6.0
     666 *
     667 * @see _deprecated_hook()
     668 *
     669 * @param string $tag         The name of the filter hook.
     670 * @param array  $args        Array of additional function arguments to be passed to apply_filters().
     671 * @param string $version     The version of WordPress that deprecated the hook.
     672 * @param string $replacement Optional. The hook that should have been used.
     673 * @param string $message     Optional. A message regarding the change.
     674 */
     675function apply_filters_deprecated( $tag, $args, $version, $replacement = false, $message = null ) {
     676    if ( ! has_filter( $tag ) ) {
     677        return;
     678    }
     679
     680    _deprecated_hook( $tag, $version, $replacement, $message );
     681
     682    return apply_filters_ref_array( $tag, $args );
     683}
     684
     685/**
     686 * Fires functions attached to a deprecated action hook.
     687 *
     688 * When an action hook is deprecated, the do_action() call is replaced with
     689 * do_action_deprecated(), which triggers a deprecation notice and then fires
     690 * the original hook.
     691 *
     692 * @since 4.6.0
     693 *
     694 * @see _deprecated_hook()
     695 *
     696 * @param string $tag         The name of the action hook.
     697 * @param array  $args        Array of additional function arguments to be passed to do_action().
     698 * @param string $version     The version of WordPress that deprecated the hook.
     699 * @param string $replacement Optional. The hook that should have been used.
     700 * @param string $message     Optional. A message regarding the change.
     701 */
     702function do_action_deprecated( $tag, $args, $version, $replacement = false, $message = null ) {
     703    if ( ! has_action( $tag ) ) {
     704        return;
     705    }
     706
     707    _deprecated_hook( $tag, $version, $replacement, $message );
     708
     709    do_action_ref_array( $tag, $args );
    656710}
    657711
  • trunk/tests/phpunit/includes/testcase.php

    r37319 r37861  
    310310        add_action( 'deprecated_function_run', array( $this, 'deprecated_function_run' ) );
    311311        add_action( 'deprecated_argument_run', array( $this, 'deprecated_function_run' ) );
     312        add_action( 'deprecated_hook_run', array( $this, 'deprecated_function_run' ) );
    312313        add_action( 'doing_it_wrong_run', array( $this, 'doing_it_wrong_run' ) );
    313314        add_action( 'deprecated_function_trigger_error', '__return_false' );
    314315        add_action( 'deprecated_argument_trigger_error', '__return_false' );
     316        add_action( 'deprecated_hook_trigger_error',     '__return_false' );
    315317        add_action( 'doing_it_wrong_trigger_error',      '__return_false' );
    316318    }
  • trunk/tests/phpunit/tests/actions.php

    r37588 r37861  
    420420        $this->assertFalse( doing_filter( 'something_else' ) );
    421421    }
     422
     423    /**
     424     * @ticket 10441
     425     * @expectedDeprecated tests_do_action_deprecated
     426     */
     427    public function test_do_action_deprecated() {
     428        $p = new WP_Post( (object) array( 'post_title' => 'Foo' ) );
     429
     430        add_action( 'tests_do_action_deprecated', array( __CLASS__, 'deprecated_action_callback' ) );
     431        do_action_deprecated( 'tests_do_action_deprecated', array( $p ), '4.6' );
     432        remove_action( 'tests_do_action_deprecated', array( __CLASS__, 'deprecated_action_callback' ) );
     433
     434        $this->assertSame( 'Bar', $p->post_title );
     435    }
     436
     437    public static function deprecated_action_callback( $p ) {
     438        $p->post_title = 'Bar';
     439    }
     440
     441    /**
     442     * @ticket 10441
     443     * @expectedDeprecated tests_do_action_deprecated
     444     */
     445    public function test_do_action_deprecated_with_multiple_params() {
     446        $p1 = new WP_Post( (object) array( 'post_title' => 'Foo1' ) );
     447        $p2 = new WP_Post( (object) array( 'post_title' => 'Foo2' ) );
     448
     449        add_action( 'tests_do_action_deprecated', array( __CLASS__, 'deprecated_action_callback_multiple_params' ), 10, 2 );
     450        do_action_deprecated( 'tests_do_action_deprecated', array( $p1, $p2 ), '4.6' );
     451        remove_action( 'tests_do_action_deprecated', array( __CLASS__, 'deprecated_action_callback_multiple_params' ), 10, 2 );
     452
     453        $this->assertSame( 'Bar1', $p1->post_title );
     454        $this->assertSame( 'Bar2', $p2->post_title );
     455    }
     456
     457    public static function deprecated_action_callback_multiple_params( $p1, $p2 ) {
     458        $p1->post_title = 'Bar1';
     459        $p2->post_title = 'Bar2';
     460    }
     461
     462    /**
     463     * @ticket 10441
     464     * @expectedDeprecated tests_apply_filters_deprecated
     465     */
     466    public function test_apply_filters_deprecated() {
     467        $p = 'Foo';
     468
     469        add_filter( 'tests_apply_filters_deprecated', array( __CLASS__, 'deprecated_filter_callback' ) );
     470        $p = apply_filters_deprecated( 'tests_apply_filters_deprecated', array( $p ), '4.6' );
     471        remove_filter( 'tests_apply_filters_deprecated', array( __CLASS__, 'deprecated_filter_callback' ) );
     472
     473        $this->assertSame( 'Bar', $p );
     474    }
     475
     476    public static function deprecated_filter_callback( $p ) {
     477        $p = 'Bar';
     478        return $p;
     479    }
     480
     481    /**
     482     * @ticket 10441
     483     * @expectedDeprecated tests_apply_filters_deprecated
     484     */
     485    public function test_apply_filters_deprecated_with_multiple_params() {
     486        $p1 = 'Foo1';
     487        $p2 = 'Foo2';
     488
     489        add_filter( 'tests_apply_filters_deprecated', array( __CLASS__, 'deprecated_filter_callback_multiple_params' ), 10, 2 );
     490        $p1 = apply_filters_deprecated( 'tests_apply_filters_deprecated', array( $p1, $p2 ), '4.6' );
     491        remove_filter( 'tests_apply_filters_deprecated', array( __CLASS__, 'deprecated_filter_callback_multiple_params' ), 10, 2 );
     492
     493        $this->assertSame( 'Bar1', $p1 );
     494
     495        // Not passed by reference, so not modified.
     496        $this->assertSame( 'Foo2', $p2 );
     497    }
     498
     499    public static function deprecated_filter_callback_multiple_params( $p1, $p2 ) {
     500        $p1 = 'Bar1';
     501        $p2 = 'Bar2';
     502
     503        return $p1;
     504    }
    422505}
Note: See TracChangeset for help on using the changeset viewer.