<?php

/**

 * The plugin API is located in this file, which allows for creating actions

 * and filters and hooking functions, and methods. The functions or methods will

 * then be run when the action or filter is called.

 *

 * The API callback examples reference functions, but can be methods of classes.

 * To hook methods, you'll need to pass an array one of two ways.

 *

 * Any of the syntaxes explained in the PHP documentation for the

 * {@link http://us2.php.net/manual/en/language.pseudo-types.php#language.types.callback 'callback'}

 * type are valid.

 *

 * Also see the {@link http://codex.wordpress.org/Plugin_API Plugin API} for

 * more information and examples on how to use a lot of these functions.

 *

 * @package WordPress

 * @subpackage Plugin

 * @since 1.5

 */

// Initialize the filter globals.

global $wp_filter, $wp_actions, $merged_filters, $wp_current_filter;

if ( ! isset( $wp_filter ) )

	$wp_filter = array();

if ( ! isset( $wp_actions ) )

	$wp_actions = array();

if ( ! isset( $merged_filters ) )

	$merged_filters = array();

if ( ! isset( $wp_current_filter ) )

	$wp_current_filter = array();

/**

 * Hooks a function or method to a specific filter action.

 *

 * WordPress offers filter hooks to allow plugins to modify

 * various types of internal data at runtime.

 *

 * A plugin can modify data by binding a callback to a filter hook. When the filter

 * is later applied, each bound callback is run in order of priority, and given

 * the opportunity to modify a value by returning a new value.

 *

 * The following example shows how a callback function is bound to a filter hook.

 * Note that $example is passed to the callback, (maybe) modified, then returned:

 *

 * <code>

 * function example_callback( $example ) {

 * 	// Maybe modify $example in some way

 * 	return $example;

 * }

 * add_filter( 'example_filter', 'example_callback' );

 * </code>

 *

 * Since WordPress 1.5.1, bound callbacks can take as many arguments as are

 * passed as parameters in the corresponding apply_filters() call. The $accepted_args

 * parameter allows for calling functions only when the number of args match.

 *

 * <strong>Note:</strong> the function will return true whether or not the callback

 * is valid. It is up to you to take care. This is done for optimization purposes,

 * so everything is as quick as possible.

 *

 * @package WordPress

 * @subpackage Plugin

 *

 * @global array $wp_filter      A multidimensional array of all hooks and the callbacks hooked to them.

 * @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.

 *

 * @since 0.71

 *

 * @param string   $tag             The name of the filter to hook the $function_to_add callback to.

 * @param callback $function_to_add The callback to be run when the filter is applied.

 * @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.

 *                                  Default 10.

 * @param int      $accepted_args   (optional) The number of arguments the function accepts.

 *                                  Default 1.

 * @return boolean true

 */

function add_filter( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) {

	global $wp_filter, $merged_filters;

	$idx = _wp_filter_build_unique_id($tag, $function_to_add, $priority);

	$wp_filter[$tag][$priority][$idx] = array('function' => $function_to_add, 'accepted_args' => $accepted_args);

	unset( $merged_filters[ $tag ] );

	return true;

}

/**

 * Check if any filter has been registered for a hook.

 *

 * @package WordPress

 * @subpackage Plugin

 * @since 2.5

 * @global array $wp_filter Stores all of the filters

 *

 * @param string $tag The name of the filter hook.

 * @param callback $function_to_check optional.

 * @return mixed If $function_to_check is omitted, returns boolean for whether the hook has anything registered.

 * 	When checking a specific function, the priority of that hook is returned, or false if the function is not attached.

 * 	When using the $function_to_check argument, this function may return a non-boolean value that evaluates to false

 * 	(e.g.) 0, so use the === operator for testing the return value.

 */

function has_filter($tag, $function_to_check = false) {

	global $wp_filter;

	$has = !empty($wp_filter[$tag]);

	if ( false === $function_to_check || false == $has )

		return $has;

	if ( !$idx = _wp_filter_build_unique_id($tag, $function_to_check, false) )

		return false;

	foreach ( (array) array_keys($wp_filter[$tag]) as $priority ) {

		if ( isset($wp_filter[$tag][$priority][$idx]) )

			return $priority;

	}

	return false;

}

