add_filter() WordPress Function

The add_filter() function is used to add a new filter to a WordPress action or filter.

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

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 value: 10

$accepted_args

(int)(Optional) The number of arguments the function accepts.

Default value: 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

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

Expand full source codeCollapse full source codeView on TracView on GitHub

Top ↑

Top ↑

Used By

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

Prepares a single post output for response.

wp-includes/rest-api/endpoints/class-wp-rest-global-styles-controller.php:WP_REST_Global_Styles_Controller::prepare_item_for_response()

Prepare a global styles config output for response.

wp-includes/theme.php:_add_default_theme_supports()

Adds default theme supports for block themes when the ‘setup_theme’ action fires.

wp-includes/block-template.php:_add_template_loader_filters()

Adds necessary filters to use ‘wp_template’ posts instead of theme template files.

wp-includes/script-loader.php:wp_enqueue_block_style()

Enqueues a stylesheet for a specific block.

wp-includes/widgets/class-wp-widget-block.php:WP_Widget_Block::__construct()

Sets up a new Block widget instance.

wp-includes/sitemaps/class-wp-sitemaps-renderer.php:WP_Sitemaps_Renderer::check_for_simple_xml_availability()

Checks for the availability of the SimpleXML extension and errors if missing.

wp-includes/sitemaps/class-wp-sitemaps.php:WP_Sitemaps::init()

Initiates all sitemap functionality.

wp-includes/formatting.php:wp_pre_kses_block_attributes()

Removes non-allowable HTML from parsed block attribute values when filtering in the post context.

wp-includes/script-loader.php:enqueue_block_styles_assets()

Function responsible for enqueuing the styles required for block styles functionality on the editor and on the frontend.

wp-admin/includes/class-wp-site-health.php:WP_Site_Health::__construct()

WP_Site_Health constructor.

wp-includes/formatting.php:wp_init_targeted_link_rel_filters()

Adds all filters modifying the rel attribute of targeted links.

wp-includes/load.php:wp_get_active_and_valid_themes()

Retrieves an array of active and valid themes.

wp-includes/ms-site.php:update_sitemeta_cache()

Updates metadata cache for list of site IDs.

wp-includes/rest-api/search/class-wp-rest-post-search-handler.php:WP_REST_Post_Search_Handler::prepare_item()

Prepares the search result for a given ID.

wp-includes/blocks.php:do_blocks()

Parses dynamic blocks out of post_content and re-renders them.

wp-includes/blocks.php:_restore_wpautop_hook()

If do_blocks() needs to remove wpautop() from the the_content filter, this re-adds it afterwards, for subsequent the_content usage.

wp-includes/wp-db.php:wpdb::placeholder_escape()

Generates and returns a placeholder escape string for use in queries returned by ::prepare().

wp-includes/widgets/class-wp-widget-custom-html.php:WP_Widget_Custom_HTML::widget()

Outputs the content for the current Custom HTML widget instance.

wp-includes/widgets/class-wp-widget-media.php:WP_Widget_Media::_register_one()

Add hooks while registering all widget instances of this widget class.

wp-includes/widgets/class-wp-widget-media-video.php:WP_Widget_Media_Video::render_media()

Render the media on the frontend.

wp-includes/class-wp-customize-manager.php:WP_Customize_Manager::save_changeset_post()

Saves the post for the loaded changeset.

wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php:WP_REST_Attachments_Controller::prepare_items_query()

Determines the allowed query_vars for a get_items() response and prepares for WP_Query.

wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php:WP_REST_Posts_Controller::prepare_item_for_response()

Prepares a single post output for response.

wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php:WP_REST_Posts_Controller::get_item_permissions_check()

Checks if a given request has access to read a post.

wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php:WP_REST_Posts_Controller::get_items()

Retrieves a collection of posts.

wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php:WP_REST_Comments_Controller::check_read_post_permission()

Checks if the post can be read.

wp-includes/class-wp-locale-switcher.php:WP_Locale_Switcher::init()

Initializes the locale switcher.

wp-includes/class-wp-taxonomy.php:WP_Taxonomy::add_hooks()

Registers the ajax callback for the meta box.

