<?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

 */

/**

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

 *

 * Filters are the hooks that WordPress launches to modify text of various types

 * before adding it to the database or sending it to the browser screen. Plugins

 * can specify that one or more of its PHP functions is executed to

 * modify specific types of text at these times, using the Filter API.

 *

 * To use the API, the following code should be used to bind a callback to the

 * filter.

 *

 * <code>

 * function example_hook($example) { echo $example; }

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

 * </code>

 *

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

 * $accepted_args allow for calling functions only when the number of args

 * match. Hooked functions can take extra arguments that are set when the

 * matching do_action() or apply_filters() call is run. For example, the action

 * comment_id_not_found will pass any functions that hook onto it the ID of the

 * requested comment.

 *

 * <strong>Note:</strong> the function will return true no matter if the

 * function was hooked fails or not. There are no checks for whether the

 * function exists beforehand and no checks to whether the <tt>$function_to_add

 * is even a string. It is up to you to take care and this is done for

 * optimization purposes, so everything is as quick as possible.

 *

 * @package WordPress

 * @subpackage Plugin

 * @since 0.71

 * @global array $wp_filter Stores all of the filters added in the form of

 *	wp_filter['tag']['array of priorities']['array of functions serialized']['array of ['array (functions, accepted_args)']']

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

 *

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

 * @param callback $function_to_add The name of the function to be called when the filter is applied.

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

 * @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. If specified, return the priority of that function on this hook or false if not attached.

 * @return int|boolean Optionally returns the priority on that hook for the specified function.

 */

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>

 * function example_hook($string, $arg1, $arg2)

 * {

 *		//Do stuff

 *		return $string;

 * }

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

 * </code>

 *

 * @package WordPress

 * @subpackage Plugin

 * @since 0.71

 * @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 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, $accepted_args = 1) {

	$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) )

		$wp_actions = array();

	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.

 *

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

 * @return int The number of times action hook <tt>$tag</tt> is fired

 */

function did_action($tag) {

	global $wp_actions;

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

		return 0;

	return $wp_actions[$tag];

}

/**

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

 *

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

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

 *