|
1 <?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 * Any of the syntaxes explained in the PHP documentation for the |
|
11 * {@link http://us2.php.net/manual/en/language.pseudo-types.php#language.types.callback 'callback'} |
|
12 * type are valid. |
|
13 * |
|
14 * Also see the {@link http://codex.wordpress.org/Plugin_API Plugin API} for |
|
15 * more information and examples on how to use a lot of these functions. |
|
16 * |
|
17 * @package WordPress |
|
18 * @subpackage Plugin |
|
19 * @since 1.5 |
|
20 */ |
|
21 |
|
22 // Initialize the filter globals. |
|
23 global $wp_filter, $wp_actions, $merged_filters, $wp_current_filter; |
|
24 |
|
25 if ( ! isset( $wp_filter ) ) |
|
26 $wp_filter = array(); |
|
27 |
|
28 if ( ! isset( $wp_actions ) ) |
|
29 $wp_actions = array(); |
|
30 |
|
31 if ( ! isset( $merged_filters ) ) |
|
32 $merged_filters = array(); |
|
33 |
|
34 if ( ! isset( $wp_current_filter ) ) |
|
35 $wp_current_filter = array(); |
|
36 |
|
37 /** |
|
38 * Hooks a function or method to a specific filter action. |
|
39 * |
|
40 * WordPress offers filter hooks to allow plugins to modify |
|
41 * various types of internal data at runtime. |
|
42 * |
|
43 * A plugin can modify data by binding a callback to a filter hook. When the filter |
|
44 * is later applied, each bound callback is run in order of priority, and given |
|
45 * the opportunity to modify a value by returning a new value. |
|
46 * |
|
47 * The following example shows how a callback function is bound to a filter hook. |
|
48 * Note that $example is passed to the callback, (maybe) modified, then returned: |
|
49 * |
|
50 * <code> |
|
51 * function example_callback( $example ) { |
|
52 * // Maybe modify $example in some way |
|
53 * return $example; |
|
54 * } |
|
55 * add_filter( 'example_filter', 'example_callback' ); |
|
56 * </code> |
|
57 * |
|
58 * Since WordPress 1.5.1, bound callbacks can take as many arguments as are |
|
59 * passed as parameters in the corresponding apply_filters() call. The $accepted_args |
|
60 * parameter allows for calling functions only when the number of args match. |
|
61 * |
|
62 * <strong>Note:</strong> the function will return true whether or not the callback |
|
63 * is valid. It is up to you to take care. This is done for optimization purposes, |
|
64 * so everything is as quick as possible. |
|
65 * |
|
66 * @package WordPress |
|
67 * @subpackage Plugin |
|
68 * |
|
69 * @global array $wp_filter A multidimensional array of all hooks and the callbacks hooked to them. |
|
70 * @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. |
|
71 * |
|
72 * @since 0.71 |
|
73 * |
|
74 * @param string $tag The name of the filter to hook the $function_to_add callback to. |
|
75 * @param callback $function_to_add The callback to be run when the filter is applied. |
|
76 * @param int $priority (optional) The order in which the functions associated with a particular action are executed. 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. |
|
77 * Default 10. |
|
78 * @param int $accepted_args (optional) The number of arguments the function accepts. |
|
79 * Default 1. |
|
80 * @return boolean true |
|
81 */ |
|
82 function add_filter( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) { |
|
83 global $wp_filter, $merged_filters; |
|
84 |
|
85 $idx = _wp_filter_build_unique_id($tag, $function_to_add, $priority); |
|
86 $wp_filter[$tag][$priority][$idx] = array('function' => $function_to_add, 'accepted_args' => $accepted_args); |
|
87 unset( $merged_filters[ $tag ] ); |
|
88 return true; |
|
89 } |
|
90 |
|
91 /** |
|
92 * Check if any filter has been registered for a hook. |
|
93 * |
|
94 * @package WordPress |
|
95 * @subpackage Plugin |
|
96 * @since 2.5 |
|
97 * @global array $wp_filter Stores all of the filters |
|
98 * |
|
99 * @param string $tag The name of the filter hook. |
|
100 * @param callback $function_to_check optional. |
|
101 * @return mixed If $function_to_check is omitted, returns boolean for whether the hook has anything registered. |
|
102 * When checking a specific function, the priority of that hook is returned, or false if the function is not attached. |
|
103 * When using the $function_to_check argument, this function may return a non-boolean value that evaluates to false |
|
104 * (e.g.) 0, so use the === operator for testing the return value. |
|
105 */ |
|
106 function has_filter($tag, $function_to_check = false) { |
|
107 global $wp_filter; |
|
108 |
|
109 $has = !empty($wp_filter[$tag]); |
|
110 if ( false === $function_to_check || false == $has ) |
|
111 return $has; |
|
112 |
|
113 if ( !$idx = _wp_filter_build_unique_id($tag, $function_to_check, false) ) |
|
114 return false; |
|
115 |
|
116 foreach ( (array) array_keys($wp_filter[$tag]) as $priority ) { |
|
117 if ( isset($wp_filter[$tag][$priority][$idx]) ) |
|
118 return $priority; |
|
119 } |
|
120 |
|
121 return false; |
|
122 } |
|
123 |
|
124 /** |
|
125 * Call the functions added to a filter hook. |
|
126 * |
|
127 * The callback functions attached to filter hook $tag are invoked by calling |
|
128 * this function. This function can be used to create a new filter hook by |
|
129 * simply calling this function with the name of the new hook specified using |
|
130 * the $tag parameter. |
|
131 * |
|
132 * The function allows for additional arguments to be added and passed to hooks. |
|
133 * <code> |
|
134 * // Our filter callback function |
|
135 * function example_callback( $string, $arg1, $arg2 ) { |
|
136 * // (maybe) modify $string |
|
137 * return $string; |
|
138 * } |
|
139 * add_filter( 'example_filter', 'example_callback', 10, 3 ); |
|
140 * |
|
141 * // Apply the filters by calling the 'example_callback' function we |
|
142 * // "hooked" to 'example_filter' using the add_filter() function above. |
|
143 * // - 'example_filter' is the filter hook $tag |
|
144 * // - 'filter me' is the value being filtered |
|
145 * // - $arg1 and $arg2 are the additional arguments passed to the callback. |
|
146 * $value = apply_filters( 'example_filter', 'filter me', $arg1, $arg2 ); |
|
147 * </code> |
|
148 * |
|
149 * @package WordPress |
|
150 * @subpackage Plugin |
|
151 * |
|
152 * @global array $wp_filter Stores all of the filters |
|
153 * @global array $merged_filters Merges the filter hooks using this function. |
|
154 * @global array $wp_current_filter stores the list of current filters with the current one last |
|
155 * |
|
156 * @since 0.71 |
|
157 * |
|
158 * @param string $tag The name of the filter hook. |
|
159 * @param mixed $value The value on which the filters hooked to <tt>$tag</tt> are applied on. |
|
160 * @param mixed $var Additional variables passed to the functions hooked to <tt>$tag</tt>. |
|
161 * @return mixed The filtered value after all hooked functions are applied to it. |
|
162 */ |
|
163 function apply_filters( $tag, $value ) { |
|
164 global $wp_filter, $merged_filters, $wp_current_filter; |
|
165 |
|
166 $args = array(); |
|
167 |
|
168 // Do 'all' actions first |
|
169 if ( isset($wp_filter['all']) ) { |
|
170 $wp_current_filter[] = $tag; |
|
171 $args = func_get_args(); |
|
172 _wp_call_all_hook($args); |
|
173 } |
|
174 |
|
175 if ( !isset($wp_filter[$tag]) ) { |
|
176 if ( isset($wp_filter['all']) ) |
|
177 array_pop($wp_current_filter); |
|
178 return $value; |
|
179 } |
|
180 |
|
181 if ( !isset($wp_filter['all']) ) |
|
182 $wp_current_filter[] = $tag; |
|
183 |
|
184 // Sort |
|
185 if ( !isset( $merged_filters[ $tag ] ) ) { |
|
186 ksort($wp_filter[$tag]); |
|
187 $merged_filters[ $tag ] = true; |
|
188 } |
|
189 |
|
190 reset( $wp_filter[ $tag ] ); |
|
191 |
|
192 if ( empty($args) ) |
|
193 $args = func_get_args(); |
|
194 |
|
195 do { |
|
196 foreach( (array) current($wp_filter[$tag]) as $the_ ) |
|
197 if ( !is_null($the_['function']) ){ |
|
198 $args[1] = $value; |
|
199 $value = call_user_func_array($the_['function'], array_slice($args, 1, (int) $the_['accepted_args'])); |
|
200 } |
|
201 |
|
202 } while ( next($wp_filter[$tag]) !== false ); |
|
203 |
|
204 array_pop( $wp_current_filter ); |
|
205 |
|
206 return $value; |
|
207 } |
|
208 |
|
209 /** |
|
210 * Execute functions hooked on a specific filter hook, specifying arguments in an array. |
|
211 * |
|
212 * @see apply_filters() This function is identical, but the arguments passed to the |
|
213 * functions hooked to <tt>$tag</tt> are supplied using an array. |
|
214 * |
|
215 * @package WordPress |
|
216 * @subpackage Plugin |
|
217 * @since 3.0.0 |
|
218 * @global array $wp_filter Stores all of the filters |
|
219 * @global array $merged_filters Merges the filter hooks using this function. |
|
220 * @global array $wp_current_filter stores the list of current filters with the current one last |
|
221 * |
|
222 * @param string $tag The name of the filter hook. |
|
223 * @param array $args The arguments supplied to the functions hooked to <tt>$tag</tt> |
|
224 * @return mixed The filtered value after all hooked functions are applied to it. |
|
225 */ |
|
226 function apply_filters_ref_array($tag, $args) { |
|
227 global $wp_filter, $merged_filters, $wp_current_filter; |
|
228 |
|
229 // Do 'all' actions first |
|
230 if ( isset($wp_filter['all']) ) { |
|
231 $wp_current_filter[] = $tag; |
|
232 $all_args = func_get_args(); |
|
233 _wp_call_all_hook($all_args); |
|
234 } |
|
235 |
|
236 if ( !isset($wp_filter[$tag]) ) { |
|
237 if ( isset($wp_filter['all']) ) |
|
238 array_pop($wp_current_filter); |
|
239 return $args[0]; |
|
240 } |
|
241 |
|
242 if ( !isset($wp_filter['all']) ) |
|
243 $wp_current_filter[] = $tag; |
|
244 |
|
245 // Sort |
|
246 if ( !isset( $merged_filters[ $tag ] ) ) { |
|
247 ksort($wp_filter[$tag]); |
|
248 $merged_filters[ $tag ] = true; |
|
249 } |
|
250 |
|
251 reset( $wp_filter[ $tag ] ); |
|
252 |
|
253 do { |
|
254 foreach( (array) current($wp_filter[$tag]) as $the_ ) |
|
255 if ( !is_null($the_['function']) ) |
|
256 $args[0] = call_user_func_array($the_['function'], array_slice($args, 0, (int) $the_['accepted_args'])); |
|
257 |
|
258 } while ( next($wp_filter[$tag]) !== false ); |
|
259 |
|
260 array_pop( $wp_current_filter ); |
|
261 |
|
262 return $args[0]; |
|
263 } |
|
264 |
|
265 /** |
|
266 * Removes a function from a specified filter hook. |
|
267 * |
|
268 * This function removes a function attached to a specified filter hook. This |
|
269 * method can be used to remove default functions attached to a specific filter |
|
270 * hook and possibly replace them with a substitute. |
|
271 * |
|
272 * To remove a hook, the $function_to_remove and $priority arguments must match |
|
273 * when the hook was added. This goes for both filters and actions. No warning |
|
274 * will be given on removal failure. |
|
275 * |
|
276 * @package WordPress |
|
277 * @subpackage Plugin |
|
278 * @since 1.2 |
|
279 * |
|
280 * @param string $tag The filter hook to which the function to be removed is hooked. |
|
281 * @param callback $function_to_remove The name of the function which should be removed. |
|
282 * @param int $priority optional. The priority of the function (default: 10). |
|
283 * @param int $accepted_args optional. The number of arguments the function accepts (default: 1). |
|
284 * @return boolean Whether the function existed before it was removed. |
|
285 */ |
|
286 function remove_filter( $tag, $function_to_remove, $priority = 10 ) { |
|
287 $function_to_remove = _wp_filter_build_unique_id($tag, $function_to_remove, $priority); |
|
288 |
|
289 $r = isset($GLOBALS['wp_filter'][$tag][$priority][$function_to_remove]); |
|
290 |
|
291 if ( true === $r) { |
|
292 unset($GLOBALS['wp_filter'][$tag][$priority][$function_to_remove]); |
|
293 if ( empty($GLOBALS['wp_filter'][$tag][$priority]) ) |
|
294 unset($GLOBALS['wp_filter'][$tag][$priority]); |
|
295 unset($GLOBALS['merged_filters'][$tag]); |
|
296 } |
|
297 |
|
298 return $r; |
|
299 } |
|
300 |
|
301 /** |
|
302 * Remove all of the hooks from a filter. |
|
303 * |
|
304 * @since 2.7 |
|
305 * |
|
306 * @param string $tag The filter to remove hooks from. |
|
307 * @param int $priority The priority number to remove. |
|
308 * @return bool True when finished. |
|
309 */ |
|
310 function remove_all_filters($tag, $priority = false) { |
|
311 global $wp_filter, $merged_filters; |
|
312 |
|
313 if( isset($wp_filter[$tag]) ) { |
|
314 if( false !== $priority && isset($wp_filter[$tag][$priority]) ) |
|
315 unset($wp_filter[$tag][$priority]); |
|
316 else |
|
317 unset($wp_filter[$tag]); |
|
318 } |
|
319 |
|
320 if( isset($merged_filters[$tag]) ) |
|
321 unset($merged_filters[$tag]); |
|
322 |
|
323 return true; |
|
324 } |
|
325 |
|
326 /** |
|
327 * Retrieve the name of the current filter or action. |
|
328 * |
|
329 * @package WordPress |
|
330 * @subpackage Plugin |
|
331 * @since 2.5 |
|
332 * |
|
333 * @return string Hook name of the current filter or action. |
|
334 */ |
|
335 function current_filter() { |
|
336 global $wp_current_filter; |
|
337 return end( $wp_current_filter ); |
|
338 } |
|
339 |
|
340 /** |
|
341 * Hooks a function on to a specific action. |
|
342 * |
|
343 * Actions are the hooks that the WordPress core launches at specific points |
|
344 * during execution, or when specific events occur. Plugins can specify that |
|
345 * one or more of its PHP functions are executed at these points, using the |
|
346 * Action API. |
|
347 * |
|
348 * @uses add_filter() Adds an action. Parameter list and functionality are the same. |
|
349 * |
|
350 * @package WordPress |
|
351 * @subpackage Plugin |
|
352 * @since 1.2 |
|
353 * |
|
354 * @param string $tag The name of the action to which the $function_to_add is hooked. |
|
355 * @param callback $function_to_add The name of the function you wish to be called. |
|
356 * @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. |
|
357 * @param int $accepted_args optional. The number of arguments the function accept (default 1). |
|
358 */ |
|
359 function add_action($tag, $function_to_add, $priority = 10, $accepted_args = 1) { |
|
360 return add_filter($tag, $function_to_add, $priority, $accepted_args); |
|
361 } |
|
362 |
|
363 /** |
|
364 * Execute functions hooked on a specific action hook. |
|
365 * |
|
366 * This function invokes all functions attached to action hook $tag. It is |
|
367 * possible to create new action hooks by simply calling this function, |
|
368 * specifying the name of the new hook using the <tt>$tag</tt> parameter. |
|
369 * |
|
370 * You can pass extra arguments to the hooks, much like you can with |
|
371 * apply_filters(). |
|
372 * |
|
373 * @see apply_filters() This function works similar with the exception that |
|
374 * nothing is returned and only the functions or methods are called. |
|
375 * |
|
376 * @package WordPress |
|
377 * @subpackage Plugin |
|
378 * @since 1.2 |
|
379 * @global array $wp_filter Stores all of the filters |
|
380 * @global array $wp_actions Increments the amount of times action was triggered. |
|
381 * |
|
382 * @param string $tag The name of the action to be executed. |
|
383 * @param mixed $arg,... Optional additional arguments which are passed on to the functions hooked to the action. |
|
384 * @return null Will return null if $tag does not exist in $wp_filter array |
|
385 */ |
|
386 function do_action($tag, $arg = '') { |
|
387 global $wp_filter, $wp_actions, $merged_filters, $wp_current_filter; |
|
388 |
|
389 if ( ! isset($wp_actions[$tag]) ) |
|
390 $wp_actions[$tag] = 1; |
|
391 else |
|
392 ++$wp_actions[$tag]; |
|
393 |
|
394 // Do 'all' actions first |
|
395 if ( isset($wp_filter['all']) ) { |
|
396 $wp_current_filter[] = $tag; |
|
397 $all_args = func_get_args(); |
|
398 _wp_call_all_hook($all_args); |
|
399 } |
|
400 |
|
401 if ( !isset($wp_filter[$tag]) ) { |
|
402 if ( isset($wp_filter['all']) ) |
|
403 array_pop($wp_current_filter); |
|
404 return; |
|
405 } |
|
406 |
|
407 if ( !isset($wp_filter['all']) ) |
|
408 $wp_current_filter[] = $tag; |
|
409 |
|
410 $args = array(); |
|
411 if ( is_array($arg) && 1 == count($arg) && isset($arg[0]) && is_object($arg[0]) ) // array(&$this) |
|
412 $args[] =& $arg[0]; |
|
413 else |
|
414 $args[] = $arg; |
|
415 for ( $a = 2; $a < func_num_args(); $a++ ) |
|
416 $args[] = func_get_arg($a); |
|
417 |
|
418 // Sort |
|
419 if ( !isset( $merged_filters[ $tag ] ) ) { |
|
420 ksort($wp_filter[$tag]); |
|
421 $merged_filters[ $tag ] = true; |
|
422 } |
|
423 |
|
424 reset( $wp_filter[ $tag ] ); |
|
425 |
|
426 do { |
|
427 foreach ( (array) current($wp_filter[$tag]) as $the_ ) |
|
428 if ( !is_null($the_['function']) ) |
|
429 call_user_func_array($the_['function'], array_slice($args, 0, (int) $the_['accepted_args'])); |
|
430 |
|
431 } while ( next($wp_filter[$tag]) !== false ); |
|
432 |
|
433 array_pop($wp_current_filter); |
|
434 } |
|
435 |
|
436 /** |
|
437 * Retrieve the number of times an action is fired. |
|
438 * |
|
439 * @package WordPress |
|
440 * @subpackage Plugin |
|
441 * @since 2.1 |
|
442 * @global array $wp_actions Increments the amount of times action was triggered. |
|
443 * |
|
444 * @param string $tag The name of the action hook. |
|
445 * @return int The number of times action hook <tt>$tag</tt> is fired |
|
446 */ |
|
447 function did_action($tag) { |
|
448 global $wp_actions; |
|
449 |
|
450 if ( ! isset( $wp_actions[ $tag ] ) ) |
|
451 return 0; |
|
452 |
|
453 return $wp_actions[$tag]; |
|
454 } |
|
455 |
|
456 /** |
|
457 * Execute functions hooked on a specific action hook, specifying arguments in an array. |
|
458 * |
|
459 * @see do_action() This function is identical, but the arguments passed to the |
|
460 * functions hooked to <tt>$tag</tt> are supplied using an array. |
|
461 * |
|
462 * @package WordPress |
|
463 * @subpackage Plugin |
|
464 * @since 2.1 |
|
465 * @global array $wp_filter Stores all of the filters |
|
466 * @global array $wp_actions Increments the amount of times action was triggered. |
|
467 * |
|
468 * @param string $tag The name of the action to be executed. |
|
469 * @param array $args The arguments supplied to the functions hooked to <tt>$tag</tt> |
|
470 * @return null Will return null if $tag does not exist in $wp_filter array |
|
471 */ |
|
472 function do_action_ref_array($tag, $args) { |
|
473 global $wp_filter, $wp_actions, $merged_filters, $wp_current_filter; |
|
474 |
|
475 if ( ! isset($wp_actions[$tag]) ) |
|
476 $wp_actions[$tag] = 1; |
|
477 else |
|
478 ++$wp_actions[$tag]; |
|
479 |
|
480 // Do 'all' actions first |
|
481 if ( isset($wp_filter['all']) ) { |
|
482 $wp_current_filter[] = $tag; |
|
483 $all_args = func_get_args(); |
|
484 _wp_call_all_hook($all_args); |
|
485 } |
|
486 |
|
487 if ( !isset($wp_filter[$tag]) ) { |
|
488 if ( isset($wp_filter['all']) ) |
|
489 array_pop($wp_current_filter); |
|
490 return; |
|
491 } |
|
492 |
|
493 if ( !isset($wp_filter['all']) ) |
|
494 $wp_current_filter[] = $tag; |
|
495 |
|
496 // Sort |
|
497 if ( !isset( $merged_filters[ $tag ] ) ) { |
|
498 ksort($wp_filter[$tag]); |
|
499 $merged_filters[ $tag ] = true; |
|
500 } |
|
501 |
|
502 reset( $wp_filter[ $tag ] ); |
|
503 |
|
504 do { |
|
505 foreach( (array) current($wp_filter[$tag]) as $the_ ) |
|
506 if ( !is_null($the_['function']) ) |
|
507 call_user_func_array($the_['function'], array_slice($args, 0, (int) $the_['accepted_args'])); |
|
508 |
|
509 } while ( next($wp_filter[$tag]) !== false ); |
|
510 |
|
511 array_pop($wp_current_filter); |
|
512 } |
|
513 |
|
514 /** |
|
515 * Check if any action has been registered for a hook. |
|
516 * |
|
517 * @package WordPress |
|
518 * @subpackage Plugin |
|
519 * @since 2.5 |
|
520 * @see has_filter() has_action() is an alias of has_filter(). |
|
521 * |
|
522 * @param string $tag The name of the action hook. |
|
523 * @param callback $function_to_check optional. |
|
524 * @return mixed If $function_to_check is omitted, returns boolean for whether the hook has anything registered. |
|
525 * When checking a specific function, the priority of that hook is returned, or false if the function is not attached. |
|
526 * When using the $function_to_check argument, this function may return a non-boolean value that evaluates to false |
|
527 * (e.g.) 0, so use the === operator for testing the return value. |
|
528 */ |
|
529 function has_action($tag, $function_to_check = false) { |
|
530 return has_filter($tag, $function_to_check); |
|
531 } |
|
532 |
|
533 /** |
|
534 * Removes a function from a specified action hook. |
|
535 * |
|
536 * This function removes a function attached to a specified action hook. This |
|
537 * method can be used to remove default functions attached to a specific filter |
|
538 * hook and possibly replace them with a substitute. |
|
539 * |
|
540 * @package WordPress |
|
541 * @subpackage Plugin |
|
542 * @since 1.2 |
|
543 * |
|
544 * @param string $tag The action hook to which the function to be removed is hooked. |
|
545 * @param callback $function_to_remove The name of the function which should be removed. |
|
546 * @param int $priority optional The priority of the function (default: 10). |
|
547 * @return boolean Whether the function is removed. |
|
548 */ |
|
549 function remove_action( $tag, $function_to_remove, $priority = 10 ) { |
|
550 return remove_filter( $tag, $function_to_remove, $priority ); |
|
551 } |
|
552 |
|
553 /** |
|
554 * Remove all of the hooks from an action. |
|
555 * |
|
556 * @since 2.7 |
|
557 * |
|
558 * @param string $tag The action to remove hooks from. |
|
559 * @param int $priority The priority number to remove them from. |
|
560 * @return bool True when finished. |
|
561 */ |
|
562 function remove_all_actions($tag, $priority = false) { |
|
563 return remove_all_filters($tag, $priority); |
|
564 } |
|
565 |
|
566 // |
|
567 // Functions for handling plugins. |
|
568 // |
|
569 |
|
570 /** |
|
571 * Gets the basename of a plugin. |
|
572 * |
|
573 * This method extracts the name of a plugin from its filename. |
|
574 * |
|
575 * @package WordPress |
|
576 * @subpackage Plugin |
|
577 * @since 1.5 |
|
578 * |
|
579 * @access private |
|
580 * |
|
581 * @param string $file The filename of plugin. |
|
582 * @return string The name of a plugin. |
|
583 * @uses WP_PLUGIN_DIR |
|
584 */ |
|
585 function plugin_basename($file) { |
|
586 $file = str_replace('\\','/',$file); // sanitize for Win32 installs |
|
587 $file = preg_replace('|/+|','/', $file); // remove any duplicate slash |
|
588 $plugin_dir = str_replace('\\','/',WP_PLUGIN_DIR); // sanitize for Win32 installs |
|
589 $plugin_dir = preg_replace('|/+|','/', $plugin_dir); // remove any duplicate slash |
|
590 $mu_plugin_dir = str_replace('\\','/',WPMU_PLUGIN_DIR); // sanitize for Win32 installs |
|
591 $mu_plugin_dir = preg_replace('|/+|','/', $mu_plugin_dir); // remove any duplicate slash |
|
592 $file = preg_replace('#^' . preg_quote($plugin_dir, '#') . '/|^' . preg_quote($mu_plugin_dir, '#') . '/#','',$file); // get relative path from plugins dir |
|
593 $file = trim($file, '/'); |
|
594 return $file; |
|
595 } |
|
596 |
|
597 /** |
|
598 * Gets the filesystem directory path (with trailing slash) for the plugin __FILE__ passed in |
|
599 * @package WordPress |
|
600 * @subpackage Plugin |
|
601 * @since 2.8 |
|
602 * |
|
603 * @param string $file The filename of the plugin (__FILE__) |
|
604 * @return string the filesystem path of the directory that contains the plugin |
|
605 */ |
|
606 function plugin_dir_path( $file ) { |
|
607 return trailingslashit( dirname( $file ) ); |
|
608 } |
|
609 |
|
610 /** |
|
611 * Gets the URL directory path (with trailing slash) for the plugin __FILE__ passed in |
|
612 * @package WordPress |
|
613 * @subpackage Plugin |
|
614 * @since 2.8 |
|
615 * |
|
616 * @param string $file The filename of the plugin (__FILE__) |
|
617 * @return string the URL path of the directory that contains the plugin |
|
618 */ |
|
619 function plugin_dir_url( $file ) { |
|
620 return trailingslashit( plugins_url( '', $file ) ); |
|
621 } |
|
622 |
|
623 /** |
|
624 * Set the activation hook for a plugin. |
|
625 * |
|
626 * When a plugin is activated, the action 'activate_PLUGINNAME' hook is |
|
627 * called. In the name of this hook, PLUGINNAME is replaced with the name |
|
628 * of the plugin, including the optional subdirectory. For example, when the |
|
629 * plugin is located in wp-content/plugins/sampleplugin/sample.php, then |
|
630 * the name of this hook will become 'activate_sampleplugin/sample.php'. |
|
631 * |
|
632 * When the plugin consists of only one file and is (as by default) located at |
|
633 * wp-content/plugins/sample.php the name of this hook will be |
|
634 * 'activate_sample.php'. |
|
635 * |
|
636 * @package WordPress |
|
637 * @subpackage Plugin |
|
638 * @since 2.0 |
|
639 * |
|
640 * @param string $file The filename of the plugin including the path. |
|
641 * @param callback $function the function hooked to the 'activate_PLUGIN' action. |
|
642 */ |
|
643 function register_activation_hook($file, $function) { |
|
644 $file = plugin_basename($file); |
|
645 add_action('activate_' . $file, $function); |
|
646 } |
|
647 |
|
648 /** |
|
649 * Set the deactivation hook for a plugin. |
|
650 * |
|
651 * When a plugin is deactivated, the action 'deactivate_PLUGINNAME' hook is |
|
652 * called. In the name of this hook, PLUGINNAME is replaced with the name |
|
653 * of the plugin, including the optional subdirectory. For example, when the |
|
654 * plugin is located in wp-content/plugins/sampleplugin/sample.php, then |
|
655 * the name of this hook will become 'deactivate_sampleplugin/sample.php'. |
|
656 * |
|
657 * When the plugin consists of only one file and is (as by default) located at |
|
658 * wp-content/plugins/sample.php the name of this hook will be |
|
659 * 'deactivate_sample.php'. |
|
660 * |
|
661 * @package WordPress |
|
662 * @subpackage Plugin |
|
663 * @since 2.0 |
|
664 * |
|
665 * @param string $file The filename of the plugin including the path. |
|
666 * @param callback $function the function hooked to the 'deactivate_PLUGIN' action. |
|
667 */ |
|
668 function register_deactivation_hook($file, $function) { |
|
669 $file = plugin_basename($file); |
|
670 add_action('deactivate_' . $file, $function); |
|
671 } |
|
672 |
|
673 /** |
|
674 * Set the uninstallation hook for a plugin. |
|
675 * |
|
676 * Registers the uninstall hook that will be called when the user clicks on the |
|
677 * uninstall link that calls for the plugin to uninstall itself. The link won't |
|
678 * be active unless the plugin hooks into the action. |
|
679 * |
|
680 * The plugin should not run arbitrary code outside of functions, when |
|
681 * registering the uninstall hook. In order to run using the hook, the plugin |
|
682 * will have to be included, which means that any code laying outside of a |
|
683 * function will be run during the uninstall process. The plugin should not |
|
684 * hinder the uninstall process. |
|
685 * |
|
686 * If the plugin can not be written without running code within the plugin, then |
|
687 * the plugin should create a file named 'uninstall.php' in the base plugin |
|
688 * folder. This file will be called, if it exists, during the uninstall process |
|
689 * bypassing the uninstall hook. The plugin, when using the 'uninstall.php' |
|
690 * should always check for the 'WP_UNINSTALL_PLUGIN' constant, before |
|
691 * executing. |
|
692 * |
|
693 * @since 2.7 |
|
694 * |
|
695 * @param string $file |
|
696 * @param callback $callback The callback to run when the hook is called. Must be a static method or function. |
|
697 */ |
|
698 function register_uninstall_hook( $file, $callback ) { |
|
699 if ( is_array( $callback ) && is_object( $callback[0] ) ) { |
|
700 _doing_it_wrong( __FUNCTION__, __( 'Only a static class method or function can be used in an uninstall hook.' ), '3.1' ); |
|
701 return; |
|
702 } |
|
703 |
|
704 // The option should not be autoloaded, because it is not needed in most |
|
705 // cases. Emphasis should be put on using the 'uninstall.php' way of |
|
706 // uninstalling the plugin. |
|
707 $uninstallable_plugins = (array) get_option('uninstall_plugins'); |
|
708 $uninstallable_plugins[plugin_basename($file)] = $callback; |
|
709 update_option('uninstall_plugins', $uninstallable_plugins); |
|
710 } |
|
711 |
|
712 /** |
|
713 * Calls the 'all' hook, which will process the functions hooked into it. |
|
714 * |
|
715 * The 'all' hook passes all of the arguments or parameters that were used for |
|
716 * the hook, which this function was called for. |
|
717 * |
|
718 * This function is used internally for apply_filters(), do_action(), and |
|
719 * do_action_ref_array() and is not meant to be used from outside those |
|
720 * functions. This function does not check for the existence of the all hook, so |
|
721 * it will fail unless the all hook exists prior to this function call. |
|
722 * |
|
723 * @package WordPress |
|
724 * @subpackage Plugin |
|
725 * @since 2.5 |
|
726 * @access private |
|
727 * |
|
728 * @uses $wp_filter Used to process all of the functions in the 'all' hook |
|
729 * |
|
730 * @param array $args The collected parameters from the hook that was called. |
|
731 */ |
|
732 function _wp_call_all_hook($args) { |
|
733 global $wp_filter; |
|
734 |
|
735 reset( $wp_filter['all'] ); |
|
736 do { |
|
737 foreach( (array) current($wp_filter['all']) as $the_ ) |
|
738 if ( !is_null($the_['function']) ) |
|
739 call_user_func_array($the_['function'], $args); |
|
740 |
|
741 } while ( next($wp_filter['all']) !== false ); |
|
742 } |
|
743 |
|
744 /** |
|
745 * Build Unique ID for storage and retrieval. |
|
746 * |
|
747 * The old way to serialize the callback caused issues and this function is the |
|
748 * solution. It works by checking for objects and creating an a new property in |
|
749 * the class to keep track of the object and new objects of the same class that |
|
750 * need to be added. |
|
751 * |
|
752 * It also allows for the removal of actions and filters for objects after they |
|
753 * change class properties. It is possible to include the property $wp_filter_id |
|
754 * in your class and set it to "null" or a number to bypass the workaround. |
|
755 * However this will prevent you from adding new classes and any new classes |
|
756 * will overwrite the previous hook by the same class. |
|
757 * |
|
758 * Functions and static method callbacks are just returned as strings and |
|
759 * shouldn't have any speed penalty. |
|
760 * |
|
761 * @package WordPress |
|
762 * @subpackage Plugin |
|
763 * @access private |
|
764 * @since 2.2.3 |
|
765 * @link http://trac.wordpress.org/ticket/3875 |
|
766 * |
|
767 * @global array $wp_filter Storage for all of the filters and actions |
|
768 * @param string $tag Used in counting how many hooks were applied |
|
769 * @param callback $function Used for creating unique id |
|
770 * @param int|bool $priority Used in counting how many hooks were applied. If === false and $function is an object reference, we return the unique id only if it already has one, false otherwise. |
|
771 * @return string|bool Unique ID for usage as array key or false if $priority === false and $function is an object reference, and it does not already have a unique id. |
|
772 */ |
|
773 function _wp_filter_build_unique_id($tag, $function, $priority) { |
|
774 global $wp_filter; |
|
775 static $filter_id_count = 0; |
|
776 |
|
777 if ( is_string($function) ) |
|
778 return $function; |
|
779 |
|
780 if ( is_object($function) ) { |
|
781 // Closures are currently implemented as objects |
|
782 $function = array( $function, '' ); |
|
783 } else { |
|
784 $function = (array) $function; |
|
785 } |
|
786 |
|
787 if (is_object($function[0]) ) { |
|
788 // Object Class Calling |
|
789 if ( function_exists('spl_object_hash') ) { |
|
790 return spl_object_hash($function[0]) . $function[1]; |
|
791 } else { |
|
792 $obj_idx = get_class($function[0]).$function[1]; |
|
793 if ( !isset($function[0]->wp_filter_id) ) { |
|
794 if ( false === $priority ) |
|
795 return false; |
|
796 $obj_idx .= isset($wp_filter[$tag][$priority]) ? count((array)$wp_filter[$tag][$priority]) : $filter_id_count; |
|
797 $function[0]->wp_filter_id = $filter_id_count; |
|
798 ++$filter_id_count; |
|
799 } else { |
|
800 $obj_idx .= $function[0]->wp_filter_id; |
|
801 } |
|
802 |
|
803 return $obj_idx; |
|
804 } |
|
805 } else if ( is_string($function[0]) ) { |
|
806 // Static Calling |
|
807 return $function[0] . '::' . $function[1]; |
|
808 } |
|
809 } |