← Back to branch summary

~canonical-sysadmins/wordpress/4.7.2

« back to all changes in this revision

Viewing changes to wp-includes/plugin.php

  • Committer: Jacek Nykis
  • Date: 2015-01-05 16:17:05 UTC
  • Revision ID: jacek.nykis@canonical.com-20150105161705-w544l1h5mcg7u4w9
Initial commit

Show diffs side-by-side

added added

removed removed

Lines of Context:
wp-includes/plugin.php
 
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.0
 
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
 * Hook 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
 * @since 0.71
 
67
 *
 
68
 * @global array $wp_filter      A multidimensional array of all hooks and the callbacks hooked to them.
 
69
 * @global array $merged_filters Tracks the tags that need to be merged for later. If the hook is added,
 
70
 *                               it doesn't need to run through that process.
 
71
 *
 
72
 * @param string   $tag             The name of the filter to hook the $function_to_add callback to.
 
73
 * @param callback $function_to_add The callback to be run when the filter is applied.
 
74
 * @param int      $priority        Optional. Used to specify the order in which the functions
 
75
 *                                  associated with a particular action are executed. Default 10.
 
76
 *                                  Lower numbers correspond with earlier execution,
 
77
 *                                  and functions with the same priority are executed
 
78
 *                                  in the order in which they were added to the action.
 
79
 * @param int      $accepted_args   Optional. The number of arguments the function accepts. 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
 * @since 2.5.0
 
95
 *
 
96
 * @global array $wp_filter Stores all of the filters.
 
97
 *
 
98
 * @param string        $tag               The name of the filter hook.
 
99
 * @param callback|bool $function_to_check Optional. The callback to check for. Default false.
 
100
 * @return bool|int If $function_to_check is omitted, returns boolean for whether the hook has
 
101
 *                  anything registered. When checking a specific function, the priority of that
 
102
 *                  hook is returned, or false if the function is not attached. When using the
 
103
 *                  $function_to_check argument, this function may return a non-boolean value
 
104
 *                  that evaluates to false (e.g.) 0, so use the === operator for testing the
 
105
 *                  return value.
 
106
 */
 
107
function has_filter($tag, $function_to_check = false) {
 
108
        // Don't reset the internal array pointer
 
109
        $wp_filter = $GLOBALS['wp_filter'];
 
110
 
 
111
        $has = ! empty( $wp_filter[ $tag ] );
 
112
 
 
113
        // Make sure at least one priority has a filter callback
 
114
        if ( $has ) {
 
115
                $exists = false;
 
116
                foreach ( $wp_filter[ $tag ] as $callbacks ) {
 
117
                        if ( ! empty( $callbacks ) ) {
 
118
                                $exists = true;
 
119
                                break;
 
120
                        }
 
121
                }
 
122
 
 
123
                if ( ! $exists ) {
 
124
                        $has = false;
 
125
                }
 
126
        }
 
127
 
 
128
        if ( false === $function_to_check || false == $has )
 
129
                return $has;
 
130
 
 
131
        if ( !$idx = _wp_filter_build_unique_id($tag, $function_to_check, false) )
 
132
                return false;
 
133
 
 
134
        foreach ( (array) array_keys($wp_filter[$tag]) as $priority ) {
 
135
                if ( isset($wp_filter[$tag][$priority][$idx]) )
 
136
                        return $priority;
 
137
        }
 
138
 
 
139
        return false;
 
140
}
 
141
 
 
142
/**
 
143
 * Call the functions added to a filter hook.
 
144
 *
 
145
 * The callback functions attached to filter hook $tag are invoked by calling
 
146
 * this function. This function can be used to create a new filter hook by
 
147
 * simply calling this function with the name of the new hook specified using
 
148
 * the $tag parameter.
 
149
 *
 
150
 * The function allows for additional arguments to be added and passed to hooks.
 
151
 * <code>
 
152
 * // Our filter callback function
 
153
 * function example_callback( $string, $arg1, $arg2 ) {
 
154
 *      // (maybe) modify $string
 
155
 *      return $string;
 
156
 * }
 
157
 * add_filter( 'example_filter', 'example_callback', 10, 3 );
 
158
 *
 
159
 * // Apply the filters by calling the 'example_callback' function we
 
160
 * // "hooked" to 'example_filter' using the add_filter() function above.
 
161
 * // - 'example_filter' is the filter hook $tag
 
162
 * // - 'filter me' is the value being filtered
 
163
 * // - $arg1 and $arg2 are the additional arguments passed to the callback.
 
164
 * $value = apply_filters( 'example_filter', 'filter me', $arg1, $arg2 );
 
165
 * </code>
 
166
 *
 
167
 * @since 0.71
 
168
 *
 
169
 * @global array $wp_filter         Stores all of the filters.
 
170
 * @global array $merged_filters    Merges the filter hooks using this function.
 
171
 * @global array $wp_current_filter Stores the list of current filters with the current one last.
 
172
 *
 
173
 * @param string $tag   The name of the filter hook.
 
174
 * @param mixed  $value The value on which the filters hooked to <tt>$tag</tt> are applied on.
 
175
 * @param mixed  $var   Additional variables passed to the functions hooked to <tt>$tag</tt>.
 
176
 * @return mixed The filtered value after all hooked functions are applied to it.
 
177
 */
 
