apply_filters_deprecated( string $hook_name, array $args, string $version, string $replacement = '', string $message = '' ): mixed
- Since
- 4.6.0
- Source
wp-includes/plugin.php:722
Description
When a filter hook is deprecated, the apply_filters() call is replaced with apply_filters_deprecated(), which triggers a deprecation notice and then fires the original filter hook.
Note: the value and extra arguments passed to the original apply_filters() call must be passed here to $args as an array. For example:
// Old filter.
return apply_filters( 'wpdocs_filter', $value, $extra_arg );
// Deprecated.
return apply_filters_deprecated( 'wpdocs_filter', array( $value, $extra_arg ), '4.9.0', 'wpdocs_new_filter' );Compatibility
- WordPress
- since 4.6.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.
$argsarray- Array of additional function arguments to be passed to apply_filters().
$versionstring- The version of WordPress that deprecated the hook.
$replacementstringoptional- The hook that should have been used. Default empty.Default:
'' $messagestringoptional- A message regarding the change. Default empty.Default:
''
Return value
mixed- The filtered value after all hooked functions are applied to it.
Performance profile
How much work a call to apply_filters_deprecated() 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
- 11–20
- Plugin surface
- 1 hook
- Called by
- 25
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 22.
Third-party callbacks on '{$hook_name}' run inside this call, and their cost is not bounded by anything here.
25 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_deprecated()this function does it
Further down the call graph this can also reach query, option, cache, serialize and transient. Those are the worst case, several calls deep and usually down an error path, not what a normal call pays.
What one call costs · 2 distinct outcomes
One number would be a lie: the work depends on which branch runs. These are every distinct cost apply_filters_deprecated() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
!has_filter() | 11 | has_filter() |
has_filter() | 20 | has_filter(), _deprecated_hook(), apply_filters_ref_array() |
Across PHP versions
Compiles the same on PHP 7.4, 8.1, 8.2, 8.3, 8.4, 8.5 and 8.6-dev: 22 instructions, 11–20 executed per call, 1 branch. 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.
Hooks and filters fired · 1
One hook fires while apply_filters_deprecated() runs, in this order:
- apply_filters( {$hook_name} )filterline 729 (+7 into the body)
Uses · 3
- has_filter()Checks if any filter has been registered for a hook.
- _deprecated_hook()Marks a deprecated action or filter hook as deprecated and throws a notice.
- apply_filters_ref_array()Calls the callback functions that have been added to a filter hook, specifying arguments in an array.
Used by · 25
- WP::build_query_string()Sets the query string property based off of the query variable property.
- WP_Http::_get_first_available_transport()Tests which transports are capable of supporting the request.
- WP_Privacy_Policy_Content::get_default_content()Returns the default suggested privacy policy content.
- WP_REST_Server::serve_request()Handles serving a REST API request.
- WP_Rewrite::mod_rewrite_rules()Retrieves mod_rewrite-formatted rewrite rules to write to .htaccess.
- WP_Rewrite::rewrite_rules()Constructs rewrite matches and queries from permalink structure.
- WP_Screen::render_screen_meta()Renders the screen's help section.
- WP_Site::get_details()Retrieves the details for this site.
- WP_Terms_List_Table::prepare_items()
- _WP_Editors::editor()Outputs the HTML for a single instance of the editor.
- _wp_privacy_send_erasure_fulfillment_notification()Notifies the user when their erasure request is fulfilled.
- _wp_privacy_send_request_confirmation_notification()Notifies the site administrator via email when a request is confirmed.
Show all 25
- block_editor_rest_api_preload()Preloads common data used with the block editor by specifying an array of REST API paths that will be preloaded for a given block editor context.
- get_allowed_block_types()Gets the list of allowed block types to use in the block editor.
- get_block_categories()Returns all the categories for block types that will be shown in the block editor.
- get_block_editor_settings()Returns the contextualized block editor settings for a selected editor context.
- get_blog_details()Retrieves the details for a blog from the blogs table and blog options.
- get_posts_by_author_sql()Retrieves the post SQL based on capability, author, and type.
- image_edit_apply_changes()Performs group of changes on Editor specified.
- login_header()Outputs the login page header.
- map_meta_cap()Maps a capability to the primitive capabilities required of the given user to satisfy the capability being checked.
- media_buttons()Adds the media button to the editor.
- validate_another_blog_signup()Validates a new site sign-up for an existing user.
- wp_save_image_file()Saves image to file.
- wp_stream_image()Streams image in WP_Image_Editor to browser.
Source code
function apply_filters_deprecated( $hook_name, $args, $version, $replacement = '', $message = '' ) { if ( ! has_filter( $hook_name ) ) { return $args[0]; } _deprecated_hook( $hook_name, $version, $replacement, $message ); return apply_filters_ref_array( $hook_name, $args );}Changelog
Introduced in 4.6.0. Unchanged from 6.7.7 through 7.1.0.
Signature, return type and hooks compared across 5 parsed releases.
About this page
- Parsed data
- Generated from the wordpress-develop 6.9.7 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.