WordPress开发函数add_filter()，将函数或方法挂钩到特定的筛选器操作。

用法：

add_filter( string $tag, callable $function_to_add, int $priority = 10, int $accepted_args = 1 )

描述：

WordPress提供了过滤钩子，允许插件在运行时修改各种类型的内部数据。

插件可以通过将回调绑定到筛选器钩子来修改数据。当稍后应用筛选器时，将按优先级顺序运行每个绑定回调，并给予机会通过返回新值来修改值。

下面的示例展示了如何将回调函数绑定到筛选器钩子。

注意，$example被传递给回调函数，(可能)被修改，然后返回:

function example_callback( $example ) {

// Maybe modify $example in some way.

return $example;

}

add_filter( ‘example_filter’, ‘example_callback’ );

在相应的apply_filters()调用中。

换句话说，如果apply_filters()调用传递了四个总参数，则回调绑定到

它可以接受none(等同于1)或最多4个参数。重要的是

$accepted_args值必须反映绑定回调的实际参数数量

选择接受。如果回调函数没有接受任何参数，则被认为是

与接受1个参数相同。例如:

// Filter call.

$value = apply_filters( ‘hook’, $value, $arg2, $arg3 );

// Accepting zero/one arguments.

function example_callback() {

…

return ‘some value’;

}

add_filter( ‘hook’, ‘example_callback’ ); // Where $priority is default 10, $accepted_args is default 1.

// Accepting two arguments (three possible).

function example_callback( $value, $arg2 ) {

…

return $maybe_modified_value;

}

add_filter( ‘hook’, ‘example_callback’, 10, 2 ); // Where $priority is 10, $accepted_args is 2.

_Note:_函数将返回true无论回调函数是否有效。这件事由你来负责。这是为了优化目的而做的，所以一切都尽可能快。

参数：

$tag

(string) (必需) 钩子$function_to_add回调函数的过滤器的名字。

$function_to_add

(callable) (必需) 应用筛选器时要运行的回调函数。

$priority

(int) (可选) 用于指定与特定操作相关联的函数的执行顺序。较低的数字对应较早的执行，具有相同优先级的函数按照它们添加到动作中的顺序执行。

默认值: 10

$accepted_args

(int) (可选) 函数接受的参数个数。

默认值: 1

更多信息

钩子函数可以接受额外的参数，这些参数是在运行匹配的do_action()或apply_filters()调用时设置的。例如，comment_id_not_found操作将把注释ID传递给每个回调。

虽然可以传递$accepted_args的数量，但只能操作$值。其他参数仅用于提供上下文，它们的值不能被filter函数更改。

您还可以将类方法作为回调传递。

静态类方法:

add_filter( ‘media_upload_newtab’, array( ‘My_Class’, ‘media_upload_callback’ ) );

实例方法:

add_filter( ‘media_upload_newtab’, array( $this, ‘media_upload_callback’ ) );

您还可以将匿名函数作为回调函数传递。例如:

add_filter( ‘the_title’, function( $title ) { return ‘<strong>’ . $title . ‘</strong>’; } );

来源：

文件：wp-includes/plugin.php

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

global $wp_filter;

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

$wp_filter[ $tag ] = new WP_Hook();

}

$wp_filter[ $tag ]->add_filter( $tag, $function_to_add, $priority, $accepted_args );

return true;

}

更新日志：

用户贡献的笔记

（Nagdy – 4年前贡献）

例句:让我们在第二十七页首页上增加额外的部分。

默认情况下，TwentySeventeen主题的首页有4个部分。这个例子将使它们变为6

add_filter( ‘twentyseventeen_front_page_sections’, ‘prefix_custom_front_page_sections’ );

function prefix_custom_front_page_sections( $num_sections )

{

return 6;

}

（由mkormendy – 1年前贡献）

要将变量传递给被调用的筛选器函数，可以使用闭包(从PHP 5.3+开始)，当参数在原始编码的apply_filters中不可用时。例如:

return $myvar;

}, $priority_integer, $accepted_arguments_integer);

