add_filter( string $hook_name, callable $callback, int $priority = 10, int $accepted_args = 1 ): true

Adds a callback function to a filter hook.

Contents

Description

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' );

Bound callbacks can accept from none to the total number of arguments passed as parameters in the corresponding apply_filters() call.

In other words, if an apply_filters() call passes four total arguments, callbacks bound to it can accept none (the same as 1) of the arguments or up to four. The important part is that the $accepted_args value must reflect the number of arguments the bound callback actually opted to accept. If no arguments were accepted by the callback that is considered to be the same as accepting 1 argument. For example:

// 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:_ 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.

Top ↑

Parameters

$hook_name string Required
The name of the filter to add the callback to.
$callback callable Required
The callback to be run when the filter is applied.
$priority int Optional
Used to specify the order in which the functions associated with a particular filter 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 int Optional
The number of arguments the function accepts.

Default: 1

Top ↑

Return

true Always returns true.

Top ↑

More Information

  • 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 '<strong>' . $title . '</strong>'; } );

Top ↑

Source

File: wp-includes/plugin.php. View all references 

function add_filter( $hook_name, $callback, $priority = 10, $accepted_args = 1 ) {
	global $wp_filter;

	if ( ! isset( $wp_filter[ $hook_name ] ) ) {
		$wp_filter[ $hook_name ] = new WP_Hook();
	}

	$wp_filter[ $hook_name ]->add_filter( $hook_name, $callback, $priority, $accepted_args );

	return true;
}

View on Trac View on GitHub

Top ↑

Top ↑

Used By

Used By
Used By Description
WP_REST_Menu_Items_Controller::prepare_item_for_response() wp-includes/rest-api/endpoints/class-wp-rest-menu-items-controller.php

Prepares a single post output for response.
WP_REST_Global_Styles_Controller::prepare_item_for_response() wp-includes/rest-api/endpoints/class-wp-rest-global-styles-controller.php

Prepare a global styles config output for response.
_add_default_theme_supports() wp-includes/theme.php

Adds default theme supports for block themes when the ‘setup_theme’ action fires.
_add_template_loader_filters() wp-includes/block-template.php

Adds necessary filters to use ‘wp_template’ posts instead of theme template files.
wp_enqueue_block_style() wp-includes/script-loader.php

Enqueues a stylesheet for a specific block.
WP_Widget_Block::__construct() wp-includes/widgets/class-wp-widget-block.php

Sets up a new Block widget instance.
wp_enqueue_global_styles() wp-includes/script-loader.php

Enqueues the global styles defined via theme.json.
WP_Sitemaps_Renderer::check_for_simple_xml_availability() wp-includes/sitemaps/class-wp-sitemaps-renderer.php

Checks for the availability of the SimpleXML extension and errors if missing.
WP_Sitemaps::init() wp-includes/sitemaps/class-wp-sitemaps.php

Initiates all sitemap functionality.
wp_pre_kses_block_attributes() wp-includes/formatting.php

Removes non-allowable HTML from parsed block attribute values when filtering in the post context.
enqueue_block_styles_assets() wp-includes/script-loader.php

Function responsible for enqueuing the styles required for block styles functionality on the editor and on the frontend.
WP_Site_Health::__construct() wp-admin/includes/class-wp-site-health.php

WP_Site_Health constructor.
wp_init_targeted_link_rel_filters() wp-includes/formatting.php

Adds all filters modifying the rel attribute of targeted links.
wp_get_active_and_valid_themes() wp-includes/load.php

Retrieves an array of active and valid themes.
update_sitemeta_cache() wp-includes/ms-site.php

Updates metadata cache for list of site IDs.
WP_REST_Post_Search_Handler::prepare_item() wp-includes/rest-api/search/class-wp-rest-post-search-handler.php

Prepares the search result for a given ID.
do_blocks() wp-includes/blocks.php

Parses dynamic blocks out of post_content and re-renders them.
_restore_wpautop_hook() wp-includes/blocks.php

If do_blocks() needs to remove wpautop() from the the_content filter, this re-adds it afterwards, for subsequent the_content usage.
wpdb::placeholder_escape() wp-includes/class-wpdb.php

Generates and returns a placeholder escape string for use in queries returned by ::prepare().
WP_Widget_Custom_HTML::widget() wp-includes/widgets/class-wp-widget-custom-html.php