178
function apply_filters( $tag, $value ) {
 
179
        global $wp_filter, $merged_filters, $wp_current_filter;
 
180
 
 
181
        $args = array();
 
182
 
 
183
        // Do 'all' actions first.
 
184
        if ( isset($wp_filter['all']) ) {
 
185
                $wp_current_filter[] = $tag;
 
186
                $args = func_get_args();
 
187
                _wp_call_all_hook($args);
 
188
        }
 
189
 
 
190
        if ( !isset($wp_filter[$tag]) ) {
 
191
                if ( isset($wp_filter['all']) )
 
192
                        array_pop($wp_current_filter);
 
193
                return $value;
 
194
        }
 
195
 
 
196
        if ( !isset($wp_filter['all']) )
 
197
                $wp_current_filter[] = $tag;
 
198
 
 
199
        // Sort.
 
200
        if ( !isset( $merged_filters[ $tag ] ) ) {
 
201
                ksort($wp_filter[$tag]);
 
202
                $merged_filters[ $tag ] = true;
 
203
        }
 
204
 
 
205
        reset( $wp_filter[ $tag ] );
 
206
 
 
207
        if ( empty($args) )
 
208
                $args = func_get_args();
 
209
 
 
210
        do {
 
211
                foreach( (array) current($wp_filter[$tag]) as $the_ )
 
212
                        if ( !is_null($the_['function']) ){
 
213
                                $args[1] = $value;
 
214
                                $value = call_user_func_array($the_['function'], array_slice($args, 1, (int) $the_['accepted_args']));
 
215
                        }
 
216
 
 
217
        } while ( next($wp_filter[$tag]) !== false );
 
218
 
 
219
        array_pop( $wp_current_filter );
 
220
 
 
221
        return $value;
 
222
}
 
223
 
 
224
/**
 
225
 * Execute functions hooked on a specific filter hook, specifying arguments in an array.
 
226
 *
 
227
 * @see apply_filters() This function is identical, but the arguments passed to the
 
228
 * functions hooked to <tt>$tag</tt> are supplied using an array.
 
229
 *
 
230
 * @since 3.0.0
 
231
 *
 
232
 * @global array $wp_filter         Stores all of the filters
 
233
 * @global array $merged_filters    Merges the filter hooks using this function.
 
234
 * @global array $wp_current_filter Stores the list of current filters with the current one last
 
235
 *
 
236
 * @param string $tag  The name of the filter hook.
 
237
 * @param array  $args The arguments supplied to the functions hooked to $tag.
 
238
 * @return mixed The filtered value after all hooked functions are applied to it.
 
239
 */
 
240
function apply_filters_ref_array($tag, $args) {
 
241
        global $wp_filter, $merged_filters, $wp_current_filter;
 
242
 
 
243
        // Do 'all' actions first
 
244
        if ( isset($wp_filter['all']) ) {
 
245
                $wp_current_filter[] = $tag;
 
246
                $all_args = func_get_args();
 
247
                _wp_call_all_hook($all_args);
 
248
        }
 
249
 
 
250
        if ( !isset($wp_filter[$tag]) ) {
 
251
                if ( isset($wp_filter['all']) )
 
252
                        array_pop($wp_current_filter);
 
253
                return $args[0];
 
254
        }
 
255
 
 
256
        if ( !isset($wp_filter['all']) )
 
257
                $wp_current_filter[] = $tag;
 
258
 
 
259
        // Sort
 
260
        if ( !isset( $merged_filters[ $tag ] ) ) {
 
261
                ksort($wp_filter[$tag]);
 
262
                $merged_filters[ $tag ] = true;
 
263
        }
 
264
 
 
265
        reset( $wp_filter[ $tag ] );
 
266
 
 
267
        do {
 
268
                foreach( (array) current($wp_filter[$tag]) as $the_ )
 
269
                        if ( !is_null($the_['function']) )
 
270
                                $args[0] = call_user_func_array($the_['function'], array_slice($args, 0, (int) $the_['accepted_args']));
 
271
 
 
272
        } while ( next($wp_filter[$tag]) !== false );
 
273
 
 
274
        array_pop( $wp_current_filter );
 
275
 
 
276
        return $args[0];
 
277
}
 
