add_filter()给一个过滤器钩子添加一个回调方法

目录

描述

译文

将函数连接到特定过滤器动作。

过滤器是WordPress发布的一种hook,在不同类别的文本被添加到书库据或发送到浏览器窗口前对这些文本进行修改。插件可用过滤器API规定在修改特定类型的文本时,执行一个还是多个PHP函数。在Plugin API上查阅过滤器hook列表。

原文

Hook a function to a specific filter action.

add_filter() 描述

用法

 <?php add_filter$tag$function_to_add$priority$accepted_args ); ?> 

add_filter() 用法

参数

$tag

(string) (必填) The name of the existing Filter to Hook the $function_to_add argument to. You can find a list of Filter Hooks here.

默认值: None

$function_to_add

(callback) (必填) The name of the function to be called when the custom Filter is applied.

默认值: None

$priority

(integer) (可选) Used to specify 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 filter.

默认值: 10

$accepted_args

(integer) (可选) The number of arguments the function(s) accept(s). In WordPress 1.5.1 and newer hooked functions can take extra arguments that are set when the matching apply_filters() call is run.

默认值: 1

add_filter() 参数

注意

  • Although you can pass the number of $accepted_args, you can only manipulate the $value. The other arguments are only to provide context, and their values cannot be changed by the 过滤器 function.
  • You can also pass a class method as a callback.

Static class method:

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
add_filter( 'media_upload_newtab', array( 'My_Class', 'media_upload_callback' ) );

Instance method:

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
add_filter( 'media_upload_newtab', array( $this, 'media_upload_callback' ) );

  • You can also pass an an anonymous function as a callback. For example:

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
add_filter( 'the_title', function( $title ) { return '<b>' . $title . '</b>'; } );

Anonymous functions were introduced in PHP 5.3.0. Check Hosting WordPress requirements and double check your PHP version before using them.

If your version of PHP is older than 5.3.0, you can use create_function() instead. But keep in mind that lambda functions created by create_function() are not cached by APC or any other optimizer. So don't use create_function() if callback is supposed to be used more than few times or it has complex logic.

add_filter() 注意

历史

  • 添加于 版本: 0.71

add_filter() 历史

源文件

add_filter() 函数的代码位于 wp-includes/plugin.php.

/* ----------------------------------
 * wordpress之魂 © http://wphun.com
 * ---------------------------------- */
/**
 * Hook 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:
 *
 *     function example_callback( $example ) {
 *         // Maybe modify $example in some way.
 *     	   return $example;
 *     }
 *     add_filter( 'example_filter', 'example_callback' );
 *
 * 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.
 *
 * *Note:* 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.
 *
 * @since 0.71
 *
 * @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.
 *
 * @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. 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 accepts. Default 1.
 * @return 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;
}

add_filter() 源文件

相关