Outputs the content for the current Custom HTML widget instance.
WP_Widget_Media::_register_one() wp-includes/widgets/class-wp-widget-media.php

Add hooks while registering all widget instances of this widget class.
WP_Widget_Media_Video::render_media() wp-includes/widgets/class-wp-widget-media-video.php

Render the media on the frontend.
WP_Customize_Manager::save_changeset_post() wp-includes/class-wp-customize-manager.php

Saves the post for the loaded changeset.
WP_REST_Attachments_Controller::prepare_items_query() wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

Determines the allowed query_vars for a get_items() response and prepares for WP_Query.
WP_REST_Posts_Controller::prepare_item_for_response() wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php

Prepares a single post output for response.
WP_REST_Posts_Controller::get_item_permissions_check() wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php

Checks if a given request has access to read a post.
WP_REST_Posts_Controller::get_items() wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php

Retrieves a collection of posts.
WP_REST_Comments_Controller::check_read_post_permission() wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php

Checks if the post can be read.
WP_Locale_Switcher::init() wp-includes/class-wp-locale-switcher.php

Initializes the locale switcher.
WP_Taxonomy::add_hooks() wp-includes/class-wp-taxonomy.php

Registers the ajax callback for the meta box.
WP_Customize_Nav_Menus::insert_auto_draft_post() wp-includes/class-wp-customize-nav-menus.php

Adds a new auto-draft post.
WP_Customize_Custom_CSS_Setting::preview() wp-includes/customize/class-wp-customize-custom-css-setting.php

Add filter to preview post value.
WP_Metadata_Lazyloader::queue_objects() wp-includes/class-wp-metadata-lazyloader.php

Adds objects to the metadata lazy-load queue.
WP_Customize_Widgets::render_widget_partial() wp-includes/class-wp-customize-widgets.php

Renders a specific widget using the supplied sidebar arguments.
WP_Customize_Widgets::selective_refresh_init() wp-includes/class-wp-customize-widgets.php

Adds hooks for selective refresh.
rest_api_default_filters() wp-includes/rest-api.php

Registers the default REST API filters.
wp_handle_comment_submission() wp-includes/comment.php

Handles the submission of a comment, usually posted to wp-comments-post.php via a comment form.
WP_Screen::render_view_mode() wp-admin/includes/class-wp-screen.php

Renders the list table view mode preferences.
WP_Customize_Nav_Menu_Setting::update() wp-includes/customize/class-wp-customize-nav-menu-setting.php

Create/update the nav_menu term for this setting.
WP_Customize_Nav_Menu_Setting::preview() wp-includes/customize/class-wp-customize-nav-menu-setting.php

Handle previewing the setting.
WP_Customize_Nav_Menu_Item_Setting::update() wp-includes/customize/class-wp-customize-nav-menu-item-setting.php

Creates/updates the nav_menu_item post for this setting.
WP_Customize_Nav_Menu_Item_Setting::preview() wp-includes/customize/class-wp-customize-nav-menu-item-setting.php

Handle previewing the setting.
WP_Customize_Nav_Menus_Panel::render_screen_options() wp-includes/customize/class-wp-customize-nav-menus-panel.php

Render screen options for Menus.
WP_Customize_Nav_Menus::customize_preview_init() wp-includes/class-wp-customize-nav-menus.php

Adds hooks for the Customizer preview.
WP_Customize_Nav_Menus::customize_register() wp-includes/class-wp-customize-nav-menus.php

Adds the customizer settings and controls.
WP_Customize_Nav_Menus::__construct() wp-includes/class-wp-customize-nav-menus.php

Constructor.
WP_Site_Icon::get_post_metadata() wp-admin/includes/class-wp-site-icon.php

Adds custom image sizes when meta data for an image is requested, that happens to be used as Site Icon.
WP_Site_Icon::__construct() wp-admin/includes/class-wp-site-icon.php

Registers actions and filters.
wp_ajax_crop_image() wp-admin/includes/ajax-actions.php

Ajax handler for cropping an image.
wp_edit_attachments_query_vars() wp-admin/includes/post.php

Returns the query variables for the current attachments request.
_WP_List_Table_Compat::__construct() wp-admin/includes/class-wp-list-table-compat.php

Constructor.
login_header() wp-login.php

Output the login page header.
WP_Automatic_Updater::update() wp-admin/includes/class-wp-automatic-updater.php

Updates an item, if appropriate.
Language_Pack_Upgrader::bulk_upgrade() wp-admin/includes/class-language-pack-upgrader.php