278
 
 
279
/**
 
280
 * Removes a function from a specified filter hook.
 
281
 *
 
282
 * This function removes a function attached to a specified filter hook. This
 
283
 * method can be used to remove default functions attached to a specific filter
 
284
 * hook and possibly replace them with a substitute.
 
285
 *
 
286
 * To remove a hook, the $function_to_remove and $priority arguments must match
 
287
 * when the hook was added. This goes for both filters and actions. No warning
 
288
 * will be given on removal failure.
 
289
 *
 
290
 * @since 1.2.0
 
291
 *
 
292
 * @param string   $tag                The filter hook to which the function to be removed is hooked.
 
293
 * @param callback $function_to_remove The name of the function which should be removed.
 
294
 * @param int      $priority           Optional. The priority of the function. Default 10.
 
295
 * @return boolean Whether the function existed before it was removed.
 
296
 */
 
297
function remove_filter( $tag, $function_to_remove, $priority = 10 ) {
 
298
        $function_to_remove = _wp_filter_build_unique_id( $tag, $function_to_remove, $priority );
 
299
 
 
300
        $r = isset( $GLOBALS['wp_filter'][ $tag ][ $priority ][ $function_to_remove ] );
 
301
 
 
302
        if ( true === $r ) {
 
303
                unset( $GLOBALS['wp_filter'][ $tag ][ $priority ][ $function_to_remove ] );
 
304
                if ( empty( $GLOBALS['wp_filter'][ $tag ][ $priority ] ) ) {
 
305
                        unset( $GLOBALS['wp_filter'][ $tag ][ $priority ] );
 
306
                }
 
307
                if ( empty( $GLOBALS['wp_filter'][ $tag ] ) ) {
 
308
                        $GLOBALS['wp_filter'][ $tag ] = array();
 
309
                }
 
310
                unset( $GLOBALS['merged_filters'][ $tag ] );
 
311
        }
 
312
 
 
313
        return $r;
 
314
}
 
315
 
 
316
/**
 
317
 * Remove all of the hooks from a filter.
 
318
 *
 
319
 * @since 2.7.0
 
320
 *
 
321
 * @param string   $tag      The filter to remove hooks from.
 
322
 * @param int|bool $priority Optional. The priority number to remove. Default false.
 
323
 * @return bool True when finished.
 
324
 */
 
325
function remove_all_filters( $tag, $priority = false ) {
 
326
        global $wp_filter, $merged_filters;
 
327
 
 
328
        if ( isset( $wp_filter[ $tag ]) ) {
 
329
                if ( false !== $priority && isset( $wp_filter[ $tag ][ $priority ] ) ) {
 
330
                        $wp_filter[ $tag ][ $priority ] = array();
 
331
                } else {
 
332
                        $wp_filter[ $tag ] = array();
 
333
                }
 
334
        }
 
335
 
 
336
        if ( isset( $merged_filters[ $tag ] ) ) {
 
337
                unset( $merged_filters[ $tag ] );
 
338
        }
 
339
 
 
340
        return true;
 
341
}
 
342
 
 
343
/**
 
344
 * Retrieve the name of the current filter or action.
 
345
 *
 
346
 * @since 2.5.0
 
347
 *
 
348
 * @return string Hook name of the current filter or action.
 
349
 */
 
350
function current_filter() {
 
351
        global $wp_current_filter;
 
352
        return end( $wp_current_filter );
 
353
}
 
354
 
 
355
/**
 
356
 * Retrieve the name of the current action.
 
357
 *
 
358
 * @since 3.9.0
 
359
 *
 
360
 * @uses current_filter()
 
361
 *
 
362
 * @return string Hook name of the current action.
 
363
 */
 
364
function current_action() {
 
365
        return current_filter();
 
366
}
 
367
 
 
368
/**
 
369
 * Retrieve the name of a filter currently being processed.
 
370
 *
 
371
 * The function current_filter() only returns the most recent filter or action
 
372
 * being executed. did_action() returns true once the action is initially
 
373
 * processed.
 
374
 *
 
375
 * This function allows detection for any filter currently being
 
376
 * executed (despite not being the most recent filter to fire, in the case of
 
377
 * hooks called from hook callbacks) to be verified.
 
378
 *
 
379
 * @since 3.9.0
 
380
 *
 
381
 * @see current_filter()
 
382
 * @see did_action()
 
383
 * @global array $wp_current_filter Current filter.
 
384
 *
 
385
 * @param null|string $filter Optional. Filter to check. Defaults to null, which
 
386
 *                            checks if any filter is currently being run.
 
387
 * @return bool Whether the filter is currently in the stack.
 
388
 */
 
