Ticket #5225: plugin.phpdoc.diff

File plugin.phpdoc.diff, 19.5 KB (added by darkdragon, 5 years ago)

Final time, corrects @uses, @link tags. Same as old patch.

  • plugin.php

     
    11<?php 
     2/** 
     3 * The plugin API is located in this file, which allows for creating actions 
     4 * and filters and hooking functions, and methods. The functions or methods will 
     5 * then be run when the action or filter is called. 
     6 * 
     7 * The API callback examples reference functions, but can be methods of classes. 
     8 * To hook methods, you'll need to pass an array one of two ways. 
     9 * 
     10 * For static methods (you won't have access to the <tt>$this</tt> variable in the 
     11 * method): 
     12 * <code>array('class_name', 'method_name');</code> 
     13 * 
     14 * The second method will need the reference to the object to have access to the 
     15 * method. 
     16 * <code>array(&$this, 'method_name');</code> 
     17 * <code> 
     18 * $obj = new myObject(); 
     19 * array(&$obj, 'method_name'); 
     20 * </code> 
     21 * Any of the syntaxes explained in the PHP documentation for the 
     22 * {@link http://us2.php.net/manual/en/language.pseudo-types.php#language.types.callback 'callback' type} are valid. 
     23 * 
     24 * Also see the {@link http://codex.wordpress.org/Plugin_API Plugin API} for more information 
     25 * and examples on how to use a lot of these functions. 
     26 * 
     27 * @package WordPress 
     28 * @subpackage Plugin 
     29 * @since 1.5 
     30 */ 
    231 
    332/** 
    4  * Hooks a function to a specific filter action. 
     33 * { @internal add_filter() }} 
    534 * 
     35 * Hooks a function or method to a specific filter action. 
     36 * 
    637 * Filters are the hooks that WordPress launches to modify text of various types 
    738 * before adding it to the database or sending it to the browser screen. Plugins 
    839 * can specify that one or more of its PHP functions is executed to 
    940 * modify specific types of text at these times, using the Filter API. 
    10  * See the [Plugin API] for a list of filter hooks. 
    1141 * 
     42 * To use the API, the following code should be used to bind a callback to the filter 
     43 * <code> 
     44 * function example_hook($example) { echo $example; } 
     45 * 
     46 * add_filter('example_filter', 'example_hook'); 
     47 * </code> 
     48 * 
     49 * In WordPress 1.5.1+, hooked functions can take extra arguments that are set when 
     50 * the matching do_action() or apply_filters() call is run. The <tt>$accepted_args 
     51 * allow for calling functions only when the number of args match. Hooked functions 
     52 * can take extra arguments that are set when the matching <tt>do_action()</tt> or 
     53 * <tt>apply_filters()</tt> call is run. For example, the action <tt>comment_id_not_found</tt> 
     54 * will pass any functions that hook onto it the ID of the requested comment. 
     55 * 
     56 * <strong>Note:</strong> the function will return true no matter if the function was hooked 
     57 * fails or not. There are no checks for whether the function exists beforehand and no checks 
     58 * to whether the <tt>$function_to_add is even a string. It is up to you to take care and 
     59 * this is done for optimization purposes, so everything is as quick as possible. 
     60 * 
     61 * @package WordPress 
     62 * @subpackage Plugin 
     63 * @since 1.5 
     64 * @global array $wp_filter Stores all of the filters added in the form of 
     65 *      wp_filter['tag']['array of priorities']['array of functions serialized']['array of ['array (functions, accepted_args)]'] 
     66 * @global array $merged_filters Tracks the tags that need to be merged for later. If the hook is added, it doesn't need to run through that process. 
     67 * 
    1268 * @param string $tag The name of the filter to hook the <tt>$function_to_add</tt> to. 
    1369 * @param callback $function_to_add The name of the function to be called when the filter is applied. 
    1470 * @param int $priority optional. Used to specify the order in which the functions associated with a particular action are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action. 
    15  * @param int $accepted_args optional. The number of arguments the function accept (default 1). In WordPress 1.5.1+, hooked functions can take extra arguments that are set when the matching do_action() or apply_filters() call is run. 
    16  * @return boolean true if the <tt>$function_to_add</tt> is added succesfully to filter <tt>$tag</tt>. How many arguments your function takes. In WordPress 1.5.1+, hooked functions can take extra arguments that are set when the matching <tt>do_action()</tt> or <tt>apply_filters()</tt> call is run. For example, the action <tt>comment_id_not_found</tt> will pass any functions that hook onto it the ID of the requested comment. 
     71 * @param int $accepted_args optional. The number of arguments the function accept (default 1). 
     72 * @return boolean true 
    1773 */ 
    1874function add_filter($tag, $function_to_add, $priority = 10, $accepted_args = 1) { 
    1975        global $wp_filter, $merged_filters; 
    2076 
    21         // So the format is wp_filter['tag']['array of priorities']['array of functions serialized']['array of ['array (functions, accepted_args)]'] 
    2277        $idx = _wp_filter_build_unique_id($tag, $function_to_add, $priority); 
    23     $wp_filter[$tag][$priority][$idx] = array('function' => $function_to_add, 'accepted_args' => $accepted_args); 
    24         //$wp_filter[$tag][$priority][serialize($function_to_add)] = array('function' => $function_to_add, 'accepted_args' => $accepted_args); 
     78        $wp_filter[$tag][$priority][$idx] = array('function' => $function_to_add, 'accepted_args' => $accepted_args); 
    2579        unset( $merged_filters[ $tag ] ); 
    2680        return true; 
    2781} 
    2882 
    2983/** 
     84 * { @internal apply_filters() }} 
     85 * 
    3086 * Call the functions added to a filter hook. 
    3187 * 
    3288 * The callback functions attached to filter hook <tt>$tag</tt> are invoked by 
    3389 * calling this function. This function can be used to create a new filter hook 
    3490 * by simply calling this function with the name of the new hook specified using 
    3591 * the <tt>$tag</a> parameter. 
    36  * @uses merge_filters Merges the filter hooks using this function. 
     92 * 
     93 * The function allows for additional arguments to be added and passed to hooks. 
     94 * <code> 
     95 * function example_hook($string, $arg1, $arg2) 
     96 * { 
     97 *              //Do stuff 
     98 * } 
     99 * $value = apply_filters('example_filter', 'filter me', 'arg1', 'arg2'); 
     100 * </code> 
     101 * 
     102 * @package WordPress 
     103 * @subpackage Plugin 
     104 * @since 1.5 
     105 * @global array $wp_filter Stores all of the filters 
     106 * @global array $merge_filters Merges the filter hooks using this function. 
     107 * 
    37108 * @param string $tag The name of the filter hook. 
    38  * @param string $string The text on which the filters hooked to <tt>$tag</tt> are applied on. 
     109 * @param string $value The value on which the filters hooked to <tt>$tag</tt> are applied on. 
    39110 * @param mixed $var,... Additional variables passed to the functions hooked to <tt>$tag</tt>. 
    40111 * @return string The text in <tt>$string</tt> after all hooked functions are applied to it. 
    41112 */ 
    42 function apply_filters($tag, $string) { 
     113function apply_filters($tag, $value) { 
    43114        global $wp_filter, $merged_filters; 
    44115 
    45116        if ( !isset( $merged_filters[ $tag ] ) ) 
    46117                merge_filters($tag); 
    47118 
    48119        if ( !isset($wp_filter[$tag]) ) 
    49                 return $string; 
     120                return $value; 
    50121 
    51122        reset( $wp_filter[ $tag ] ); 
    52123 
    … …  
    55126        do{ 
    56127                foreach( (array) current($wp_filter[$tag]) as $the_ ) 
    57128                        if ( !is_null($the_['function']) ){ 
    58                                 $args[1] = $string; 
    59                                 $string = call_user_func_array($the_['function'], array_slice($args, 1, (int) $the_['accepted_args'])); 
     129                                $args[1] = $value; 
     130                                $value = call_user_func_array($the_['function'], array_slice($args, 1, (int) $the_['accepted_args'])); 
    60131                        } 
    61132 
    62133        } while ( next($wp_filter[$tag]) !== false ); 
    63134 
    64         return $string; 
     135        return $value; 
    65136} 
    66137 
    67138/** 
     139 * { @internal merge_filters() }} 
     140 * 
    68141 * Merge the filter functions of a specific filter hook with generic filter functions. 
    69142 * 
    70143 * It is possible to defined generic filter functions using the filter hook 
    71144 * <em>all</e>. These functions are called for every filter tag. This function 
    72145 * merges the functions attached to the <em>all</em> hook with the functions 
    73  * of a specific hoook defined by <tt>$tag</tt>. 
     146 * of a specific hook defined by <tt>$tag</tt>. 
     147 * 
     148 * Bugged if you hook into 'all' tag, then you <strong>will</strong> lose all priority 
     149 * information. {@link http://trac.wordpress.org/ticket/4715 Bug #4715} for more information. 
     150 * 
     151 * @package WordPress 
     152 * @subpackage Plugin 
     153 * @since 1.5 
     154 * @global array $wp_filter Stores all of the filters 
     155 * @global array $merge_filters Merges the filter hooks using this function. 
     156 * 
    74157 * @param string $tag The filter hook of which the functions should be merged. 
    75158 */ 
    76159function merge_filters($tag) { 
    … …  
    87170} 
    88171 
    89172/** 
     173 * { @internal remove_filter() }} 
     174 * 
    90175 * Removes a function from a specified filter hook. 
    91176 * 
    92177 * This function removes a function attached to a specified filter hook. This 
    93178 * method can be used to remove default functions attached to a specific filter 
    94179 * hook and possibly replace them with a substitute. 
     180 * 
     181 * To remove a hook, the <tt>$function_to_remove</tt> and <tt>$priority</tt> arguments 
     182 * must match when the hook was added. This goes for both filters and actions. No warning 
     183 * will be given on removal failure. 
     184 * 
     185 * @package WordPress 
     186 * @subpackage Plugin 
     187 * @since 1.5 
     188 * 
    95189 * @param string $tag The filter hook to which the function to be removed is hooked. 
    96190 * @param callback $function_to_remove The name of the function which should be removed. 
    97191 * @param int $priority optional. The priority of the function (default: 10). 
    98192 * @param int $accepted_args optional. The number of arguments the function accpets (default: 1). 
    99  * @return boolean Whether the function is removed. 
     193 * @return boolean Whether the function existed before it was removed. 
    100194 */ 
    101195function remove_filter($tag, $function_to_remove, $priority = 10, $accepted_args = 1) { 
    102196        $function_to_remove = _wp_filter_build_unique_id($tag, $function_to_remove, $priority); 
    … …  
    110204} 
    111205 
    112206/** 
     207 * { @internal add_action() }} 
     208 * 
    113209 * Hooks a function on to a specific action. 
    114210 * 
    115211 * Actions are the hooks that the WordPress core launches at specific points 
    … …  
    117213 * one or more of its PHP functions are executed at these points, using the 
    118214 * Action API. 
    119215 * 
     216 * @uses add_filter() Adds an action. Parameter list and functionality are the same. 
     217 * 
     218 * @package WordPress 
     219 * @subpackage Plugin 
     220 * @since 1.5 
     221 * 
    120222 * @param string $tag The name of the action to which the <tt>$function_to-add</tt> is hooked. 
    121  * @param callback $function_to_add The name of the function you wish to be called. Note: any of the syntaxes explained in the PHP documentation for the 'callback' type (http://us2.php.net/manual/en/language.pseudo-types.php#language.types.callback) are valid. 
     223 * @param callback $function_to_add The name of the function you wish to be called. 
    122224 * @param int $priority optional. Used to specify the order in which the functions associated with a particular action are executed (default: 10). Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action. 
    123  * @param int $accepted_args optional. The number of arguments the function accept (default 1). In WordPress 1.5.1+, hooked functions can take extra arguments that are set when the matching do_action() or apply_filters() call is run. 
    124  * @return boolean Always true. 
     225 * @param int $accepted_args optional. The number of arguments the function accept (default 1). 
    125226 */ 
    126227function add_action($tag, $function_to_add, $priority = 10, $accepted_args = 1) { 
    127228        add_filter($tag, $function_to_add, $priority, $accepted_args); 
    128229} 
    129230 
    130231/** 
     232 * { @internal do_action() }} 
     233 * 
    131234 * Execute functions hooked on a specific action hook. 
    132235 * 
    133236 * This function invokes all functions attached to action hook <tt>$tag</tt>. 
    134237 * It is possible to create new action hooks by simply calling this function, 
    135238 * specifying the name of the new hook using the <tt>$tag</tt> parameter. 
    136  * @uses merge_filters 
     239 * 
     240 * You can pass extra arguments to the hooks, much like you can with apply_filters(). 
     241 * 
     242 * @see apply_filters() This function works similar with the exception that nothing is 
     243 * returned and only the functions or methods are called. 
     244 * 
     245 * @package WordPress 
     246 * @subpackage Plugin 
     247 * @since 1.5 
     248 * @global array $wp_filter Stores all of the filters 
     249 * @global array $wp_actions Increments the amount of times action was triggered. 
     250 * 
    137251 * @param string $tag The name of the action to be executed. 
    138252 * @param mixed $arg,... Optional additional arguments which are passed on to the functions hooked to the action. 
     253 * @return null Will return null if $tag does not exist in $wp_filter array 
    139254 */ 
    140255function do_action($tag, $arg = '') { 
    141256        global $wp_filter, $wp_actions; 
    … …  
    168283} 
    169284 
    170285/** 
     286 * { @internal did_action() }} 
     287 * 
    171288 * Return the number times an action is fired. 
     289 * 
     290 * @package WordPress 
     291 * @subpackage Plugin 
     292 * @since 2.1 
     293 * @global array $wp_actions Increments the amount of times action was triggered. 
     294 * 
    172295 * @param string $tag The name of the action hook. 
    173296 * @return int The number of times action hook <tt>$tag</tt> is fired 
    174297 */ 
    … …  
    182305} 
    183306 
    184307/** 
    185  * Execute functions hooked on a specific action hook, specifying arguments in a array. 
     308 * { @internal do_action_ref_array() }} 
    186309 * 
    187  * This function is identical to {@link do_action}, but the argumetns passe to 
     310 * Execute functions hooked on a specific action hook, specifying arguments in an array. 
     311 * 
     312 * @see do_action() This function is identical, but the arguments passed to 
    188313 * the functions hooked to <tt>$tag</tt> are supplied using an array. 
     314 * 
     315 * @uses merge_filters() 
     316 * 
     317 * @package WordPress 
     318 * @subpackage Plugin 
     319 * @since 2.1 
     320 * @global array $wp_filter Stores all of the filters 
     321 * @global array $wp_actions Increments the amount of times action was triggered. 
     322 * 
    189323 * @param string $tag The name of the action to be executed. 
    190324 * @param array $args The arguments supplied to the functions hooked to <tt>$tag</tt> 
     325 * @return null Will return null if $tag does not exist in $wp_filter array 
    191326 */ 
    192327function do_action_ref_array($tag, $args) { 
    193328        global $wp_filter, $wp_actions; 
    … …  
    212347} 
    213348 
    214349/** 
     350 * { @internal remove_action() }} 
     351 * 
    215352 * Removes a function from a specified action hook. 
    216353 * 
    217354 * This function removes a function attached to a specified action hook. This 
    218355 * method can be used to remove default functions attached to a specific filter 
    219356 * hook and possibly replace them with a substitute. 
     357 * 
     358 * @uses remove_filter() Uses remove_filter to remove actions added. 
     359 * 
     360 * @package WordPress 
     361 * @subpackage Plugin 
     362 * @since 1.5 
     363 * 
    220364 * @param string $tag The action hook to which the function to be removed is hooked. 
    221365 * @param callback $function_to_remove The name of the function which should be removed. 
    222366 * @param int $priority optional The priority of the function (default: 10). 
    … …  
    232376// 
    233377 
    234378/** 
     379 * { @internal plugin_basename() }} 
     380 * @access private 
     381 * 
    235382 * Gets the basename of a plugin. 
    236383 * 
    237384 * This method extract the name of a plugin from its filename. 
     385 * 
     386 * @package WordPress 
     387 * @subpackage Plugin 
     388 * @since 1.5 
     389 * 
    238390 * @param string $file The filename of plugin. 
    239391 * @return string The name of a plugin. 
    240392 */ 
    … …  
    246398} 
    247399 
    248400/** 
     401 * { @internal register_activation_hook() }} 
     402 * @access private 
     403 * 
    249404 * Hook a function on a plugin activation action hook. 
    250405 * 
    251406 * When a plugin is activated, the action 'activate_PLUGINNAME' hook is 
    252407 * activated. In the name of this hook, PLUGINNAME is replaced with the name of 
    253408 * the plugin, including the optional subdirectory. For example, when the plugin 
    254409 * is located in <tt>wp-content/plugin/sampleplugin/sample.php</tt>, then the 
    255  * name of this hook will become 'activate_sampleplugin/sample.php'. 
     410 * name of this hook will become 'activate_sampleplugin/sample.php' 
    256411 * When the plugin consists of only one file and is (as by default) located at 
    257412 * <tt>wp-content/plugin/sample.php</tt> the name of this hook will be 
    258413 * 'activate_sample.php'. 
     414 * 
     415 * @package WordPress 
     416 * @subpackage Plugin 
     417 * @since 1.5 
     418 * 
    259419 * @param string $file The filename of the plugin including the path. 
    260420 * @param string $function the function hooked to the 'activate_PLUGIN' action. 
    261421 */ 
    … …  
    265425} 
    266426 
    267427/** 
     428 * { @internal register_deactivation_hook() }} 
     429 * @access private 
     430 * 
    268431 * Hook a function on a plugin deactivation action hook. 
    269432 * 
    270433 * When a plugin is deactivated, the action 'deactivate_PLUGINNAME' hook is 
    … …  
    275438 * When the plugin consists of only one file and is (as by default) located at 
    276439 * <tt>wp-content/plugin/sample.php</tt> the name of this hook will be 
    277440 * 'activate_sample.php'. 
     441 * 
     442 * @package WordPress 
     443 * @subpackage Plugin 
     444 * @since 2.0 
     445 * 
    278446 * @param string $file The filename of the plugin including the path. 
    279447 * @param string $function the function hooked to the 'activate_PLUGIN' action. 
    280448 */ 
    … …  
    284452} 
    285453 
    286454/** 
     455 * { @internal _wp_filter_build_unique_id() }} 
    287456 * @access private 
    288457 * 
    289  * _wp_filter_build_unique_id() - Build Unique ID for storage and retrieval 
     458 * Build Unique ID for storage and retrieval 
    290459 * 
    291  * This function is used to fix the issue where serialized, when used with  
    292  * classes that updated their properties, wouldn't be able to remove actions. 
     460 * @link http://trac.wordpress.org/ticket/3875 
    293461 * 
    294  * How it works is that it first checks if the $function parameter is a string 
    295  * and passes it through, untouched. Functions won't need to be changed, since 
    296  * there can only be one declared. 
    297  *  
    298  * The second type that will be passed through untouched, is for static methods 
    299  * in classes. They don't need to be changed since they are much like functions 
    300  * in that you can only call one of them. 
     462 * The old way to serialize the callback caused issues and this function is the 
     463 * solution. It works by checking for objects and creating an a new property in 
     464 * the class to keep track of the object and new objects of the same class that 
     465 * need to be added. 
    301466 * 
    302  * The main purpose of this function is for classes, which can have more than 
    303  * one declared and you want to add more than one hook for each one that is  
    304  * declared, or want to change properties internal of the class that you declared 
    305  * the hook. 
     467 * It also allows for the removal of actions and filters for objects after they 
     468 * change class properties. It is possible to include the property $wp_filter_id 
     469 * in your class and set it to "null" or a number to bypass the workaround. However 
     470 * this will prevent you from adding new classes and any new classes will overwrite 
     471 * the previous hook by the same class. 
    306472 * 
    307  * @global $wp_filter 
     473 * Functions and static method callbacks are just returned as strings and shouldn't 
     474 * have any speed penalty. 
     475 * 
     476 * @package WordPress 
     477 * @subpackage Plugin 
     478 * @since 2.2.3 
     479 * 
     480 * @global array $wp_filter Storage for all of the filters and actions 
    308481 * @param string $tag Used in counting how many hooks were applied 
    309482 * @param string|array $function Used for creating unique id 
    310483 * @param int $priority Used in counting how many hooks were applied 
    … …  
    315488        global $wp_filter; 
    316489 
    317490        // If function then just skip all of the tests and not overwrite the following. 
    318         // Static Calling 
    319491        if( is_string($function) ) 
    320492                return $function; 
    321493        // Object Class Calling 
    322494        else if(is_object($function[0]) ) 
    323495        { 
    324496                $obj_idx = get_class($function[0]).$function[1]; 
    325                 if( is_null($function[0]->wp_filter_id) ) { 
     497                if( is_null($function[0]->wp_filter_id) ) { // This should be instead of is_null() change to !isset() to fix notice 
    326498                        $count = count((array)$wp_filter[$tag][$priority]); 
    327499                        $function[0]->wp_filter_id = $count; 
    328500                        $obj_idx .= $count; 
    … …  
    331503                        $obj_idx .= $function[0]->wp_filter_id; 
    332504                return $obj_idx; 
    333505        } 
     506        // Static Calling 
    334507        else if( is_string($function[0]) ) 
    335508                return $function[0].$function[1]; 
    336509} 
    337510 
    338 ?> 
     511?> 
     512 No newline at end of file