Bulk upgrade language packs.
Theme_Upgrader::check_parent_theme_filter() wp-admin/includes/class-theme-upgrader.php

Check if a child theme is being installed and we need to install its parent.
Theme_Upgrader::install() wp-admin/includes/class-theme-upgrader.php

Install a theme package.
Theme_Upgrader::upgrade() wp-admin/includes/class-theme-upgrader.php

Upgrade a theme.
Theme_Upgrader::bulk_upgrade() wp-admin/includes/class-theme-upgrader.php

Upgrade several themes at once.
Plugin_Upgrader::bulk_upgrade() wp-admin/includes/class-plugin-upgrader.php

Bulk upgrade several plugins at once.
Plugin_Upgrader::install() wp-admin/includes/class-plugin-upgrader.php

Install a plugin package.
Plugin_Upgrader::upgrade() wp-admin/includes/class-plugin-upgrader.php

Upgrade a plugin.
WP_Screen::render_per_page_options() wp-admin/includes/class-wp-screen.php

Renders the items per page option.
export_wp() wp-admin/includes/export.php

Generates the WXR export file for download.
wp_update_core() wp-admin/includes/deprecated.php

This was once used to kick-off the Core Updater.
wp_update_plugin() wp-admin/includes/deprecated.php

This was once used to kick-off the Plugin Updater.
wp_update_theme() wp-admin/includes/deprecated.php

This was once used to kick-off the Theme Updater.
WP_List_Table::__construct() wp-admin/includes/class-wp-list-table.php

Constructor.
wp_dashboard_setup() wp-admin/includes/dashboard.php

Registers dashboard widgets.
register_setting() wp-includes/option.php

Registers a setting and its data.
media_upload_type_form() wp-admin/includes/media.php

Outputs the legacy media upload form for a given media type.
media_upload_gallery_form() wp-admin/includes/media.php

Adds gallery form to upload iframe.
media_upload_library_form() wp-admin/includes/media.php

Outputs the legacy media upload form for the media library.
wp_ajax_query_attachments() wp-admin/includes/ajax-actions.php

Ajax handler for querying attachments.
wp_ajax_replyto_comment() wp-admin/includes/ajax-actions.php

Ajax handler for replying to a comment.
wp_link_manager_disabled_message() wp-admin/includes/bookmark.php

Outputs the ‘disabled’ message for the WordPress Link Manager.
WP_Media_List_Table::display_rows() wp-admin/includes/class-wp-media-list-table.php
WP_Importer::get_page() wp-admin/includes/class-wp-importer.php

GET URL
WP_Comments_List_Table::__construct() wp-admin/includes/class-wp-comments-list-table.php

Constructor.
wp_nav_menu_setup() wp-admin/includes/nav-menu.php

Register nav menu meta boxes and advanced menu items.
wp_list_widget_controls() wp-admin/includes/widgets.php

Show the widgets and their settings for a sidebar.
WP_Posts_List_Table::display_rows() wp-admin/includes/class-wp-posts-list-table.php
do_core_upgrade() wp-admin/update-core.php

Upgrade WordPress core display.
WP_Customize_Manager::customize_preview_init() wp-includes/class-wp-customize-manager.php

Prints JavaScript settings.
WP_Customize_Manager::start_previewing_theme() wp-includes/class-wp-customize-manager.php

If the theme to be previewed isn’t the active theme, add filter callbacks to swap it out at runtime.
WP_Customize_Manager::__construct() wp-includes/class-wp-customize-manager.php

Constructor.
kses_init_filters() wp-includes/kses.php

Adds all KSES input form content filters.
_default_wp_die_handler() wp-includes/functions.php

Kills WordPress execution and displays HTML page with an error message.
WP_Widget_Text::widget() wp-includes/widgets/class-wp-widget-text.php

Outputs the content for the current Text widget instance.
WP_Widget_Text::form() wp-includes/widgets/class-wp-widget-text.php

Outputs the Text widget settings form.
WP_Embed::__construct() wp-includes/class-wp-embed.php

Constructor
WP_oEmbed::__construct() wp-includes/class-wp-oembed.php

Constructor.
add_action() wp-includes/plugin.php

Adds a callback function to an action hook.
WP_Customize_Setting::__construct() wp-includes/class-wp-customize-setting.php

Constructor.
WP_Customize_Setting::preview() wp-includes/class-wp-customize-setting.php

