WordPress.org

Make WordPress Core

Changeset 37861


Ignore:
Timestamp:
06/25/16 19:56:19 (12 months 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.