wp-includes/class-wp-customize-nav-menus.php:WP_Customize_Nav_Menus::insert_auto_draft_post()

Adds a new auto-draft post.

wp-includes/customize/class-wp-customize-custom-css-setting.php:WP_Customize_Custom_CSS_Setting::preview()

Add filter to preview post value.

wp-includes/class-wp-metadata-lazyloader.php:WP_Metadata_Lazyloader::queue_objects()

Adds objects to the metadata lazy-load queue.

wp-includes/class-wp-customize-widgets.php:WP_Customize_Widgets::render_widget_partial()

Renders a specific widget using the supplied sidebar arguments.

wp-includes/class-wp-customize-widgets.php:WP_Customize_Widgets::selective_refresh_init()

Adds hooks for selective refresh.

wp-includes/rest-api.php:rest_api_default_filters()

Registers the default REST API filters.

wp-includes/comment.php:wp_handle_comment_submission()

Handles the submission of a comment, usually posted to wp-comments-post.php via a comment form.

wp-admin/includes/class-wp-screen.php:WP_Screen::render_view_mode()

Render the list table view mode preferences.

wp-includes/customize/class-wp-customize-nav-menu-setting.php:WP_Customize_Nav_Menu_Setting::update()

Create/update the nav_menu term for this setting.

wp-includes/customize/class-wp-customize-nav-menu-setting.php:WP_Customize_Nav_Menu_Setting::preview()

Handle previewing the setting.

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

Creates/updates the nav_menu_item post for this setting.

wp-includes/customize/class-wp-customize-nav-menu-item-setting.php:WP_Customize_Nav_Menu_Item_Setting::preview()

Handle previewing the setting.

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

Render screen options for Menus.

wp-includes/class-wp-customize-nav-menus.php:WP_Customize_Nav_Menus::customize_preview_init()

Adds hooks for the Customizer preview.

wp-includes/class-wp-customize-nav-menus.php:WP_Customize_Nav_Menus::customize_register()

Adds the customizer settings and controls.

wp-includes/class-wp-customize-nav-menus.php:WP_Customize_Nav_Menus::__construct()

Constructor.

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

Adds custom image sizes when meta data for an image is requested, that happens to be used as Site Icon.

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

Registers actions and filters.

wp-admin/includes/ajax-actions.php:wp_ajax_crop_image()

Ajax handler for cropping an image.

wp-admin/includes/post.php:wp_edit_attachments_query_vars()

Returns the query variables for the current attachments request.

wp-admin/includes/class-wp-list-table-compat.php:_WP_List_Table_Compat::__construct()

Constructor.

wp-login.php:login_header()

Output the login page header.

wp-admin/includes/class-wp-automatic-updater.php:WP_Automatic_Updater::update()

Updates an item, if appropriate.

wp-admin/includes/class-language-pack-upgrader.php:Language_Pack_Upgrader::bulk_upgrade()

Bulk upgrade language packs.

wp-admin/includes/class-plugin-upgrader.php:Plugin_Upgrader::bulk_upgrade()

Bulk upgrade several plugins at once.

wp-admin/includes/class-theme-upgrader.php:Theme_Upgrader::check_parent_theme_filter()

Check if a child theme is being installed and we need to install its parent.

wp-admin/includes/class-theme-upgrader.php:Theme_Upgrader::install()

Install a theme package.

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

Upgrade a theme.

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

Upgrade several themes at once.

wp-admin/includes/class-plugin-upgrader.php:Plugin_Upgrader::install()

Install a plugin package.

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

Upgrade a plugin.

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

Render the items per page option

wp-admin/includes/export.php:export_wp()

Generates the WXR export file for download.

wp-admin/includes/deprecated.php:wp_update_core()

This was once used to kick-off the Core Updater.

wp-admin/includes/deprecated.php:wp_update_plugin()

This was once used to kick-off the Plugin Updater.

wp-admin/includes/deprecated.php:wp_update_theme()

This was once used to kick-off the Theme Updater.

wp-admin/includes/class-wp-list-table.php:WP_List_Table::__construct()

Constructor.

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

Registers dashboard widgets.

wp-includes/option.php:register_setting()

