_deprecated_argument( string $function_name, string $version, string $message = '' )
- Since
- 3.0.0, 5.4.0, 5.4.0
- Source
wp-includes/functions.php:5973
Fires the deprecated_argument_run action for a legacy function argument and raises an E_USER_DEPRECATED notice when WP_DEBUG is enabled. It does not check whether the argument was actually used, the caller must test that first and only call this function when the deprecated value was supplied. Pair it with the deprecated_argument_trigger_error filter to control whether the on-screen notice appears, or use _deprecated_function when an entire function, rather than one of its arguments, is being retired.
Description
This function is to be used whenever a deprecated function argument is used.
Before this function is called, the argument must be checked for whether it was used by comparing it to its default value or evaluating whether it is empty.
For example:
if ( ! empty( $deprecated ) ) {
_deprecated_argument( __FUNCTION__, '3.0.0' );
}There is a 'deprecated_argument_run' hook that will be called that can be used to get the backtrace up to what file and function used the deprecated argument.
The current behavior is to trigger a user error if WP_DEBUG is true.
Compatibility
- WordPress
- since 5.4.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
$function_namestring- The function that was called.
$versionstring- The version of WordPress that deprecated the argument used.
$messagestringoptional- A message regarding the change. Default empty string.Default:
''
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.
Warn developers when a legacy argument is still being passed to a custom function
A shop helper used to accept a raw meta key as its second argument and now ignores it, so it reports the change whenever that argument is still supplied.
add_action( 'deprecated_argument_run', function( $function_name, $message, $version ) {
printf( 'Deprecated argument in %s() since %s: %s', esc_html( $function_name ), esc_html( $version ), esc_html( $message ) );
}, 10, 3 );
function shop_get_product_price( $post_id, $legacy_meta_key = null ) {
if ( ! empty( $legacy_meta_key ) ) {
_deprecated_argument( __FUNCTION__, '5.4.0', 'The meta key is now fixed to "price" and no longer configurable.' );
}
return get_post_meta( $post_id, 'price', true );
}
echo '<p>Price: ' . esc_html( shop_get_product_price( 2, 'price' ) ) . '</p>';The empty() check on $legacy_meta_key happens before the call, which is the pattern _deprecated_argument expects every caller to follow.
Suppress the on-screen deprecation notice while still logging it
Some hosts run with WP_DEBUG off in production, so the deprecated_argument_run action is used to capture the message instead of relying on the notice.
add_filter( 'deprecated_argument_trigger_error', '__return_false' );
add_action( 'deprecated_argument_run', function( $function_name, $message, $version ) {
echo '<p>Logged: ' . esc_html( $function_name ) . ' (' . esc_html( $version ) . ') - ' . esc_html( $message ) . '</p>';
} );
_deprecated_argument( 'legacy_widget_render', '3.0.0', 'Pass widget options as an array, not as separate arguments.' );
echo '<p>Notice suppressed but the action still ran.</p>';Returning false from deprecated_argument_trigger_error stops the E_USER_DEPRECATED trigger even when WP_DEBUG is true, but the action fires regardless of that filter.
Common problems and fixes · 3
- Why does _deprecated_argument not display anything on my site?
- Do I need to check the argument's value before calling this function?
- How do I include the actual deprecated value in the notice?
Why does _deprecated_argument not display anything on my site?
Do I need to check the argument's value before calling this function?
if ( ! empty( $deprecated_argument ) ) {
_deprecated_argument( __FUNCTION__, '5.4.0' );
}
``How do I include the actual deprecated value in the notice?
Alternatives and related functions
_deprecated_function- When an entire function or method is being phased out rather than just one of its parameters.
_deprecated_hook- When an action or filter hook itself is deprecated instead of an argument passed to a function.
_deprecated_constructor- When a class's old-style PHP4 constructor is deprecated in favor of __construct().
_doing_it_wrong- When the code is being misused in a way that is not simply a deprecated argument, such as calling it too early or with an invalid combination of values.
Performance profile
How much work a call to _deprecated_argument() 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
- 12–38
- Plugin surface
- 2 hooks
- 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 63.
Third-party callbacks on 'deprecated_argument_run', 'deprecated_argument_trigger_error' run inside this call, and their cost is not bounded by anything here.
50 places in core call this, so the cost is paid more often than your own code shows.
What it touches
- hookthird-party callbacks
do_action()called directly
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 · 4 distinct outcomes
One number would be a lie: the work depends on which branch runs. These are every distinct cost _deprecated_argument() can have, taken from its control-flow graph on PHP 8.5.
| When | Instructions | Calls it makes |
|---|---|---|
| always | 12 | do_action() |
!apply_filters() | 17 | do_action(), apply_filters() |
apply_filters() && !function_exists() | 33–35 | do_action(), apply_filters(), function_exists(), sprintf(), wp_trigger_error() |
apply_filters() && function_exists() | 37–38 | do_action(), apply_filters(), function_exists(), __(), sprintf(), wp_trigger_error() |
Across PHP versions
Compiles the same on PHP 7.4, 8.1, 8.2, 8.3, 8.4, 8.5 and 8.6-dev: 63 instructions, 12–38 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.
Hooks and filters fired · 2
2 hooks fire while _deprecated_argument() runs, in this order:
- do_action( deprecated_argument_run )actionline 5984 (+11 into the body)
Fires when a deprecated argument is called.
- apply_filters( deprecated_argument_trigger_error )filterline 5993 (+20 into the body)
Filters whether to trigger an error for deprecated arguments.
Uses · 4
- do_action()Calls the callback functions that have been added to an action hook.
- apply_filters()Calls the callback functions that have been added to a filter hook.
- __()Retrieves the translation of $text.
- wp_trigger_error()Generates a user-level error/warning/notice/deprecation message.
Used by · 50
- WP_Admin_Bar::add_node()Adds a node to the menu.
- WP_Dependencies::add_data()Add extra item data.
- WP_Query::get_posts()Retrieves an array of posts based on query variables.
- WP_Theme_JSON::get_stylesheet()Returns the stylesheet that results of processing the theme.json structure this object represents.
- WP_Theme_JSON_Resolver::get_merged_data()Returns the data merged from multiple origins.
- WP_Theme_JSON_Resolver::get_theme_data()Returns the theme's data.
- WP_User::__get()Magic method for accessing custom fields.
- WP_User::__isset()Magic method for checking the existence of a certain custom field.
- WP_User::__set()Magic method for setting custom user fields.
- WP_User::__unset()Magic method for unsetting a certain custom field.
- WP_User::has_cap()Returns whether the user has the specified capability.
- WP_User_Query::prepare_query()Prepares the query variables.
Show all 50
- _WP_Editors::parse_settings()Parse default arguments for the editor instance.
- _load_remote_block_patterns()Register Core's official patterns from wordpress.org/patterns.
- _wp_can_use_pcre_u()Returns whether PCRE/u (PCRE_UTF8 modifier) is available for use.
- add_option()Adds a new option.
- add_settings_field()Adds a new field to a section of a settings page.
- add_settings_section()Adds a new section to a settings page.
- comments_link()Displays the link to the current post comments.
- convert_chars()Converts lone & characters into `&` (a.k.a. `&`)
- discover_pingback_server_uri()Finds a pingback server URI based on the given URL.
- get_adjacent_post()Retrieves the adjacent post.
- get_bloginfo()Retrieves information about the current site.
- get_categories()Retrieves a list of category objects.
- get_category_parents()Retrieves category parents with separator.
- get_delete_post_link()Retrieves the delete posts link for post.
- get_last_updated()Gets a list of most recently updated blogs.
- get_option()Retrieves an option value based on an option name.
- get_plugin_data()Parses the plugin contents to retrieve plugin's metadata.
- get_the_author()Retrieves the author of the current post.
- get_the_excerpt()Retrieves the post excerpt.
- get_user_option()Retrieves user option that can be either per Site or per Network.
- get_wp_title_rss()Retrieves the blog title for the feed title.
- image_edit_apply_changes()Performs group of changes on Editor specified.
- inject_ignored_hooked_blocks_metadata_attributes()Inject ignoredHookedBlocks metadata attributes into a template or template part.
- is_email()Verifies that an email is valid.
- load_plugin_textdomain()Loads a plugin's translated strings.
- ms_subdomain_constants()Defines Multisite subdomain constants and handles warnings and notices.
- register_setting()Registers a setting and its data.
- safecss_filter_attr()Filters an inline style attribute and removes disallowed rules.
- the_attachment_link()Displays an attachment page link using an image or icon.
- the_author()Displays the name of the author of the current post.
- the_author_posts_link()Displays an HTML link to the author page of the current post's author.
- trackback_rdf()Generates and displays the RDF for the trackback information of current post.
- trackback_url()Displays the current post's trackback URL.
- unregister_setting()Unregisters a setting.
- update_blog_option()Updates an option for a particular blog.
- update_blog_status()Updates a blog details field.
- update_option()Updates the value of an option that was already added.
- update_user_status()Update the status of a user in the database.
Source code
function _deprecated_argument( $function_name, $version, $message = '' ) { /** * Fires when a deprecated argument is called. * * @since 3.0.0 * * @param string $function_name The function that was called. * @param string $message A message regarding the change. * @param string $version The version of WordPress that deprecated the argument used. */ do_action( 'deprecated_argument_run', $function_name, $message, $version ); /** * Filters whether to trigger an error for deprecated arguments. * * @since 3.0.0 * * @param bool $trigger Whether to trigger the error for deprecated arguments. Default true. */ if ( WP_DEBUG && apply_filters( 'deprecated_argument_trigger_error', true ) ) { if ( function_exists( '__' ) ) { if ( $message ) { $message = sprintf( /* translators: 1: PHP function name, 2: Version number, 3: Optional message regarding the change. */ __( 'Function %1$s was called with an argument that is <strong>deprecated</strong> since version %2$s! %3$s' ), $function_name, $version, $message ); } else { $message = sprintf( /* translators: 1: PHP function name, 2: Version number. */ __( 'Function %1$s was called with an argument that is <strong>deprecated</strong> since version %2$s with no alternative available.' ), $function_name, $version ); } } else { if ( $message ) { $message = sprintf( 'Function %1$s was called with an argument that is <strong>deprecated</strong> since version %2$s! %3$s', $function_name, $version, $message ); } else { $message = sprintf( 'Function %1$s was called with an argument that is <strong>deprecated</strong> since version %2$s with no alternative available.', $function_name, $version ); } } wp_trigger_error( '', $message, E_USER_DEPRECATED ); }}Changelog
Introduced in 3.0.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 7.1.0 tag, from
src/wp-includes/functions.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.