389
function doing_filter( $filter = null ) {
 
390
        global $wp_current_filter;
 
391
 
 
392
        if ( null === $filter ) {
 
393
                return ! empty( $wp_current_filter );
 
394
        }
 
395
 
 
396
        return in_array( $filter, $wp_current_filter );
 
397
}
 
398
 
 
399
/**
 
400
 * Retrieve the name of an action currently being processed.
 
401
 *
 
402
 * @since 3.9.0
 
403
 *
 
404
 * @uses doing_filter()
 
405
 *
 
406
 * @param string|null $action Optional. Action to check. Defaults to null, which checks
 
407
 *                            if any action is currently being run.
 
408
 * @return bool Whether the action is currently in the stack.
 
409
 */
 
410
function doing_action( $action = null ) {
 
411
        return doing_filter( $action );
 
412
}
 
413
 
 
414
/**
 
415
 * Hooks a function on to a specific action.
 
416
 *
 
417
 * Actions are the hooks that the WordPress core launches at specific points
 
418
 * during execution, or when specific events occur. Plugins can specify that
 
419
 * one or more of its PHP functions are executed at these points, using the
 
420
 * Action API.
 
421
 *
 
422
 * @since 1.2.0
 
423
 *
 
424
 * @uses add_filter() Adds an action. Parameter list and functionality are the same.
 
425
 *
 
426
 * @param string   $tag             The name of the action to which the $function_to_add is hooked.
 
427
 * @param callback $function_to_add The name of the function you wish to be called.
 
428
 * @param int      $priority        Optional. Used to specify the order in which the functions
 
429
 *                                  associated with a particular action are executed. Default 10.
 
430
 *                                  Lower numbers correspond with earlier execution,
 
431
 *                                  and functions with the same priority are executed
 
432
 *                                  in the order in which they were added to the action.
 
433
 * @param int      $accepted_args   Optional. The number of arguments the function accept. Default 1.
 
434
 * @return bool Will always return true.
 
435
 */
 
436
function add_action($tag, $function_to_add, $priority = 10, $accepted_args = 1) {
 
437
        return add_filter($tag, $function_to_add, $priority, $accepted_args);
 
438
}
 
439
 
 
440
/**
 
441
 * Execute functions hooked on a specific action hook.
 
442
 *
 
443
 * This function invokes all functions attached to action hook $tag. It is
 
444
 * possible to create new action hooks by simply calling this function,
 
445
 * specifying the name of the new hook using the <tt>$tag</tt> parameter.
 
446
 *
 
447
 * You can pass extra arguments to the hooks, much like you can with
 
448
 * apply_filters().
 
449
 *
 
450
 * @since 1.2.0
 
451
 *
 
452
 * @see apply_filters() This function works similar with the exception that nothing
 
453
 *                      is returned and only the functions or methods are called.
 
454
 * @global array $wp_filter  Stores all of the filters
 
455
 * @global array $wp_actions Increments the amount of times action was triggered.
 
456
 *
 
457
 * @param string $tag The name of the action to be executed.
 
458
 * @param mixed  $arg Optional. Additional arguments which are passed on to the
 
459
 *                    functions hooked to the action. Default empty.
 
460
 * @return null Will return null if $tag does not exist in $wp_filter array.
 
461
 */
 
462
function do_action($tag, $arg = '') {
 
463
        global $wp_filter, $wp_actions, $merged_filters, $wp_current_filter;
 
464
 
 
465
        if ( ! isset($wp_actions[$tag]) )
 
466
                $wp_actions[$tag] = 1;
 
467
        else
 
468
                ++$wp_actions[$tag];
 
469
 
 
470
        // Do 'all' actions first
 
471
        if ( isset($wp_filter['all']) ) {
 
472
                $wp_current_filter[] = $tag;
 
473
                $all_args = func_get_args();
 
474
                _wp_call_all_hook($all_args);
 
475
        }
 
476
 
 
477
        if ( !isset($wp_filter[$tag]) ) {
 
478
                if ( isset($wp_filter['all']) )
 
479
                        array_pop($wp_current_filter);
 
480
                return;
 
481
        }
 
482
 
 
483
        if ( !isset($wp_filter['all']) )
 
484
                $wp_current_filter[] = $tag;
 
485
 
 
486
        $args = array();
 
487
        if ( is_array($arg) && 1 == count($arg) && isset($arg[0]) && is_object($arg[0]) ) // array(&$this)
 
488
                $args[] =& $arg[0];
 
489
        else
 
490
                $args[] = $arg;
 
491
        for ( $a = 2; $a < func_num_args(); $a++ )
 
492
                $args[] = func_get_arg($a);
 
493
 
 
494
        // Sort
 
495
        if ( !isset( $merged_filters[ $tag ] ) ) {
 
496
                ksort($wp_filter[$tag]);
 
497
                $merged_filters[ $tag ] = true;
 
498
        }
 
499
 
 
500
        reset( $wp_filter[ $tag ] );
 
501
 
 
502
        do {
 
503
                foreach ( (array) current($wp_filter[$tag]) as $the_ )
 
504
                        if ( !is_null($the_['function']) )
 
505
                                call_user_func_array($the_['function'], array_slice($args, 0, (int) $the_['accepted_args']));
 
506
 
 
507
        } while ( next($wp_filter[$tag]) !== false );
 
508
 
 
509
        array_pop($wp_current_filter);
 
510
}
 