Registers a setting and its data.

wp-admin/includes/media.php:media_upload_type_form()

Outputs the legacy media upload form for a given media type.

wp-admin/includes/media.php:media_upload_gallery_form()

Adds gallery form to upload iframe.

wp-admin/includes/media.php:media_upload_library_form()

Outputs the legacy media upload form for the media library.

wp-admin/includes/ajax-actions.php:wp_ajax_query_attachments()

Ajax handler for querying attachments.

wp-admin/includes/ajax-actions.php:wp_ajax_replyto_comment()

Ajax handler for replying to a comment.

wp-admin/includes/bookmark.php:wp_link_manager_disabled_message()

Outputs the ‘disabled’ message for the WordPress Link Manager.

wp-admin/includes/class-wp-media-list-table.php:WP_Media_List_Table::display_rows()
wp-admin/includes/class-wp-importer.php:WP_Importer::get_page()

GET URL

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

Constructor.

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

Register nav menu meta boxes and advanced menu items.

wp-admin/includes/widgets.php:wp_list_widget_controls()

Show the widgets and their settings for a sidebar.

wp-admin/includes/class-wp-posts-list-table.php:WP_Posts_List_Table::display_rows()
wp-admin/update-core.php:do_core_upgrade()

Upgrade WordPress core display.

wp-includes/class-wp-customize-manager.php:WP_Customize_Manager::customize_preview_init()

Prints JavaScript settings.

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

If the theme to be previewed isn’t the active theme, add filter callbacks to swap it out at runtime.

wp-includes/class-wp-customize-manager.php:WP_Customize_Manager::__construct()

Constructor.

wp-includes/kses.php:kses_init_filters()

Adds all KSES input form content filters.

wp-includes/functions.php:_default_wp_die_handler()

Kills WordPress execution and displays HTML page with an error message.

wp-includes/widgets/class-wp-widget-text.php:WP_Widget_Text::widget()

Outputs the content for the current Text widget instance.

wp-includes/widgets/class-wp-widget-text.php:WP_Widget_Text::form()

Outputs the Text widget settings form.

wp-includes/class-wp-embed.php:WP_Embed::__construct()

Constructor

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

Constructor.

wp-includes/plugin.php:add_action()

Adds a callback function to an action hook.

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

Constructor.

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

Add filters to supply the setting’s value when accessed.

wp-includes/user.php:wp_signon()

Authenticates and logs a user in with ‘remember’ capability.

wp-includes/revision.php:_set_preview()

Sets up the post object for preview based on the post autosave.

wp-includes/revision.php:_show_post_preview()

Filters the latest content for preview from the post autosave.

wp-includes/ms-default-constants.php:ms_upload_constants()

Defines Multisite upload constants.

wp-includes/class-walker-comment.php:Walker_Comment::start_el()

Starts the element output.

wp-includes/class-wp-customize-widgets.php:WP_Customize_Widgets::start_capturing_option_updates()

Begins keeping track of changes to widget options, caching new values.

wp-includes/class-wp-customize-widgets.php:WP_Customize_Widgets::capture_filter_pre_update_option()

Pre-filters captured option values before updating.

wp-includes/class-wp-customize-widgets.php:WP_Customize_Widgets::__construct()

Initial loader.

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

Override sidebars_widgets for theme switch.

wp-includes/class-wp-customize-widgets.php:WP_Customize_Widgets::customize_register()

Registers Customizer settings and controls for all sidebars and widgets.

wp-includes/comment.php:check_comment_flood_db()

Hooks WP’s native database-based comment-flood check.

wp-includes/meta.php:register_meta()

Registers a meta key.

wp-includes/class-wp-editor.php:_WP_Editors::editor()

Outputs the HTML for a single instance of the editor.

Show 101 more used byHide more used by

Top ↑

Changelog

Changelog
VersionDescription
0.71Introduced.
Download the latest version of WordPress from https://wordpress.org/

The content displayed on this page has been created in part by processing WordPress source code files which are made available under the GPLv2 (or a later version) license by the Free Software Foundation. In addition to this, the content includes user-written examples and information. All material is subject to review and curation by the WPPaste.com community.