Add filters to supply the setting’s value when accessed.
wp_signon() wp-includes/user.php

Authenticates and logs a user in with ‘remember’ capability.
_set_preview() wp-includes/revision.php

Sets up the post object for preview based on the post autosave.
_show_post_preview() wp-includes/revision.php

Filters the latest content for preview from the post autosave.
ms_upload_constants() wp-includes/ms-default-constants.php

Defines Multisite upload constants.
Walker_Comment::start_el() wp-includes/class-walker-comment.php

Starts the element output.
WP_Customize_Widgets::start_capturing_option_updates() wp-includes/class-wp-customize-widgets.php

Begins keeping track of changes to widget options, caching new values.
WP_Customize_Widgets::capture_filter_pre_update_option() wp-includes/class-wp-customize-widgets.php

Pre-filters captured option values before updating.
WP_Customize_Widgets::__construct() wp-includes/class-wp-customize-widgets.php

Initial loader.
WP_Customize_Widgets::override_sidebars_widgets_for_theme_switch() wp-includes/class-wp-customize-widgets.php

Override sidebars_widgets for theme switch.
WP_Customize_Widgets::customize_register() wp-includes/class-wp-customize-widgets.php

Registers Customizer settings and controls for all sidebars and widgets.
wp_update_comment() wp-includes/comment.php

Updates an existing comment in the database.
check_comment_flood_db() wp-includes/comment.php

Hooks WP’s native database-based comment-flood check.
register_meta() wp-includes/meta.php

Registers a meta key.
_WP_Editors::editor() wp-includes/class-wp-editor.php

Outputs the HTML for a single instance of the editor.
Show 103 more used by Hide more used by

Top ↑

Changelog

Changelog
Version Description
0.71 Introduced.

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 11You must log in to vote on the helpfulness of this note
    Contributed by Nagdy —

    Example: Let’s add extra sections to TwentySeventeen Front page.
    By default, TwentySeventeen theme has 4 sections for the front page. This example will make them 6

    add_filter( 'twentyseventeen_front_page_sections', 'prefix_custom_front_page_sections' );
	
function prefix_custom_front_page_sections( $num_sections )
{
		return 6;
}
  2. Skip to note 2 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note
    Contributed by mkormendy —

    To pass a variable to the called function of the filter, you can use closures (since PHP 5.3+) when the argument is not available in the original coded apply_filters. For example:

    add_filter('wp_footer', function($arguments) use ($myvar) { 
    return $myvar;
}, $priority_integer, $accepted_arguments_integer);
  3. Skip to note 3 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
    Contributed by Rinku Y —

    Example: Let display custom length of post excerpt.

    if( ! function_exists( 'prefix_custom_excerpt_length' ) )
{
	function prefix_custom_excerpt_length( $length )
	{
		return 40;
	}
}
add_filter( 'excerpt_length', 'prefix_custom_excerpt_length', 999 );

    By default, WordPress display 57 character. you can set custom length using above code. this time except length will be 40. it is a nice and easiest use of add_filter.

  4. Skip to note 4 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
    Contributed by Xaib Aslam —

    Example: If you want to inject a CLASS/ID CSS in content. Let’s add extra CLASS/ID to post content.

    //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;
}
  5. Skip to note 5 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
    Contributed by biziclop —

    In the special case you have to add a filter before WordPress starts, you can create and pre-populate the global $wp_filter array instead of using the not-yet available add_filter (or add_action) function:

    // 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
);

    WP_Hook::build_preinitialized_hooks will automatically take care of the rest.
    Though to remove your filter, you can only use the remove_all_filters() function.

  6. Skip to note 6 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note
    Contributed by jonburnaby —

    The Callback $function_to_add need not be defined until the Filter hook fires. This means that:

    1. The add_filter function does not check that $function_to_add exists
    2. The function statement for $function_to_add can be defined after the add_filter statement, even in a conditional (e.g. – if block) where the $function_to_add function does not actually exist until after the add_filter function executes
    3. If the Filter hook never fires, an undefined $function_to_add function will not be reported as an error

    Point 3 needs to be considered during Testing or Quality Control

    An undefined $function_to_add function detected when a Filter hook fires is reported as a Warning error:
    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

  7. Skip to note 7 content
    You must log in to vote on the helpfulness of this noteVote results for this note: -5You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    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>';
}

You must log in before being able to contribute a note or feedback.