/**

 * Call the functions added to a filter hook.

 *

 * The callback functions attached to filter hook $tag are invoked by calling

 * this function. This function can be used to create a new filter hook by

 * simply calling this function with the name of the new hook specified using

 * the $tag parameter.

 *

 * The function allows for additional arguments to be added and passed to hooks.

 * <code>

 * // Our filter callback function

 * function example_callback( $string, $arg1, $arg2 ) {

 *	// (maybe) modify $string

 *	return $string;

 * }

 * add_filter( 'example_filter', 'example_callback', 10, 3 );

 *

 * // Apply the filters by calling the 'example_callback' function we

 * // "hooked" to 'example_filter' using the add_filter() function above.

 * // - 'example_filter' is the filter hook $tag

 * // - 'filter me' is the value being filtered

 * // - $arg1 and $arg2 are the additional arguments passed to the callback.

 * $value = apply_filters( 'example_filter', 'filter me', $arg1, $arg2 );

 * </code>

 *

 * @package WordPress

 * @subpackage Plugin

 *

 * @global array $wp_filter         Stores all of the filters

 * @global array $merged_filters    Merges the filter hooks using this function.

 * @global array $wp_current_filter stores the list of current filters with the current one last

 *

 * @since 0.71

 *

 * @param string $tag  The name of the filter hook.

 * @param mixed $value The value on which the filters hooked to <tt>$tag</tt> are applied on.

 * @param mixed $var   Additional variables passed to the functions hooked to <tt>$tag</tt>.

 * @return mixed The filtered value after all hooked functions are applied to it.

 */

function apply_filters( $tag, $value ) {

	global $wp_filter, $merged_filters, $wp_current_filter;

	$args = array();

	// Do 'all' actions first

	if ( isset($wp_filter['all']) ) {

		$wp_current_filter[] = $tag;

		$args = func_get_args();

		_wp_call_all_hook($args);

	}

	if ( !isset($wp_filter[$tag]) ) {

		if ( isset($wp_filter['all']) )

			array_pop($wp_current_filter);

		return $value;

	}

	if ( !isset($wp_filter['all']) )

		$wp_current_filter[] = $tag;

	// Sort

	if ( !isset( $merged_filters[ $tag ] ) ) {

		ksort($wp_filter[$tag]);

		$merged_filters[ $tag ] = true;

	}

	reset( $wp_filter[ $tag ] );

	if ( empty($args) )

		$args = func_get_args();

	do {

		foreach( (array) current($wp_filter[$tag]) as $the_ )

			if ( !is_null($the_['function']) ){

				$args[1] = $value;

				$value = call_user_func_array($the_['function'], array_slice($args, 1, (int) $the_['accepted_args']));

			}

	} while ( next($wp_filter[$tag]) !== false );

	array_pop( $wp_current_filter );

	return $value;

}

/**

 * Execute functions hooked on a specific filter hook, specifying arguments in an array.

 *

 * @see apply_filters() This function is identical, but the arguments passed to the

 * functions hooked to <tt>$tag</tt> are supplied using an array.

 *

 * @package WordPress

 * @subpackage Plugin

 * @since 3.0.0

 * @global array $wp_filter Stores all of the filters

 * @global array $merged_filters Merges the filter hooks using this function.

 * @global array $wp_current_filter stores the list of current filters with the current one last

 *

 * @param string $tag The name of the filter hook.

 * @param array $args The arguments supplied to the functions hooked to <tt>$tag</tt>

 * @return mixed The filtered value after all hooked functions are applied to it.

 */

function apply_filters_ref_array($tag, $args) {

	global $wp_filter, $merged_filters, $wp_current_filter;

	// Do 'all' actions first

	if ( isset($wp_filter['all']) ) {

		$wp_current_filter[] = $tag;

		$all_args = func_get_args();

		_wp_call_all_hook($all_args);

	}

	if ( !isset($wp_filter[$tag]) ) {

		if ( isset($wp_filter['all']) )

			array_pop($wp_current_filter);

		return $args[0];

	}

	if ( !isset($wp_filter['all']) )

		$wp_current_filter[] = $tag;

	// Sort

	if ( !isset( $merged_filters[ $tag ] ) ) {

		ksort($wp_filter[$tag]);

		$merged_filters[ $tag ] = true;

	}

	reset( $wp_filter[ $tag ] );

	do {

		foreach( (array) current($wp_filter[$tag]) as $the_ )

			if ( !is_null($the_['function']) )

				$args[0] = call_user_func_array($the_['function'], array_slice($args, 0, (int) $the_['accepted_args']));

	} while ( next($wp_filter[$tag]) !== false );

	array_pop( $wp_current_filter );

	return $args[0];

}

/**

 * Removes a function from a specified filter hook.

 *

 * This function removes a function attached to a specified filter hook. This

 * method can be used to remove default functions attached to a specific filter

 * hook and possibly replace them with a substitute.

 *

 * To remove a hook, the $function_to_remove and $priority arguments must match

 * when the hook was added. This goes for both filters and actions. No warning

 * will be given on removal failure.

 *

 * @package WordPress

 * @subpackage Plugin

 * @since 1.2

 *

 * @param string $tag The filter hook to which the function to be removed is hooked.

 * @param callback $function_to_remove The name of the function which should be removed.

 * @param int $priority optional. The priority of the function (default: 10).

 * @param int $accepted_args optional. The number of arguments the function accepts (default: 1).

 * @return boolean Whether the function existed before it was removed.

 */

