WordPress.org
Get WordPress

Make WordPress Core

Changeset 50807


Ignore:
Timestamp:
05/04/2021 10:46:26 AM (4 years 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.

Location:
trunk/src/wp-includes
Files:
2 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    }

  • trunk/src/wp-includes/plugin.php

    r49929 r50807  
    4949
    5050/**
    51  * Hook a function or method to a specific filter action.
     51 * Adds a callback function to a filter hook.
    5252 *
    5353 * WordPress offers filter hooks to allow plugins to modify
    … …  
    102102 * @global WP_Hook[] $wp_filter A multidimensional array of all hooks and the callbacks hooked to them.
    103103 *
    104  * @param string   $tag             The name of the filter to hook the $function_to_add callback to.
    105  * @param callable $function_to_add The callback to be run when the filter is applied.
    106  * @param int      $priority        Optional. Used to specify the order in which the functions
    107  *                                  associated with a particular action are executed.
    108  *                                  Lower numbers correspond with earlier execution,
    109  *                                  and functions with the same priority are executed
    110  *                                  in the order in which they were added to the action. Default 10.
    111  * @param int      $accepted_args   Optional. The number of arguments the function accepts. Default 1.
    112  * @return true
    113  */
    114 function add_filter( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) {
     104 * @param string   $hook_name     The name of the filter to add the callback to.
     105 * @param callable $callback      The callback to be run when the filter is applied.
     106 * @param int      $priority      Optional. Used to specify the order in which the functions
     107 *                                associated with a particular filter are executed.
     108 *                                Lower numbers correspond with earlier execution,
     109 *                                and functions with the same priority are executed
     110 *                                in the order in which they were added to the filter. Default 10.
     111 * @param int      $accepted_args Optional. The number of arguments the function accepts. Default 1.
     112 * @return true Always returns true.
     113 */
     114function add_filter( $hook_name, $callback, $priority = 10, $accepted_args = 1 ) {
    115115    global $wp_filter;
    116     if ( ! isset( $wp_filter[ $tag ] ) ) {
    117         $wp_filter[ $tag ] = new WP_Hook();
    118     }
    119     $wp_filter[ $tag ]->add_filter( $tag, $function_to_add, $priority, $accepted_args );
     116
     117    if ( ! isset( $wp_filter[ $hook_name ] ) ) {
     118        $wp_filter[ $hook_name ] = new WP_Hook();
     119    }
     120
     121    $wp_filter[ $hook_name ]->add_filter( $hook_name, $callback, $priority, $accepted_args );
     122
    120123    return true;
    121124}
    122125
    123126/**
    124  * Checks if any filter has been registered for a hook.
    125  *
    126  * When using the `$function_to_check` argument, this function may return a non-boolean value
    127  * that evaluates to false (e.g. 0), so use the `===` operator for testing the return value.
    128  *
    129  * @since 2.5.0
    130  *
    131  * @global WP_Hook[] $wp_filter Stores all of the filters and actions.
    132  *
    133  * @param string         $tag               The name of the filter hook.
    134  * @param callable|false $function_to_check Optional. The callback to check for. Default false.
    135  * @return bool|int If `$function_to_check` is omitted, returns boolean for whether the hook has
    136  *                  anything registered. When checking a specific function, the priority of that
    137  *                  hook is returned, or false if the function is not attached.
    138  */
    139 function has_filter( $tag, $function_to_check = false ) {
    140     global $wp_filter;
    141 
    142     if ( ! isset( $wp_filter[ $tag ] ) ) {
    143         return false;
    144     }
    145 
    146     return $wp_filter[ $tag ]->has_filter( $tag, $function_to_check );
    147 }
    148 
    149 /**
    150127 * Calls the callback functions that have been added to a filter hook.
    151128 *
    152  * The callback functions attached to the filter hook are invoked by calling
    153  * this function. This function can be used to create a new filter hook by
    154  * simply calling this function with the name of the new hook specified using
    155  * the `$tag` parameter.
     129 * This function invokes all functions attached to filter hook `$hook_name`.
     130 * It is possible to create new filter hooks by simply calling this function,
     131 * specifying the name of the new hook using the `$hook_name` parameter.
    156132 *
    157133 * The function also allows for multiple additional arguments to be passed to hooks.
    … …  
    180156 * @global string[]  $wp_current_filter Stores the list of current filters with the current one last.
    181157 *
    182  * @param string $tag    The name of the filter hook.
    183  * @param mixed  $value   The value to filter.
    184  * @param mixed  ...$args Additional parameters to pass to the callback functions.
     158 * @param string $hook_name The name of the filter hook.
     159 * @param mixed  $value     The value to filter.
     160 * @param mixed  ...$args   Additional parameters to pass to the callback functions.
    185161 * @return mixed The filtered value after all hooked functions are applied to it.
    186162 */
    187 function apply_filters( $tag, $value ) {
     163function apply_filters( $hook_name, $value ) {
    188164    global $wp_filter, $wp_current_filter;
    189165
    … …  
    192168    // Do 'all' actions first.
    193169    if ( isset( $wp_filter['all'] ) ) {
    194         $wp_current_filter[] = $tag;
     170        $wp_current_filter[] = $hook_name;
    195171        _wp_call_all_hook( $args );
    196172    }
    197173
    198     if ( ! isset( $wp_filter[ $tag ] ) ) {
     174    if ( ! isset( $wp_filter[ $hook_name ] ) ) {
    199175        if ( isset( $wp_filter['all'] ) ) {
    200176            array_pop( $wp_current_filter );
    201177        }
     178
    202179        return $value;
    203180    }
    204181
    205182    if ( ! isset( $wp_filter['all'] ) ) {
    206         $wp_current_filter[] = $tag;
     183        $wp_current_filter[] = $hook_name;
    207184    }
    208185
    … …  
    210187    array_shift( $args );
    211188
    212     $filtered = $wp_filter[ $tag ]->apply_filters( $value, $args );
     189    $filtered = $wp_filter[ $hook_name ]->apply_filters( $value, $args );
    213190
    214191    array_pop( $wp_current_filter );
    … …  
    223200 *
    224201 * @see apply_filters() This function is identical, but the arguments passed to the
    225  * functions hooked to `$tag` are supplied using an array.
     202 *                      functions hooked to `$hook_name` are supplied using an array.
    226203 *
    227204 * @global WP_Hook[] $wp_filter         Stores all of the filters and actions.
    228205 * @global string[]  $wp_current_filter Stores the list of current filters with the current one last.
    229206 *
    230  * @param string $tag The name of the filter hook.
    231  * @param array  $args The arguments supplied to the functions hooked to $tag.
     207 * @param string $hook_name The name of the filter hook.
     208 * @param array  $args      The arguments supplied to the functions hooked to `$hook_name`.
    232209 * @return mixed The filtered value after all hooked functions are applied to it.
    233210 */
    234 function apply_filters_ref_array( $tag, $args ) {
     211function apply_filters_ref_array( $hook_name, $args ) {
    235212    global $wp_filter, $wp_current_filter;
    236213
    237214    // Do 'all' actions first.
    238215    if ( isset( $wp_filter['all'] ) ) {
    239         $wp_current_filter[] = $tag;
     216        $wp_current_filter[] = $hook_name;
    240217        $all_args            = func_get_args(); // phpcs:ignore PHPCompatibility.FunctionUse.ArgumentFunctionsReportCurrentValue.NeedsInspection
    241218        _wp_call_all_hook( $all_args );
    242219    }
    243220
    244     if ( ! isset( $wp_filter[ $tag ] ) ) {
     221    if ( ! isset( $wp_filter[ $hook_name ] ) ) {
    245222        if ( isset( $wp_filter['all'] ) ) {
    246223            array_pop( $wp_current_filter );
    247224        }
     225
    248226        return $args[0];
    249227    }
    250228
    251229    if ( ! isset( $wp_filter['all'] ) ) {
    252         $wp_current_filter[] = $tag;
    253     }
    254 
    255     $filtered = $wp_filter[ $tag ]->apply_filters( $args[0], $args );
     230        $wp_current_filter[] = $hook_name;
     231    }
     232
     233    $filtered = $wp_filter[ $hook_name ]->apply_filters( $args[0], $args );
    256234
    257235    array_pop( $wp_current_filter );
    … …  
    261239
    262240/**
    263  * Removes a function from a specified filter hook.
    264  *
    265  * This function removes a function attached to a specified filter hook. This
    266  * method can be used to remove default functions attached to a specific filter
     241 * Checks if any filter has been registered for a hook.
     242 *
     243 * When using the `$callback` argument, this function may return a non-boolean value
     244 * that evaluates to false (e.g. 0), so use the `===` operator for testing the return value.
     245 *
     246 * @since 2.5.0
     247 *
     248 * @global WP_Hook[] $wp_filter Stores all of the filters and actions.
     249 *
     250 * @param string         $hook_name The name of the filter hook.
     251 * @param callable|false $callback  Optional. The callback to check for. Default false.
     252 * @return bool|int If `$callback` is omitted, returns boolean for whether the hook has
     253 *                  anything registered. When checking a specific function, the priority
     254 *                  of that hook is returned, or false if the function is not attached.
     255 */
     256function has_filter( $hook_name, $callback = false ) {
     257    global $wp_filter;
     258
     259    if ( ! isset( $wp_filter[ $hook_name ] ) ) {
     260        return false;
     261    }
     262
     263    return $wp_filter[ $hook_name ]->has_filter( $hook_name, $callback );
     264}
     265
     266/**
     267 * Removes a callback function from a filter hook.
     268 *
     269 * This can be used to remove default functions attached to a specific filter
    267270 * hook and possibly replace them with a substitute.
    268271 *
    269  * To remove a hook, the $function_to_remove and $priority arguments must match
     272 * To remove a hook, the `$callback` and `$priority` arguments must match
    270273 * when the hook was added. This goes for both filters and actions. No warning
    271274 * will be given on removal failure.
    … …  
    275278 * @global WP_Hook[] $wp_filter Stores all of the filters and actions.
    276279 *
    277  * @param string   $tag                The filter hook to which the function to be removed is hooked.
    278  * @param callable $function_to_remove The name of the function which should be removed.
    279  * @param int      $priority           Optional. The priority of the function. Default 10.
    280  * @return bool    Whether the function existed before it was removed.
    281  */
    282 function remove_filter( $tag, $function_to_remove, $priority = 10 ) {
     280 * @param string   $hook_name The filter hook to which the function to be removed is hooked.
     281 * @param callable $callback The name of the function which should be removed.
     282 * @param int      $priority  Optional. The priority of the function. Default 10.
     283 * @return bool Whether the function existed before it was removed.
     284 */
     285function remove_filter( $hook_name, $callback, $priority = 10 ) {
    283286    global $wp_filter;
    284287
    285288    $r = false;
    286     if ( isset( $wp_filter[ $tag ] ) ) {
    287         $r = $wp_filter[ $tag ]->remove_filter( $tag, $function_to_remove, $priority );
    288         if ( ! $wp_filter[ $tag ]->callbacks ) {
    289             unset( $wp_filter[ $tag ] );
     289
     290    if ( isset( $wp_filter[ $hook_name ] ) ) {
     291        $r = $wp_filter[ $hook_name ]->remove_filter( $hook_name, $callback, $priority );
     292
     293        if ( ! $wp_filter[ $hook_name ]->callbacks ) {
     294            unset( $wp_filter[ $hook_name ] );
    290295        }
    291296    }
    … …  
    295300
    296301/**
    297  * Remove all of the hooks from a filter.
     302 * Removes all of the callback functions from a filter hook.
    298303 *
    299304 * @since 2.7.0
    … …  
    301306 * @global WP_Hook[] $wp_filter Stores all of the filters and actions.
    302307 *
    303  * @param string    $tag      The filter to remove hooks from.
    304  * @param int|false $priority Optional. The priority number to remove. Default false.
    305  * @return true True when finished.
    306  */
    307 function remove_all_filters( $tag, $priority = false ) {
     308 * @param string    $hook_name The filter to remove callbacks from.
     309 * @param int|false $priority  Optional. The priority number to remove them from.
     310 *                             Default false.
     311 * @return true Always returns true.
     312 */
     313function remove_all_filters( $hook_name, $priority = false ) {
    308314    global $wp_filter;
    309315
    310     if ( isset( $wp_filter[ $tag ] ) ) {
    311         $wp_filter[ $tag ]->remove_all_filters( $priority );
    312         if ( ! $wp_filter[ $tag ]->has_filters() ) {
    313             unset( $wp_filter[ $tag ] );
     316    if ( isset( $wp_filter[ $hook_name ] ) ) {
     317        $wp_filter[ $hook_name ]->remove_all_filters( $priority );
     318
     319        if ( ! $wp_filter[ $hook_name ]->has_filters() ) {
     320            unset( $wp_filter[ $hook_name ] );
    314321        }
    315322    }
    … …  
    319326
    320327/**
    321  * Retrieve the name of the current filter or action.
     328 * Retrieves the name of the current filter hook.
    322329 *
    323330 * @since 2.5.0
    … …  
    325332 * @global string[] $wp_current_filter Stores the list of current filters with the current one last
    326333 *
    327  * @return string Hook name of the current filter or action.
     334 * @return string Hook name of the current filter.
    328335 */
    329336function current_filter() {
    330337    global $wp_current_filter;
     338
    331339    return end( $wp_current_filter );
    332340}
    333341
    334342/**
    335  * Retrieve the name of the current action.
    336  *
    337  * @since 3.9.0
    338  *
    339  * @return string Hook name of the current action.
    340  */
    341 function current_action() {
    342     return current_filter();
    343 }
    344 
    345 /**
    346  * Retrieve the name of a filter currently being processed.
     343 * Returns whether or not a filter hook is currently being processed.
    347344 *
    348345 * The function current_filter() only returns the most recent filter or action
    … …  
    350347 * processed.
    351348 *
    352  * This function allows detection for any filter currently being
    353  * executed (despite not being the most recent filter to fire, in the case of
     349 * This function allows detection for any filter currently being executed
     350 * (regardless of whether it's the most recent filter to fire, in the case of
    354351 * hooks called from hook callbacks) to be verified.
    355352 *
    … …  
    360357 * @global string[] $wp_current_filter Current filter.
    361358 *
    362  * @param null|string $filter Optional. Filter to check. Defaults to null, which
    363  *                            checks if any filter is currently being run.
     359 * @param null|string $hook_name Optional. Filter hook to check. Defaults to null,
     360 *                               which checks if any filter is currently being run.
    364361 * @return bool Whether the filter is currently in the stack.
    365362 */
    366 function doing_filter( $filter = null ) {
     363function doing_filter( $hook_name = null ) {
    367364    global $wp_current_filter;
    368365
    369     if ( null === $filter ) {
     366    if ( null === $hook_name ) {
    370367        return ! empty( $wp_current_filter );
    371368    }
    372369
    373     return in_array( $filter, $wp_current_filter, true );
    374 }
    375 
    376 /**
    377  * Retrieve the name of an action currently being processed.
    378  *
    379  * @since 3.9.0
    380  *
    381  * @param string|null $action Optional. Action to check. Defaults to null, which checks
    382  *                            if any action is currently being run.
    383  * @return bool Whether the action is currently in the stack.
    384  */
    385 function doing_action( $action = null ) {
    386     return doing_filter( $action );
    387 }
    388 
    389 /**
    390  * Hooks a function on to a specific action.
     370    return in_array( $hook_name, $wp_current_filter, true );
     371}
     372
     373/**
     374 * Adds a callback function to an action hook.
    391375 *
    392376 * Actions are the hooks that the WordPress core launches at specific points
    … …  
    397381 * @since 1.2.0
    398382 *
    399  * @param string   $tag             The name of the action to which the $function_to_add is hooked.
    400  * @param callable $function_to_add The name of the function you wish to be called.
     383 * @param string   $hook_name       The name of the action to add the callback to.
     384 * @param callable $callback        The callback to be run when the action is called.
    401385 * @param int      $priority        Optional. Used to specify the order in which the functions
    402  *                                  associated with a particular action are executed. Default 10.
     386 *                                  associated with a particular action are executed.
    403387 *                                  Lower numbers correspond with earlier execution,
    404388 *                                  and functions with the same priority are executed
    405  *                                  in the order in which they were added to the action.
     389 *                                  in the order in which they were added to the action. Default 10.
    406390 * @param int      $accepted_args   Optional. The number of arguments the function accepts. Default 1.
    407  * @return true Will always return true.
    408  */
    409 function add_action( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) {
    410     return add_filter( $tag, $function_to_add, $priority, $accepted_args );
    411 }
    412 
    413 /**
    414  * Execute functions hooked on a specific action hook.
    415  *
    416  * This function invokes all functions attached to action hook `$tag`. It is
    417  * possible to create new action hooks by simply calling this function,
    418  * specifying the name of the new hook using the `$tag` parameter.
     391 * @return true Always returns true.
     392 */
     393function add_action( $hook_name, $callback, $priority = 10, $accepted_args = 1 ) {
     394    return add_filter( $hook_name, $callback, $priority, $accepted_args );
     395}
     396
     397/**
     398 * Calls the callback functions that have been added to an action hook.
     399 *
     400 * This function invokes all functions attached to action hook `$hook_name`.
     401 * It is possible to create new action hooks by simply calling this function,
     402 * specifying the name of the new hook using the `$hook_name` parameter.
    419403 *
    420404 * You can pass extra arguments to the hooks, much like you can with `apply_filters()`.
    … …  
    444428 * @global string[]  $wp_current_filter Stores the list of current filters with the current one last.
    445429 *
    446  * @param string $tag    The name of the action to be executed.
    447  * @param mixed  ...$arg Optional. Additional arguments which are passed on to the
    448  *                       functions hooked to the action. Default empty.
    449  */
    450 function do_action( $tag, ...$arg ) {
     430 * @param string $hook_name The name of the action to be executed.
     431 * @param mixed  ...$arg    Optional. Additional arguments which are passed on to the
     432 *                          functions hooked to the action. Default empty.
     433 */
     434function do_action( $hook_name, ...$arg ) {
    451435    global $wp_filter, $wp_actions, $wp_current_filter;
    452436
    453     if ( ! isset( $wp_actions[ $tag ] ) ) {
    454         $wp_actions[ $tag ] = 1;
     437    if ( ! isset( $wp_actions[ $hook_name ] ) ) {
     438        $wp_actions[ $hook_name ] = 1;
    455439    } else {
    456         ++$wp_actions[ $tag ];
     440        ++$wp_actions[ $hook_name ];
    457441    }
    458442
    459443    // Do 'all' actions first.
    460444    if ( isset( $wp_filter['all'] ) ) {
    461         $wp_current_filter[] = $tag;
     445        $wp_current_filter[] = $hook_name;
    462446        $all_args            = func_get_args(); // phpcs:ignore PHPCompatibility.FunctionUse.ArgumentFunctionsReportCurrentValue.NeedsInspection
    463447        _wp_call_all_hook( $all_args );
    464448    }
    465449
    466     if ( ! isset( $wp_filter[ $tag ] ) ) {
     450    if ( ! isset( $wp_filter[ $hook_name ] ) ) {
    467451        if ( isset( $wp_filter['all'] ) ) {
    468452            array_pop( $wp_current_filter );
    469453        }
     454
    470455        return;
    471456    }
    472457
    473458    if ( ! isset( $wp_filter['all'] ) ) {
    474         $wp_current_filter[] = $tag;
     459        $wp_current_filter[] = $hook_name;
    475460    }
    476461
    … …  
    482467    }
    483468
    484     $wp_filter[ $tag ]->do_action( $arg );
     469    $wp_filter[ $hook_name ]->do_action( $arg );
    485470
    486471    array_pop( $wp_current_filter );
    … …  
    488473
    489474/**
    490  * Retrieve the number of times an action is fired.
     475 * Calls the callback functions that have been added to an action hook, specifying arguments in an array.
    491476 *
    492477 * @since 2.1.0
    493478 *
    494  * @global int[] $wp_actions Stores the number of times each action was triggered.
    495  *
    496  * @param string $tag The name of the action hook.
    497  * @return int The number of times action hook $tag is fired.
    498  */
    499 function did_action( $tag ) {
    500     global $wp_actions;
    501 
    502     if ( ! isset( $wp_actions[ $tag ] ) ) {
    503         return 0;
    504     }
    505 
    506     return $wp_actions[ $tag ];
    507 }
    508 
    509 /**
    510  * Calls the callback functions that have been added to an action hook, specifying arguments in an array.
    511  *
    512  * @since 2.1.0
    513  *
    514479 * @see do_action() This function is identical, but the arguments passed to the
    515  *                  functions hooked to `$tag` are supplied using an array.
     480 *                  functions hooked to `$hook_name` are supplied using an array.
    516481 *
    517482 * @global WP_Hook[] $wp_filter         Stores all of the filters and actions.
    … …  
    519484 * @global string[]  $wp_current_filter Stores the list of current filters with the current one last.
    520485 *
    521  * @param string $tag The name of the action to be executed.
    522  * @param array  $args The arguments supplied to the functions hooked to `$tag`.
    523  */
    524 function do_action_ref_array( $tag, $args ) {
     486 * @param string $hook_name The name of the action to be executed.
     487 * @param array  $args      The arguments supplied to the functions hooked to `$hook_name`.
     488 */
     489function do_action_ref_array( $hook_name, $args ) {
    525490    global $wp_filter, $wp_actions, $wp_current_filter;
    526491
    527     if ( ! isset( $wp_actions[ $tag ] ) ) {
    528         $wp_actions[ $tag ] = 1;
     492    if ( ! isset( $wp_actions[ $hook_name ] ) ) {
     493        $wp_actions[ $hook_name ] = 1;
    529494    } else {
    530         ++$wp_actions[ $tag ];
     495        ++$wp_actions[ $hook_name ];
    531496    }
    532497
    533498    // Do 'all' actions first.
    534499    if ( isset( $wp_filter['all'] ) ) {
    535         $wp_current_filter[] = $tag;
     500        $wp_current_filter[] = $hook_name;
    536501        $all_args            = func_get_args(); // phpcs:ignore PHPCompatibility.FunctionUse.ArgumentFunctionsReportCurrentValue.NeedsInspection
    537502        _wp_call_all_hook( $all_args );
    538503    }
    539504
    540     if ( ! isset( $wp_filter[ $tag ] ) ) {
     505    if ( ! isset( $wp_filter[ $hook_name ] ) ) {
    541506        if ( isset( $wp_filter['all'] ) ) {
    542507            array_pop( $wp_current_filter );
    543508        }
     509
    544510        return;
    545511    }
    546512
    547513    if ( ! isset( $wp_filter['all'] ) ) {
    548         $wp_current_filter[] = $tag;
    549     }
    550 
    551     $wp_filter[ $tag ]->do_action( $args );
     514        $wp_current_filter[] = $hook_name;
     515    }
     516
     517    $wp_filter[ $hook_name ]->do_action( $args );
    552518
    553519    array_pop( $wp_current_filter );
    … …  
    557523 * Checks if any action has been registered for a hook.
    558524 *
    559  * When using the `$function_to_check` argument, this function may return a non-boolean value
     525 * When using the `$callback` argument, this function may return a non-boolean value
    560526 * that evaluates to false (e.g. 0), so use the `===` operator for testing the return value.
    561527 *
    … …  
    564530 * @see has_filter() has_action() is an alias of has_filter().
    565531 *
    566  * @param string         $tag               The name of the action hook.
    567  * @param callable|false $function_to_check Optional. The callback to check for. Default false.
    568  * @return bool|int If `$function_to_check` is omitted, returns boolean for whether the hook has
    569  *                  anything registered. When checking a specific function, the priority of that
    570  *                  hook is returned, or false if the function is not attached.
    571  */
    572 function has_action( $tag, $function_to_check = false ) {
    573     return has_filter( $tag, $function_to_check );
    574 }
    575 
    576 /**
    577  * Removes a function from a specified action hook.
    578  *
    579  * This function removes a function attached to a specified action hook. This
    580  * method can be used to remove default functions attached to a specific filter
     532 * @param string         $hook_name The name of the action hook.
     533 * @param callable|false $callback  Optional. The callback to check for. Default false.
     534 * @return bool|int If `$callback` is omitted, returns boolean for whether the hook has
     535 *                  anything registered. When checking a specific function, the priority
     536 *                  of that hook is returned, or false if the function is not attached.
     537 */
     538function has_action( $hook_name, $callback = false ) {
     539    return has_filter( $hook_name, $callback );
     540}
     541
     542/**
     543 * Removes a callback function from an action hook.
     544 *
     545 * This can be used to remove default functions attached to a specific action
    581546 * hook and possibly replace them with a substitute.
    582547 *
     548 * To remove a hook, the `$callback` and `$priority` arguments must match
     549 * when the hook was added. This goes for both filters and actions. No warning
     550 * will be given on removal failure.
     551 *
    583552 * @since 1.2.0
    584553 *
    585  * @param string   $tag                The action hook to which the function to be removed is hooked.
    586  * @param callable $function_to_remove The name of the function which should be removed.
    587  * @param int      $priority           Optional. The priority of the function. Default 10.
     554 * @param string   $hook_name The action hook to which the function to be removed is hooked.
     555 * @param callable $callback The name of the function which should be removed.
     556 * @param int      $priority  Optional. The priority of the function. Default 10.
    588557 * @return bool Whether the function is removed.
    589558 */
    590 function remove_action( $tag, $function_to_remove, $priority = 10 ) {
    591     return remove_filter( $tag, $function_to_remove, $priority );
    592 }
    593 
    594 /**
    595  * Remove all of the hooks from an action.
     559function remove_action( $hook_name, $callback, $priority = 10 ) {
     560    return remove_filter( $hook_name, $callback, $priority );
     561}
     562
     563/**
     564 * Removes all of the callback functions from an action hook.
    596565 *
    597566 * @since 2.7.0
    598567 *
    599  * @param string    $tag      The action to remove hooks from.
    600  * @param int|false $priority The priority number to remove them from. Default false.
    601  * @return true True when finished.
    602  */
    603 function remove_all_actions( $tag, $priority = false ) {
    604     return remove_all_filters( $tag, $priority );
     568 * @param string    $hook_name The action to remove callbacks from.
     569 * @param int|false $priority  Optional. The priority number to remove them from.
     570 *                             Default false.
     571 * @return true Always returns true.
     572 */
     573function remove_all_actions( $hook_name, $priority = false ) {
     574    return remove_all_filters( $hook_name, $priority );
     575}
     576
     577/**
     578 * Retrieves the name of the current action hook.
     579 *
     580 * @since 3.9.0
     581 *
     582 * @return string Hook name of the current action.
     583 */
     584function current_action() {
     585    return current_filter();
     586}
     587
     588/**
     589 * Returns whether or not an action hook is currently being processed.
     590 *
     591 * @since 3.9.0
     592 *
     593 * @param string|null $hook_name Optional. Action hook to check. Defaults to null,
     594 *                               which checks if any action is currently being run.
     595 * @return bool Whether the action is currently in the stack.
     596 */
     597function doing_action( $hook_name = null ) {
     598    return doing_filter( $hook_name );
     599}
     600
     601/**
     602 * Retrieves the number of times an action has been fired during the current request.
     603 *
     604 * @since 2.1.0
     605 *
     606 * @global int[] $wp_actions Stores the number of times each action was triggered.
     607 *
     608 * @param string $hook_name The name of the action hook.
     609 * @return int The number of times the action hook has been fired.
     610 */
     611function did_action( $hook_name ) {
     612    global $wp_actions;
     613
     614    if ( ! isset( $wp_actions[ $hook_name ] ) ) {
     615        return 0;
     616    }
     617
     618    return $wp_actions[ $hook_name ];
    605619}
    606620
    … …  
    625639 * @see _deprecated_hook()
    626640 *
    627  * @param string $tag         The name of the filter hook.
     641 * @param string $hook_name   The name of the filter hook.
    628642 * @param array  $args        Array of additional function arguments to be passed to apply_filters().
    629643 * @param string $version     The version of WordPress that deprecated the hook.
    … …  
    631645 * @param string $message     Optional. A message regarding the change. Default empty.
    632646 */
    633 function apply_filters_deprecated( $tag, $args, $version, $replacement = '', $message = '' ) {
    634     if ( ! has_filter( $tag ) ) {
     647function apply_filters_deprecated( $hook_name, $args, $version, $replacement = '', $message = '' ) {
     648    if ( ! has_filter( $hook_name ) ) {
    635649        return $args[0];
    636650    }
    637651
    638     _deprecated_hook( $tag, $version, $replacement, $message );
    639 
    640     return apply_filters_ref_array( $tag, $args );
     652    _deprecated_hook( $hook_name, $version, $replacement, $message );
     653
     654    return apply_filters_ref_array( $hook_name, $args );
    641655}
    642656
    … …  
    652666 * @see _deprecated_hook()
    653667 *
    654  * @param string $tag         The name of the action hook.
     668 * @param string $hook_name   The name of the action hook.
    655669 * @param array  $args        Array of additional function arguments to be passed to do_action().
    656670 * @param string $version     The version of WordPress that deprecated the hook.
    … …  
    658672 * @param string $message     Optional. A message regarding the change. Default empty.
    659673 */
    660 function do_action_deprecated( $tag, $args, $version, $replacement = '', $message = '' ) {
    661     if ( ! has_action( $tag ) ) {
     674function do_action_deprecated( $hook_name, $args, $version, $replacement = '', $message = '' ) {
     675    if ( ! has_action( $hook_name ) ) {
    662676        return;
    663677    }
    664678
    665     _deprecated_hook( $tag, $version, $replacement, $message );
    666 
    667     do_action_ref_array( $tag, $args );
     679    _deprecated_hook( $hook_name, $version, $replacement, $message );
     680
     681    do_action_ref_array( $hook_name, $args );
    668682}
    669683
    … …  
    691705
    692706    arsort( $wp_plugin_paths );
     707
    693708    foreach ( $wp_plugin_paths as $dir => $realdir ) {
    694709        if ( strpos( $file, $realdir ) === 0 ) {
    … …  
    725740    // Normalize, but store as static to avoid recalculation of a constant value.
    726741    static $wp_plugin_path = null, $wpmu_plugin_path = null;
     742
    727743    if ( ! isset( $wp_plugin_path ) ) {
    728744        $wp_plugin_path   = wp_normalize_path( WP_PLUGIN_DIR );
    … …  
    784800 *
    785801 * @param string   $file     The filename of the plugin including the path.
    786  * @param callable $function The function hooked to the 'activate_PLUGIN' action.
    787  */
    788 function register_activation_hook( $file, $function ) {
     802 * @param callable $callback The function hooked to the 'activate_PLUGIN' action.
     803 */
     804function register_activation_hook( $file, $callback ) {
    789805    $file = plugin_basename( $file );
    790     add_action( 'activate_' . $file, $function );
    791 }
    792 
    793 /**
    794  * Set the deactivation hook for a plugin.
     806    add_action( 'activate_' . $file, $callback );
     807}
     808
     809/**
     810 * Sets the deactivation hook for a plugin.
    795811 *
    796812 * When a plugin is deactivated, the action 'deactivate_PLUGINNAME' hook is
    … …  
    807823 *
    808824 * @param string   $file     The filename of the plugin including the path.
    809  * @param callable $function The function hooked to the 'deactivate_PLUGIN' action.
    810  */
    811 function register_deactivation_hook( $file, $function ) {
     825 * @param callable $callback The function hooked to the 'deactivate_PLUGIN' action.
     826 */
     827function register_deactivation_hook( $file, $callback ) {
    812828    $file = plugin_basename( $file );
    813     add_action( 'deactivate_' . $file, $function );
    814 }
    815 
    816 /**
    817  * Set the uninstallation hook for a plugin.
     829    add_action( 'deactivate_' . $file, $callback );
     830}
     831
     832/**
     833 * Sets the uninstallation hook for a plugin.
    818834 *
    819835 * Registers the uninstall hook that will be called when the user clicks on the
    … …  
    853869    $uninstallable_plugins = (array) get_option( 'uninstall_plugins' );
    854870    $plugin_basename       = plugin_basename( $file );
     871
    855872    if ( ! isset( $uninstallable_plugins[ $plugin_basename ] ) || $uninstallable_plugins[ $plugin_basename ] !== $callback ) {
    856873        $uninstallable_plugins[ $plugin_basename ] = $callback;
    … …  
    860877
    861878/**
    862  * Call the 'all' hook, which will process the functions hooked into it.
     879 * Calls the 'all' hook, which will process the functions hooked into it.
    863880 *
    864881 * The 'all' hook passes all of the arguments or parameters that were used for
    … …  
    884901
    885902/**
    886  * Build Unique ID for storage and retrieval.
     903 * Builds Unique ID for storage and retrieval.
    887904 *
    888905 * The old way to serialize the callback caused issues and this function is the
    … …  
    904921 * @since 2.2.3
    905922 * @since 5.3.0 Removed workarounds for spl_object_hash().
    906  *              `$tag` and `$priority` are no longer used,
     923 *              `$hook_name` and `$priority` are no longer used,
    907924 *              and the function always returns a string.
    908925 * @access private
    909926 *
    910  * @param string   $tag      Unused. The name of the filter to build ID for.
    911  * @param callable $function The function to generate ID for.
    912  * @param int      $priority Unused. The order in which the functions
    913  *                           associated with a particular action are executed.
     927 * @param string   $hook_name Unused. The name of the filter to build ID for.
     928 * @param callable $callback The function to generate ID for.
     929 * @param int      $priority  Unused. The order in which the functions
     930 *                            associated with a particular action are executed.
    914931 * @return string Unique function ID for usage as array key.
    915932 */
    916 function _wp_filter_build_unique_id( $tag, $function, $priority ) {
    917     if ( is_string( $function ) ) {
    918         return $function;
    919     }
    920 
    921     if ( is_object( $function ) ) {
     933function _wp_filter_build_unique_id( $hook_name, $callback, $priority ) {
     934    if ( is_string( $callback ) ) {
     935        return $callback;
     936    }
     937
     938    if ( is_object( $callback ) ) {
    922939        // Closures are currently implemented as objects.
    923         $function = array( $function, '' );
     940        $callback = array( $callback, '' );
    924941    } else {
    925         $function = (array) $function;
    926     }
    927 
    928     if ( is_object( $function[0] ) ) {
     942        $callback = (array) $callback;
     943    }
     944
     945    if ( is_object( $callback[0] ) ) {
    929946        // Object class calling.
    930         return spl_object_hash( $function[0] ) . $function[1];
    931     } elseif ( is_string( $function[0] ) ) {
     947        return spl_object_hash( $callback[0] ) . $callback[1];
     948    } elseif ( is_string( $callback[0] ) ) {
    932949        // Static calling.
    933         return $function[0] . '::' . $function[1];
    934     }
    935 }
     950        return $callback[0] . '::' . $callback[1];
     951    }
     952}
Note: See TracChangeset for help on using the changeset viewer.