511
 
 
512
/**
 
513
 * Retrieve the number of times an action is fired.
 
514
 *
 
515
 * @since 2.1.0
 
516
 *
 
517
 * @global array $wp_actions Increments the amount of times action was triggered.
 
518
 *
 
519
 * @param string $tag The name of the action hook.
 
520
 * @return int The number of times action hook $tag is fired.
 
521
 */
 
522
function did_action($tag) {
 
523
        global $wp_actions;
 
524
 
 
525
        if ( ! isset( $wp_actions[ $tag ] ) )
 
526
                return 0;
 
527
 
 
528
        return $wp_actions[$tag];
 
529
}
 
530
 
 
531
/**
 
532
 * Execute functions hooked on a specific action hook, specifying arguments in an array.
 
533
 *
 
534
 * @since 2.1.0
 
535
 *
 
536
 * @see do_action() This function is identical, but the arguments passed to the
 
537
 *                  functions hooked to $tag< are supplied using an array.
 
538
 * @global array $wp_filter  Stores all of the filters
 
539
 * @global array $wp_actions Increments the amount of times action was triggered.
 
540
 *
 
541
 * @param string $tag  The name of the action to be executed.
 
542
 * @param array  $args The arguments supplied to the functions hooked to <tt>$tag</tt>
 
543
 * @return null Will return null if $tag does not exist in $wp_filter array
 
544
 */
 
545
function do_action_ref_array($tag, $args) {
 
546
        global $wp_filter, $wp_actions, $merged_filters, $wp_current_filter;
 
547
 
 
548
        if ( ! isset($wp_actions[$tag]) )
 
549
                $wp_actions[$tag] = 1;
 
550
        else
 
551
                ++$wp_actions[$tag];
 
552
 
 
553
        // Do 'all' actions first
 
554
        if ( isset($wp_filter['all']) ) {
 
555
                $wp_current_filter[] = $tag;
 
556
                $all_args = func_get_args();
 
557
                _wp_call_all_hook($all_args);
 
558
        }
 
559
 
 
560
        if ( !isset($wp_filter[$tag]) ) {
 
561
                if ( isset($wp_filter['all']) )
 
562
                        array_pop($wp_current_filter);
 
563
                return;
 
564
        }
 
565
 
 
566
        if ( !isset($wp_filter['all']) )
 
567
                $wp_current_filter[] = $tag;
 
568
 
 
569
        // Sort
 
570
        if ( !isset( $merged_filters[ $tag ] ) ) {
 
571
                ksort($wp_filter[$tag]);
 
572
                $merged_filters[ $tag ] = true;
 
573
        }
 
574
 
 
575
        reset( $wp_filter[ $tag ] );
 
576
 
 
577
        do {
 
578
                foreach( (array) current($wp_filter[$tag]) as $the_ )
 
579
                        if ( !is_null($the_['function']) )
 
580
                                call_user_func_array($the_['function'], array_slice($args, 0, (int) $the_['accepted_args']));
 
581
 
 
582
        } while ( next($wp_filter[$tag]) !== false );
 
583
 
 
584
        array_pop($wp_current_filter);
 
585
}
 
586
 
 
587
/**
 
588
 * Check if any action has been registered for a hook.
 
589
 *
 
590
 * @since 2.5.0
 
591
 *
 
592
 * @see has_filter() has_action() is an alias of has_filter().
 
593
 *
 
594
 * @param string        $tag               The name of the action hook.
 
595
 * @param callback|bool $function_to_check Optional. The callback to check for. Default false.
 
596
 * @return bool|int If $function_to_check is omitted, returns boolean for whether the hook has
 
597
 *                  anything registered. When checking a specific function, the priority of that
 
598
 *                  hook is returned, or false if the function is not attached. When using the
 
599
 *                  $function_to_check argument, this function may return a non-boolean value
 
600
 *                  that evaluates to false (e.g.) 0, so use the === operator for testing the
 
601
 *                  return value.
 
602
 */
 
603
function has_action($tag, $function_to_check = false) {
 
604
        return has_filter($tag, $function_to_check);
 
605
}
 