function remove_filter( $tag, $function_to_remove, $priority = 10 ) {

	$function_to_remove = _wp_filter_build_unique_id($tag, $function_to_remove, $priority);

	$r = isset($GLOBALS['wp_filter'][$tag][$priority][$function_to_remove]);

	if ( true === $r) {

		unset($GLOBALS['wp_filter'][$tag][$priority][$function_to_remove]);

		if ( empty($GLOBALS['wp_filter'][$tag][$priority]) )

			unset($GLOBALS['wp_filter'][$tag][$priority]);

		unset($GLOBALS['merged_filters'][$tag]);

	}

	return $r;

}

/**

 * Remove all of the hooks from a filter.

 *

 * @since 2.7

 *

 * @param string $tag The filter to remove hooks from.

 * @param int $priority The priority number to remove.

 * @return bool True when finished.

 */

function remove_all_filters($tag, $priority = false) {

	global $wp_filter, $merged_filters;

	if( isset($wp_filter[$tag]) ) {

		if( false !== $priority && isset($wp_filter[$tag][$priority]) )

			unset($wp_filter[$tag][$priority]);

		else

			unset($wp_filter[$tag]);

	}

	if( isset($merged_filters[$tag]) )

		unset($merged_filters[$tag]);

	return true;

}

/**

 * Retrieve the name of the current filter or action.

 *

 * @package WordPress

 * @subpackage Plugin

 * @since 2.5

 *

 * @return string Hook name of the current filter or action.

 */

function current_filter() {

	global $wp_current_filter;

	return end( $wp_current_filter );

}

/**

 * Hooks a function on to a specific action.

 *

 * Actions are the hooks that the WordPress core launches at specific points

 * during execution, or when specific events occur. Plugins can specify that

 * one or more of its PHP functions are executed at these points, using the

 * Action API.

 *

 * @uses add_filter() Adds an action. Parameter list and functionality are the same.

 *

 * @package WordPress

 * @subpackage Plugin

 * @since 1.2

 *

 * @param string $tag The name of the action to which the $function_to_add is hooked.

 * @param callback $function_to_add The name of the function you wish to be called.

 * @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.

 * @param int $accepted_args optional. The number of arguments the function accept (default 1).

 */

function add_action($tag, $function_to_add, $priority = 10, $accepted_args = 1) {

	return add_filter($tag, $function_to_add, $priority, $accepted_args);

}

/**

 * Execute functions hooked on a specific action hook.

 *

 * This function invokes all functions attached to action hook $tag. It is

 * possible to create new action hooks by simply calling this function,

 * specifying the name of the new hook using the <tt>$tag</tt> parameter.

 *

 * You can pass extra arguments to the hooks, much like you can with

 * apply_filters().

 *

 * @see apply_filters() This function works similar with the exception that

 * nothing is returned and only the functions or methods are called.

 *

 * @package WordPress

 * @subpackage Plugin

 * @since 1.2

 * @global array $wp_filter Stores all of the filters

 * @global array $wp_actions Increments the amount of times action was triggered.

 *

 * @param string $tag The name of the action to be executed.

 * @param mixed $arg,... Optional additional arguments which are passed on to the functions hooked to the action.

 * @return null Will return null if $tag does not exist in $wp_filter array

 */

function do_action($tag, $arg = '') {

	global $wp_filter, $wp_actions, $merged_filters, $wp_current_filter;

	if ( ! isset($wp_actions[$tag]) )

		$wp_actions[$tag] = 1;

	else

		++$wp_actions[$tag];

	// Do 'all' actions first

	if ( isset($wp_filter['all']) ) {

		$wp_current_filter[] = $tag;

		$all_args = func_get_args();

		_wp_call_all_hook($all_args);

	}

	if ( !isset($wp_filter[$tag]) ) {

		if ( isset($wp_filter['all']) )

			array_pop($wp_current_filter);

		return;

	}

	if ( !isset($wp_filter['all']) )

		$wp_current_filter[] = $tag;

	$args = array();

	if ( is_array($arg) && 1 == count($arg) && isset($arg[0]) && is_object($arg[0]) ) // array(&$this)

		$args[] =& $arg[0];

	else

		$args[] = $arg;

	for ( $a = 2; $a < func_num_args(); $a++ )

		$args[] = func_get_arg($a);

	// Sort

	if ( !isset( $merged_filters[ $tag ] ) ) {

		ksort($wp_filter[$tag]);

		$merged_filters[ $tag ] = true;

	}

	reset( $wp_filter[ $tag ] );

	do {

		foreach ( (array) current($wp_filter[$tag]) as $the_ )

			if ( !is_null($the_['function']) )

				call_user_func_array($the_['function'], array_slice($args, 0, (int) $the_['accepted_args']));

	} while ( next($wp_filter[$tag]) !== false );

	array_pop($wp_current_filter);

}

/**

 * Retrieve the number of times an action is fired.

 *

 * @package WordPress

 * @subpackage Plugin

 * @since 2.1

 * @global array $wp_actions Increments the amount of times action was triggered.