This page redirects to an external site: https://developer.wordpress.org/reference/functions/add_filter/

Languages: English • Italiano • 日本語 Русский • (Add your language)

Description

Hook a function to a specific filter action.

• Glossary: Filters

Usage

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

Parameters

$tag

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

Default: None

$function_to_add

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

Default: None

$priority

(integer) (optional) 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.

Default: 10

$accepted_args

(integer) (optional) 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.

Default: 1

Return

The function returns true if the attempted function hook succeeds or false if not. There is no test that the function exists nor whether the $function_to_add is even a string. It is up to you to take care. This is done for optimization purposes, so everything is as quick as possible.

Example

The filter img_caption_shortcode is applied in media.php using the following call:

// Allow plugins/themes to override the default caption template.
$output = apply_filters('img_caption_shortcode', '', $attr, $content);
if ( $output != '' )
	return $output;

The target filter function will be called with three arguments:

• '' <= This is normally the value the filter will be modifying
• $attr
• $content

In order for the filter function to actually receive the full argument list, the call to add_filter() must be modified to specify there are 3 arguments on the parameter list.

add_filter('img_caption_shortcode', 'my_img_caption_shortcode_filter',10,3);

/**
 * Filter to replace the [caption] 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>';
}

Notes

• 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 the comment ID to each callback.

• 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 filter function.

• You can also pass a class method as a callback.

Static class method:

add_filter( 'media_upload_newtab', array( 'My_Class', 'media_upload_callback' ) );

Instance method:

add_filter( 'media_upload_newtab', array( $this, 'media_upload_callback' ) );

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

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.

Change Log

• Since: 0.71

Source File

add_filter() is located in wp-includes/plugin.php.

See Also

• A good explanation on Filter hooks on stackoverflow.com (2012-12-10)

Related

Filter Functions:

• has_filter()
• add_filter()
• apply_filters()
• current_filter()
• merge_filters()
• remove_filter()
• remove_all_filters()

External Resources

• WordPress for the adventurous: Plugin API