WordPress.org

Make WordPress Core


Ignore:
Timestamp:
05/04/2021 10:46:26 AM (7 months ago)
Author:
SergeyBiryukov
Message:

Plugins: Standardize the terminology used for actions, filters, and callback functions.

Use $hook_name when referring to a filter or action hook name, and $callback when referring to a callback function.

This brings more consistency to parameter names in Plugin API functions.

Includes minor code layout fixes for better readability and reordering some functions in a more logical order.

Props johnbillion, jrf, SergeyBiryukov.
Fixes #50531.

File:
1 edited

Legend:

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

    r49929 r50807  
    5959
    6060    /**
    61      * Hooks a function or method to a specific filter action.
    62      *
    63      * @since 4.7.0
    64      *
    65      * @param string   $tag             The name of the filter to hook the $function_to_add callback to.
    66      * @param callable $function_to_add The callback to be run when the filter is applied.
    67      * @param int      $priority        The order in which the functions associated with a particular action
    68      *                                  are executed. Lower numbers correspond with earlier execution,
    69      *                                  and functions with the same priority are executed in the order
    70      *                                  in which they were added to the action.
    71      * @param int      $accepted_args   The number of arguments the function accepts.
    72      */
    73     public function add_filter( $tag, $function_to_add, $priority, $accepted_args ) {
    74         $idx = _wp_filter_build_unique_id( $tag, $function_to_add, $priority );
     61     * Adds a callback function to the specified filter hook.
     62     *
     63     * @since 4.7.0
     64     *
     65     * @param string   $hook_name     The name of the filter to add the callback to.
     66     * @param callable $callback      The callback to be run when the filter is applied.
     67     * @param int      $priority      The order in which the functions associated with a particular action
     68     *                                are executed. Lower numbers correspond with earlier execution,
     69     *                                and functions with the same priority are executed in the order
     70     *                                in which they were added to the action.
     71     * @param int      $accepted_args The number of arguments the function accepts.
     72     */
     73    public function add_filter( $hook_name, $callback, $priority, $accepted_args ) {
     74        $idx = _wp_filter_build_unique_id( $hook_name, $callback, $priority );
    7575
    7676        $priority_existed = isset( $this->callbacks[ $priority ] );
    7777
    7878        $this->callbacks[ $priority ][ $idx ] = array(
    79             'function'      => $function_to_add,
     79            'function'      => $callback,
    8080            'accepted_args' => $accepted_args,
    8181        );
     
    109109                $this->iterations[ $index ] = $new_priorities;
    110110            }
     111
    111112            return;
    112113        }
    113114
    114115        $min = min( $new_priorities );
     116
    115117        foreach ( $this->iterations as $index => &$iteration ) {
    116118            $current = current( $iteration );
     119
    117120            // If we're already at the end of this iteration, just leave the array pointer where it is.
    118121            if ( false === $current ) {
     
    147150                    $prev = prev( $iteration );
    148151                }
     152
    149153                if ( false === $prev ) {
    150154                    // Start of the array. Reset, and go about our day.
     
    156160            }
    157161        }
     162
    158163        unset( $iteration );
    159164    }
    160165
    161166    /**
    162      * Unhooks a function or method from a specific filter action.
    163      *
    164      * @since 4.7.0
    165      *
    166      * @param string   $tag                The filter hook to which the function to be removed is hooked.
    167      * @param callable $function_to_remove The callback to be removed from running when the filter is applied.
    168      * @param int      $priority           The exact priority used when adding the original filter callback.
     167     * Removes a callback function from the specified filter hook.
     168     *
     169     * @since 4.7.0
     170     *
     171     * @param string   $hook_name The filter hook to which the function to be removed is hooked.
     172     * @param callable $callback The callback to be removed from running when the filter is applied.
     173     * @param int      $priority  The exact priority used when adding the original filter callback.
    169174     * @return bool Whether the callback existed before it was removed.
    170175     */
    171     public function remove_filter( $tag, $function_to_remove, $priority ) {
    172         $function_key = _wp_filter_build_unique_id( $tag, $function_to_remove, $priority );
     176    public function remove_filter( $hook_name, $callback, $priority ) {
     177        $function_key = _wp_filter_build_unique_id( $hook_name, $callback, $priority );
    173178
    174179        $exists = isset( $this->callbacks[ $priority ][ $function_key ] );
     180
    175181        if ( $exists ) {
    176182            unset( $this->callbacks[ $priority ][ $function_key ] );
     183
    177184            if ( ! $this->callbacks[ $priority ] ) {
    178185                unset( $this->callbacks[ $priority ] );
     186
    179187                if ( $this->nesting_level > 0 ) {
    180188                    $this->resort_active_iterations();
     
    182190            }
    183191        }
     192
    184193        return $exists;
    185194    }
    186195
    187196    /**
    188      * Checks if a specific action has been registered for this hook.
    189      *
    190      * When using the `$function_to_check` argument, this function may return a non-boolean value
     197     * Checks if a specific callback has been registered for this hook.
     198     *
     199     * When using the `$callback` argument, this function may return a non-boolean value
    191200     * that evaluates to false (e.g. 0), so use the `===` operator for testing the return value.
    192201     *
    193202     * @since 4.7.0
    194203     *
    195      * @param string         $tag              Optional. The name of the filter hook. Default empty.
    196      * @param callable|false $function_to_check Optional. The callback to check for. Default false.
    197      * @return bool|int If `$function_to_check` is omitted, returns boolean for whether the hook has
    198      *                  anything registered. When checking a specific function, the priority of that
    199      *                  hook is returned, or false if the function is not attached.
    200      */
    201     public function has_filter( $tag = '', $function_to_check = false ) {
    202         if ( false === $function_to_check ) {
     204     * @param string         $hook_name Optional. The name of the filter hook. Default empty.
     205     * @param callable|false $callback Optional. The callback to check for. Default false.
     206     * @return bool|int If `$callback` is omitted, returns boolean for whether the hook has
     207     *                  anything registered. When checking a specific function, the priority
     208     *                  of that hook is returned, or false if the function is not attached.
     209     */
     210    public function has_filter( $hook_name = '', $callback = false ) {
     211        if ( false === $callback ) {
    203212            return $this->has_filters();
    204213        }
    205214
    206         $function_key = _wp_filter_build_unique_id( $tag, $function_to_check, false );
     215        $function_key = _wp_filter_build_unique_id( $hook_name, $callback, false );
     216
    207217        if ( ! $function_key ) {
    208218            return false;
     
    231241            }
    232242        }
     243
    233244        return false;
    234245    }
     
    335346        do {
    336347            $priority = current( $this->iterations[ $nesting_level ] );
     348
    337349            foreach ( $this->callbacks[ $priority ] as $the_ ) {
    338350                call_user_func_array( $the_['function'], $args );
     
    349361     * @since 4.7.0
    350362     *
    351      * @return int|false If the hook is running, return the current priority level. If it isn't running, return false.
     363     * @return int|false If the hook is running, return the current priority level.
     364     *                   If it isn't running, return false.
    352365     */
    353366    public function current_priority() {
     
    392405        $normalized = array();
    393406
    394         foreach ( $filters as $tag => $callback_groups ) {
     407        foreach ( $filters as $hook_name => $callback_groups ) {
    395408            if ( is_object( $callback_groups ) && $callback_groups instanceof WP_Hook ) {
    396                 $normalized[ $tag ] = $callback_groups;
     409                $normalized[ $hook_name ] = $callback_groups;
    397410                continue;
    398411            }
     412
    399413            $hook = new WP_Hook();
    400414
     
    404418                // Loop through callbacks.
    405419                foreach ( $callbacks as $cb ) {
    406                     $hook->add_filter( $tag, $cb['function'], $priority, $cb['accepted_args'] );
    407                 }
    408             }
    409             $normalized[ $tag ] = $hook;
    410         }
     420                    $hook->add_filter( $hook_name, $cb['function'], $priority, $cb['accepted_args'] );
     421                }
     422            }
     423
     424            $normalized[ $hook_name ] = $hook;
     425        }
     426
    411427        return $normalized;
    412428    }
Note: See TracChangeset for help on using the changeset viewer.