606
 
 
607
/**
 
608
 * Removes a function from a specified action hook.
 
609
 *
 
610
 * This function removes a function attached to a specified action hook. This
 
611
 * method can be used to remove default functions attached to a specific filter
 
612
 * hook and possibly replace them with a substitute.
 
613
 *
 
614
 * @since 1.2.0
 
615
 *
 
616
 * @param string   $tag                The action hook to which the function to be removed is hooked.
 
617
 * @param callback $function_to_remove The name of the function which should be removed.
 
618
 * @param int      $priority           Optional. The priority of the function. Default 10.
 
619
 * @return boolean Whether the function is removed.
 
620
 */
 
621
function remove_action( $tag, $function_to_remove, $priority = 10 ) {
 
622
        return remove_filter( $tag, $function_to_remove, $priority );
 
623
}
 
624
 
 
625
/**
 
626
 * Remove all of the hooks from an action.
 
627
 *
 
628
 * @since 2.7.0
 
629
 *
 
630
 * @param string   $tag      The action to remove hooks from.
 
631
 * @param int|bool $priority The priority number to remove them from. Default false.
 
632
 * @return bool True when finished.
 
633
 */
 
634
function remove_all_actions($tag, $priority = false) {
 
635
        return remove_all_filters($tag, $priority);
 
636
}
 
637
 
 
638
//
 
639
// Functions for handling plugins.
 
640
//
 
641
 
 
642
/**
 
643
 * Gets the basename of a plugin.
 
644
 *
 
645
 * This method extracts the name of a plugin from its filename.
 
646
 *
 
647
 * @since 1.5.0
 
648
 *
 
649
 * @uses WP_PLUGIN_DIR, WPMU_PLUGIN_DIR
 
650
 *
 
651
 * @param string $file The filename of plugin.
 
652
 * @return string The name of a plugin.
 
653
 */
 
654
function plugin_basename( $file ) {
 
655
        global $wp_plugin_paths;
 
656
 
 
657
        foreach ( $wp_plugin_paths as $dir => $realdir ) {
 
658
                if ( strpos( $file, $realdir ) === 0 ) {
 
659
                        $file = $dir . substr( $file, strlen( $realdir ) );
 
660
                }
 
661
        }
 
662
 
 
663
        $file = wp_normalize_path( $file );
 
664
        $plugin_dir = wp_normalize_path( WP_PLUGIN_DIR );
 
665
        $mu_plugin_dir = wp_normalize_path( WPMU_PLUGIN_DIR );
 
666
 
 
667
        $file = preg_replace('#^' . preg_quote($plugin_dir, '#') . '/|^' . preg_quote($mu_plugin_dir, '#') . '/#','',$file); // get relative path from plugins dir
 
668
        $file = trim($file, '/');
 
669
        return $file;
 
670
}
 
671
 
 
672
/**
 
673
 * Register a plugin's real path.
 
674
 *
 
675
 * This is used in plugin_basename() to resolve symlinked paths.
 
676
 *
 
677
 * @since 3.9.0
 
678
 *
 
679
 * @see plugin_basename()
 
680
 *
 
681
 * @param string $file Known path to the file.
 
682
 * @return bool Whether the path was able to be registered.
 
683
 */
 
684
function wp_register_plugin_realpath( $file ) {
 
685
        global $wp_plugin_paths;
 
686
 
 
687
        // Normalize, but store as static to avoid recalculation of a constant value
 
688
        static $wp_plugin_path, $wpmu_plugin_path;
 
689
        if ( ! isset( $wp_plugin_path ) ) {
 
690
                $wp_plugin_path   = wp_normalize_path( WP_PLUGIN_DIR   );
 
691
                $wpmu_plugin_path = wp_normalize_path( WPMU_PLUGIN_DIR );
 
692
        }
 
693
 
 
694
        $plugin_path = wp_normalize_path( dirname( $file ) );
 
695
        $plugin_realpath = wp_normalize_path( dirname( realpath( $file ) ) );
 
696
 
 
697
        if ( $plugin_path === $wp_plugin_path || $plugin_path === $wpmu_plugin_path ) {
 
698
                return false;
 
699
        }
 
700
 
 
701
        if ( $plugin_path !== $plugin_realpath ) {
 
702
                $wp_plugin_paths[ $plugin_path ] = $plugin_realpath;
 
703
        }
 
704
 
 
705
        return true;
 
706
}
 
707
 
 
708
/**
 
709
 * Get the filesystem directory path (with trailing slash) for the plugin __FILE__ passed in.
 
710
 *
 
711
 * @since 2.8.0
 
712
 *
 
713
 * @param string $file The filename of the plugin (__FILE__).
 
714
 * @return string the filesystem path of the directory that contains the plugin.
 
715
 */
 
