apply_filters( string $hook_name, mixed $value, mixed $args ): mixed
- Since
- 0.71, 6.0.0
- Source
wp-includes/plugin.php:174
Pass a value through every callback attached to a filter hook with apply_filters() and get the filtered result back. Calling it with a new hook name is how you create a filter in your own plugin or theme; any arguments after $value are handed to callbacks as extra context.
Description
This function invokes all functions attached to filter hook $hook_name.
It is possible to create new filter hooks by simply calling this function, specifying the name of the new hook using the $hook_name parameter.
The function also allows for multiple additional arguments to be passed to hooks.
Example usage:
// The filter callback function.
function example_callback( $string, $arg1, $arg2 ) {
// (maybe) modify $string.
return $string;
}
add_filter( 'example_filter', 'example_callback', 10, 3 );
/*
* Apply the filters by calling the 'example_callback()' function
* that's hooked onto example_filter above.
*
* - 'example_filter' is the filter hook.
* - 'filter me' is the value being filtered.
* - $arg1 and $arg2 are the additional arguments passed to the callback.
$value = apply_filters( 'example_filter', 'filter me', $arg1, $arg2 );Compatibility
- WordPress
- since 6.0.0
- PHP
- 7.4–8.6-dev
- 6.7.7
- 6.8.8
- 6.9.7
- 7.0.4
- 7.1.0
Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.
Parameters
$hook_namestring- The name of the filter hook.
$valuemixed- The value to filter.
$argsmixed- Additional parameters to pass to the callback functions.
Return value
mixed- The filtered value after all hooked functions are applied to it.
Code examples
Every example is editable and runs in a real WordPress booted in your browser by WordPress Playground. Press Run, then edit the code: clicking away re-runs it. Nothing is sent anywhere until you do.
Make a plugin value filterable
Wrap an internal value in apply_filters() so other plugins and themes can override it.
function myshop_get_currency_symbol() {
$symbol = '$';
// Other code can change this via add_filter( 'myshop_currency_symbol', ... ).
return apply_filters( 'myshop_currency_symbol', $symbol );
}
echo esc_html( myshop_get_currency_symbol() );The result is whatever the last callback returns, so never assume the filtered value still has the original type; validate before using it.
Pass context arguments to callbacks
Send extra arguments after $value so callbacks can make decisions based on context like a post ID.
function myplugin_card_excerpt( $post_id ) {
$excerpt = wp_trim_words( get_the_excerpt( $post_id ), 20 );
// Callbacks receive the excerpt plus the post ID as context.
return apply_filters( 'myplugin_card_excerpt', $excerpt, $post_id );
}
echo esc_html( myplugin_card_excerpt( 42 ) );Only the first argument ($value) is filtered and returned; the extra arguments are read-only context, and callbacks only receive them if their add_filter() call sets $accepted_args high enough.
Performance profile
How much work a call to apply_filters() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.
- Cost class
- Trivial
- Scaling
- Constant
- Instructions
- 17–39
- Plugin surface
- None
- Called by
- 50
Touches nothing outside its own arguments.
No loop in the body: the same number of instructions runs whatever you pass in.
Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 47.
Nothing here hands control to plugin code.
50 places in core call this, so the cost is paid more often than your own code shows.
What it touches
- hookthird-party callbacks
apply_filters()this function does it
What one call costs · 6 distinct outcomes
One number would be a lie: the work depends on which branch runs. These are every distinct cost apply_filters() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
!isset($wp_filter) && !isset($wp_filter[$hook_name]) | 17–18 | none |
!isset($wp_filter[$hook_name]) | 20–21 | array_pop() |
!isset($wp_filter[$hook_name]) | 23–24 | _wp_call_all_hook() |
isset($wp_filter) && !isset($wp_filter[$hook_name]) | 26–27 | _wp_call_all_hook(), array_pop() |
!isset($wp_filter) && isset($wp_filter[$hook_name]) | 30–33 | array_unshift(), ->apply_filters(), array_pop() |
isset($wp_filter) && isset($wp_filter[$hook_name]) | 36–39 | _wp_call_all_hook(), array_unshift(), ->apply_filters(), array_pop() |
Across PHP versions
Compiles the same on PHP 7.4, 8.1, 8.2, 8.3, 8.4, 8.5 and 8.6-dev: 47 instructions, 17–39 executed per call, 5 branches. The work does not change between versions.
An instruction is not a fixed amount of time, so a matching count is not necessarily the same speed; what it rules out is a difference in the work itself.
Uses · 1
- _wp_call_all_hook()Calls the 'all' hook, which will process the functions hooked into it.
Used by · 50
- Bulk_Plugin_Upgrader_Skin::bulk_footer()Displays the footer following the bulk update process.
- Bulk_Theme_Upgrader_Skin::bulk_footer()Displays the footer following the bulk update process.
- Core_Upgrader::should_update_to_version()Determines if this WordPress Core version should update to an offered version or not.
- Core_Upgrader::upgrade()Upgrades WordPress core.
- Custom_Background::handle_upload()Handles an Image upload for the background image.
- Custom_Background::wp_set_background_image()
- Custom_Image_Header::ajax_header_crop()Gets attachment uploaded by Media Manager, crops it, then saves it as a new object. Returns JSON-encoded object details.
- Custom_Image_Header::insert_attachment()Inserts an attachment and its metadata.
- Custom_Image_Header::step_2()Displays second step of custom header image page.
- Custom_Image_Header::step_3()Displays third step of custom header image page.
- IXR_Message::parse()
- Language_Pack_Upgrader::async_upgrade()Asynchronously upgrades language packs after other upgrades have been made.
Show all 50
- Language_Pack_Upgrader_Skin::bulk_footer()Displays the footer following the bulk update process.
- Plugin_Installer_Skin::after()Performs an action following a plugin install.
- Plugin_Installer_Skin::do_overwrite()Checks if the plugin can be overwritten and outputs the HTML for overwriting a plugin on upload.
- Plugin_Upgrader_Skin::after()Performs an action following a single plugin update.
- Theme_Installer_Skin::after()Performs an action following a single theme install.
- Theme_Installer_Skin::do_overwrite()Checks if the theme can be overwritten and outputs the HTML for overwriting a theme on upload.
- Theme_Upgrader_Skin::after()Performs an action following a single theme update.
- TwentyTwenty_Non_Latin_Languages::get_non_latin_css()Gets custom CSS.
- TwentyTwenty_SVG_Icons::get_social_link_svg()GET SOCIAL LINK SVG Detects the social network from a URL and returns the SVG code for its icon.
- TwentyTwenty_SVG_Icons::get_svg()GET SVG CODE Gets the SVG code for the specified icon.
- TwentyTwenty_Walker_Page::start_el()Outputs the beginning of the current element in the tree.
- Twenty_Eleven_Ephemera_Widget::widget()Outputs the HTML for this widget.
- Twenty_Fourteen_Ephemera_Widget::enqueue_scripts()Enqueues scripts.
- Twenty_Fourteen_Ephemera_Widget::widget()Outputs the HTML for this widget.
- Twenty_Twenty_One_SVG_Icons::get_social_link_svg()Detects the social network from a URL and returns the SVG code for its icon.
- Twenty_Twenty_One_SVG_Icons::get_svg()Gets the SVG code for a given icon.
- WP::handle_404()Set the Headers for 404, if nothing is found for requested URL.
- WP::parse_request()Parses the request to find the correct WordPress query.
- WP::send_headers()Sends additional HTTP headers for caching, content type, etc.
- WP_AI_Client_Cache::get_cache_group()Retrieves the cache group used for cache operations, applying a filter for customization.
- WP_AI_Client_Prompt_Builder::__call()Magic method to proxy snake_case method calls to their PHP AI Client camelCase counterparts.
- WP_AI_Client_Prompt_Builder::__construct()Constructor.
- WP_Abilities_Registry::register()Registers a new ability.
- WP_Ability::check_permissions()Checks whether the ability has the necessary permissions.
- WP_Ability::do_execute()Executes the ability callback.
- WP_Ability::execute()Executes the ability after input validation and running a permission check.
- WP_Ability::normalize_input()Normalizes the input for the ability, applying the default value from the input schema when needed.
- WP_Ability::validate_input()Validates input data against the input schema.
- WP_Ability::validate_output()Validates output data against the output schema.
- WP_Ability_Categories_Registry::register()Registers a new ability category.
- WP_Automatic_Updater::after_plugin_theme_update()Checks whether an email should be sent after attempting plugin or theme updates.
- WP_Automatic_Updater::has_fatal_error()Performs a loopback request to check for potential fatal errors.
- WP_Automatic_Updater::is_disabled()Determines whether the entire automatic updater is disabled.
- WP_Automatic_Updater::is_vcs_checkout()Checks for version control checkouts.
- WP_Automatic_Updater::run()Kicks off the background update process, looping through all pending updates.
- WP_Automatic_Updater::send_core_update_notification_email()Notifies an administrator of a core update.
- WP_Automatic_Updater::send_debug_email()Prepares and sends an email of a full log of background update results, useful for debugging and geekery.
- WP_Automatic_Updater::send_email()Sends an email upon the completion or failure of a background core update.
Source code
function apply_filters( $hook_name, $value, ...$args ) { global $wp_filter, $wp_filters, $wp_current_filter; if ( ! isset( $wp_filters[ $hook_name ] ) ) { $wp_filters[ $hook_name ] = 1; } else { ++$wp_filters[ $hook_name ]; } // Do 'all' actions first. if ( isset( $wp_filter['all'] ) ) { $wp_current_filter[] = $hook_name; $all_args = func_get_args(); // phpcs:ignore PHPCompatibility.FunctionUse.ArgumentFunctionsReportCurrentValue.NeedsInspection _wp_call_all_hook( $all_args ); } if ( ! isset( $wp_filter[ $hook_name ] ) ) { if ( isset( $wp_filter['all'] ) ) { array_pop( $wp_current_filter ); } return $value; } if ( ! isset( $wp_filter['all'] ) ) { $wp_current_filter[] = $hook_name; } // Pass the value to WP_Hook. array_unshift( $args, $value ); $filtered = $wp_filter[ $hook_name ]->apply_filters( $value, $args ); array_pop( $wp_current_filter ); return $filtered;}Changelog
Introduced in 0.71. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
...$args parameter by adding it to the function signature.from the docblockAbout this page
- Parsed data
- Generated from the wordpress-develop 7.1.0 tag, from
src/wp-includes/plugin.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it. - Corrections
- Something wrong on this page? Report it and it gets fixed in the next regeneration.