（由Rinku Y – 5年前贡献）

示例:显示自定义长度的文章摘录。

if( ! function_exists( ‘prefix_custom_excerpt_length’ ) )

{

function prefix_custom_excerpt_length( $length )

{

return 40;

}

}

add_filter( ‘excerpt_length’, ‘prefix_custom_excerpt_length’, 999 );

默认情况下，WordPress显示57个字符。您可以使用上述代码设置自定义长度。这次的长度是40。这是一个很好的和最简单的add_filter使用。

（由Xaibi Aslam于1年前贡献）

例如:如果你想在content中注入一个CLASS/ID CSS。让我们添加额外的类/ID来发布内容。

//Add Class/ID to Post Content

add_filter(‘the_content’, ‘xai_my_class’);

function xai_my_class($content)

{

//Replace the instance with the Class/ID markup.

$string = ‘<ul’; //your tag

$replace = ‘<ul class=”detail-list”‘; //add your class/id and tag

$content = str_replace( $string, $replace, $content );

return $content;

}

（由jonburnaby贡献- 12个月前）

回调函数$function_to_add在过滤器钩子触发之前不需要定义。这意味着:

1.dd_filter函数不检查$function_to_add是否存在

2.$function_to_add的函数语句可以在add_filter语句之后定义，即使是在一个条件语句(例如:if块)中，在add_filter函数执行之前，$function_to_add函数实际上并不存在

3.如果过滤器钩子从未触发，未定义的$function_to_add函数将不会作为错误报告

第三点需要在测试或质量控制中考虑

当过滤器钩子触发时，未定义的$function_to_add函数被报告为警告错误:

Warning: call_user_func_array() expects parameter 1 to be a valid callback, function ‘reg_public1’ not found or invalid function name in /var/www/example.com/public_html/wp-includes/class-wp-hook.php on line 288

（由biziclop贡献- 1个月前）

在特殊情况下，你必须在WordPress启动之前添加一个过滤器，你可以创建并预先填充全局$wp_filter数组，而不是使用尚未可用的add_filter(或add_action)函数:

// Instead of add_filter( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ):

$GLOBALS[‘wp_filter’][ $tag ][ $priority ][] = array(

‘function’ => $function_to_add,

‘accepted_args’ => $accepted_args

);

build_preinitialized_hooks将自动处理剩下的部分。

不过，要删除过滤器，只能使用remove_all_filters()函数。

（由Codex – 6年前贡献）

例子

filter img_caption_shortcode在media.php中使用如下调用:

// Allow plugins/themes to override the default caption template.

$output = apply_filters( ‘img_caption_shortcode’, ”, $attr, $content );

if ( $output != ” )

return $output;

目标过滤器函数将被调用，并带有三个参数:

” <=这通常是过滤器要修改的值

$attr
$content

为了让filter函数实际接收完整的参数列表，必须修改对add_filter()的调用，以指定形参列表上有3个参数。

add_filter(‘img_caption_shortcode’, ‘my_img_caption_shortcode_filter’,10,3);

/**

* Filter to replace the shortcode text with HTML5 compliant code

*

* @return text HTML content describing embedded figure

**/

function my_img_caption_shortcode_filter($val, $attr, $content = null)

{

extract( shortcode_atts( array(

‘id’ => ”,

‘align’ => ”,

‘width’ => ”,

‘caption’ => ”

), $attr ) );

if ( 1 > (int) $width || empty($caption) )

return $val;

$capid = ”;

if ( $id ) {

$id = esc_attr( $id );

$capid = ‘id=”figcaption_’ . $id . ‘” ‘;

$id = ‘id=”‘ . $id . ‘” aria-labelledby=”figcaption_’ . $id . ‘” ‘;

}

return ‘<figure ‘ . $id . ‘class=”wp-caption ‘ . esc_attr($align) . ‘” style=”width: ‘

. (10 + (int) $width) . ‘px”>’ . do_shortcode( $content ) . ‘<figcaption ‘ . $capid

. ‘class=”wp-caption-text”>’ . $caption . ‘</figcaption></figure>’;

}