716
function plugin_dir_path( $file ) {
 
717
        return trailingslashit( dirname( $file ) );
 
718
}
 
719
 
 
720
/**
 
721
 * Get the URL directory path (with trailing slash) for the plugin __FILE__ passed in.
 
722
 *
 
723
 * @since 2.8.0
 
724
 *
 
725
 * @param string $file The filename of the plugin (__FILE__).
 
726
 * @return string the URL path of the directory that contains the plugin.
 
727
 */
 
728
function plugin_dir_url( $file ) {
 
729
        return trailingslashit( plugins_url( '', $file ) );
 
730
}
 
731
 
 
732
/**
 
733
 * Set the activation hook for a plugin.
 
734
 *
 
735
 * When a plugin is activated, the action 'activate_PLUGINNAME' hook is
 
736
 * called. In the name of this hook, PLUGINNAME is replaced with the name
 
737
 * of the plugin, including the optional subdirectory. For example, when the
 
738
 * plugin is located in wp-content/plugins/sampleplugin/sample.php, then
 
739
 * the name of this hook will become 'activate_sampleplugin/sample.php'.
 
740
 *
 
741
 * When the plugin consists of only one file and is (as by default) located at
 
742
 * wp-content/plugins/sample.php the name of this hook will be
 
743
 * 'activate_sample.php'.
 
744
 *
 
745
 * @since 2.0.0
 
746
 *
 
747
 * @param string   $file     The filename of the plugin including the path.
 
748
 * @param callback $function The function hooked to the 'activate_PLUGIN' action.
 
749
 */
 
750
function register_activation_hook($file, $function) {
 
751
        $file = plugin_basename($file);
 
752
        add_action('activate_' . $file, $function);
 
753
}
 
754
 
 
755
/**
 
756
 * Set the deactivation hook for a plugin.
 
757
 *
 
758
 * When a plugin is deactivated, the action 'deactivate_PLUGINNAME' hook is
 
759
 * called. In the name of this hook, PLUGINNAME is replaced with the name
 
760
 * of the plugin, including the optional subdirectory. For example, when the
 
761
 * plugin is located in wp-content/plugins/sampleplugin/sample.php, then
 
762
 * the name of this hook will become 'deactivate_sampleplugin/sample.php'.
 
763
 *
 
764
 * When the plugin consists of only one file and is (as by default) located at
 
765
 * wp-content/plugins/sample.php the name of this hook will be
 
766
 * 'deactivate_sample.php'.
 
767
 *
 
768
 * @since 2.0.0
 
769
 *
 
770
 * @param string   $file     The filename of the plugin including the path.
 
771
 * @param callback $function The function hooked to the 'deactivate_PLUGIN' action.
 
772
 */
 
773
function register_deactivation_hook($file, $function) {
 
774
        $file = plugin_basename($file);
 
775
        add_action('deactivate_' . $file, $function);
 
776
}
 
777
 
 
778
/**
 
779
 * Set the uninstallation hook for a plugin.
 
780
 *
 
781
 * Registers the uninstall hook that will be called when the user clicks on the
 
782
 * uninstall link that calls for the plugin to uninstall itself. The link won't
 
783
 * be active unless the plugin hooks into the action.
 
784
 *
 
785
 * The plugin should not run arbitrary code outside of functions, when
 
786
 * registering the uninstall hook. In order to run using the hook, the plugin
 
787
 * will have to be included, which means that any code laying outside of a
 
788
 * function will be run during the uninstall process. The plugin should not
 
789
 * hinder the uninstall process.
 
790
 *
 
791
 * If the plugin can not be written without running code within the plugin, then
 
792
 * the plugin should create a file named 'uninstall.php' in the base plugin
 
793
 * folder. This file will be called, if it exists, during the uninstall process
 
794
 * bypassing the uninstall hook. The plugin, when using the 'uninstall.php'
 
795
 * should always check for the 'WP_UNINSTALL_PLUGIN' constant, before
 
796
 * executing.
 
797
 *
 
798
 * @since 2.7.0
 
799
 *
 
800
 * @param string   $file     Plugin file.
 
801
 * @param callback $callback The callback to run when the hook is called. Must be
 
802
 *                           a static method or function.
 
803
 */
 
804
function register_uninstall_hook( $file, $callback ) {
 
805
        if ( is_array( $callback ) && is_object( $callback[0] ) ) {
 
806
                _doing_it_wrong( __FUNCTION__, __( 'Only a static class method or function can be used in an uninstall hook.' ), '3.1' );
 
807
                return;
 
808
        }
 
809
 
 
810
        /*
 
811
         * The option should not be autoloaded, because it is not needed in most
 
812
         * cases. Emphasis should be put on using the 'uninstall.php' way of
 
813
         * uninstalling the plugin.
 
814
         */
 
815
        $uninstallable_plugins = (array) get_option('uninstall_plugins');
 
816
        $uninstallable_plugins[plugin_basename($file)] = $callback;
 
817
 
 
818
        update_option('uninstall_plugins', $uninstallable_plugins);
 
819
}
 
820
 
 
821
/**
 
822
 * Call the 'all' hook, which will process the functions hooked into it.
 
823
 *
 
824
 * The 'all' hook passes all of the arguments or parameters that were used for
 
825
 * the hook, which this function was called for.
 
826
 *
 
827
 * This function is used internally for apply_filters(), do_action(), and
 
828
 * do_action_ref_array() and is not meant to be used from outside those
 
829
 * functions. This function does not check for the existence of the all hook, so
 
830
 * it will fail unless the all hook exists prior to this function call.
 
831
 *
 
832
 * @since 2.5.0
 
833
 * @access private
 
834
 *
 
835
 * @uses $wp_filter Used to process all of the functions in the 'all' hook.
 
836
 *
 
837
 * @param array $args The collected parameters from the hook that was called.
 
838
 */
 
839
function _wp_call_all_hook($args) {
 
840
        global $wp_filter;
 
841
 
 
842
        reset( $wp_filter['all'] );
 
843
        do {
 
844
                foreach( (array) current($wp_filter['all']) as $the_ )
 
845
                        if ( !is_null($the_['function']) )
 
846
                                call_user_func_array($the_['function'], $args);
 
847
 
 
848
        } while ( next($wp_filter['all']) !== false );
 
849
}
 
850
 
 
851
/**
 
852
 * Build Unique ID for storage and retrieval.
 
853
 *
 
854
 * The old way to serialize the callback caused issues and this function is the
 
855
 * solution. It works by checking for objects and creating an a new property in
 
856
 * the class to keep track of the object and new objects of the same class that
 
857
 * need to be added.
 
858
 *
 
859
 * It also allows for the removal of actions and filters for objects after they
 
860
 * change class properties. It is possible to include the property $wp_filter_id
 
861
 * in your class and set it to "null" or a number to bypass the workaround.
 
862
 * However this will prevent you from adding new classes and any new classes
 
863
 * will overwrite the previous hook by the same class.
 
864
 *
 
865
 * Functions and static method callbacks are just returned as strings and
 
866
 * shouldn't have any speed penalty.
 
867
 *
 
868
 * @link http://trac.wordpress.org/ticket/3875
 
869
 *
 
870
 * @since 2.2.3
 
871
 * @access private
 
872
 *
 
873
 * @global array $wp_filter Storage for all of the filters and actions.
 
874
 *
 
875
 * @param string   $tag      Used in counting how many hooks were applied
 
876
 * @param callback $function Used for creating unique id
 
877
 * @param int|bool $priority Used in counting how many hooks were applied. If === false
 
878
 *                           and $function is an object reference, we return the unique
 
879
 *                           id only if it already has one, false otherwise.
 
880
 * @return string|bool Unique ID for usage as array key or false if $priority === false
 
881
 *                     and $function is an object reference, and it does not already have
 
882
 *                     a unique id.
 
883
 */
 
884
function _wp_filter_build_unique_id($tag, $function, $priority) {
 
885
        global $wp_filter;
 
886
        static $filter_id_count = 0;
 
887
 
 
888
        if ( is_string($function) )
 
889
                return $function;
 
890
 
 
891
        if ( is_object($function) ) {
 
892
                // Closures are currently implemented as objects
 
893
                $function = array( $function, '' );
 
894
        } else {
 
895
                $function = (array) $function;
 
896
        }
 
897
 
 
898
        if (is_object($function[0]) ) {
 
899
                // Object Class Calling
 
900
                if ( function_exists('spl_object_hash') ) {
 
901
                        return spl_object_hash($function[0]) . $function[1];
 
902
                } else {
 
903
                        $obj_idx = get_class($function[0]).$function[1];
 
904
                        if ( !isset($function[0]->wp_filter_id) ) {
 
905
                                if ( false === $priority )
 
906
                                        return false;
 
907
                                $obj_idx .= isset($wp_filter[$tag][$priority]) ? count((array)$wp_filter[$tag][$priority]) : $filter_id_count;
 
908
                                $function[0]->wp_filter_id = $filter_id_count;
 
909
                                ++$filter_id_count;
 
910
                        } else {
 
911
                                $obj_idx .= $function[0]->wp_filter_id;
 
912
                        }
 
913
 
 
914
                        return $obj_idx;
 
915
                }
 
916
        } else if ( is_string($function[0]) ) {
 
917
                // Static Calling
 
918
                return $function[0] . '::' . $function[1];
 
919
        }
 
920
}