_deprecated_argument( string $function_name, string $version, string $message = '' )

Description

if ( ! empty( $deprecated ) ) {
 _deprecated_argument( __FUNCTION__, '3.0.0' );
}

Compatibility

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.

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

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

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?

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

Touches nothing outside its own arguments.

Scaling

Constant

No loop in the body: the same number of instructions runs whatever you pass in.

Instructions

12–38

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 63.

Plugin surface

2 hooks

Third-party callbacks on 'deprecated_argument_run', 'deprecated_argument_trigger_error' run inside this call, and their cost is not bounded by anything here.

Called by

50

50 places in core call this, so the cost is paid more often than your own code shows.

What it touches

• hookthird-party callbacksdo_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.

Hooks and filters fired · 2

2 hooks fire while _deprecated_argument() runs, in this order:

1. 1
   do_action( deprecated_argument_run )actionline 5864 (+11 into the body)

   Fires when a deprecated argument is called.

2. 2
   apply_filters( deprecated_argument_trigger_error )filterline 5873 (+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_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.
• _WP_Editors::parse_settings()Parse default arguments for the editor instance.

Source code

View on Trac ↗View on GitHub ↗

5853function _deprecated_argument( $function_name, $version, $message = '' ) {5854 5855	/**5856	 * Fires when a deprecated argument is called.5857	 *5858	 * @since 3.0.05859	 *5860	 * @param string $function_name The function that was called.5861	 * @param string $message       A message regarding the change.5862	 * @param string $version       The version of WordPress that deprecated the argument used.5863	 */5864	do_action( 'deprecated_argument_run', $function_name, $message, $version );5865 5866	/**5867	 * Filters whether to trigger an error for deprecated arguments.5868	 *5869	 * @since 3.0.05870	 *5871	 * @param bool $trigger Whether to trigger the error for deprecated arguments. Default true.5872	 */5873	if ( WP_DEBUG && apply_filters( 'deprecated_argument_trigger_error', true ) ) {5874		if ( function_exists( '__' ) ) {5875			if ( $message ) {5876				$message = sprintf(5877					/* translators: 1: PHP function name, 2: Version number, 3: Optional message regarding the change. */5878					__( 'Function %1$s was called with an argument that is <strong>deprecated</strong> since version %2$s! %3$s' ),5879					$function_name,5880					$version,5881					$message5882				);5883			} else {5884				$message = sprintf(5885					/* translators: 1: PHP function name, 2: Version number. */5886					__( 'Function %1$s was called with an argument that is <strong>deprecated</strong> since version %2$s with no alternative available.' ),5887					$function_name,5888					$version5889				);5890			}5891		} else {5892			if ( $message ) {5893				$message = sprintf(5894					'Function %1$s was called with an argument that is <strong>deprecated</strong> since version %2$s! %3$s',5895					$function_name,5896					$version,5897					$message5898				);5899			} else {5900				$message = sprintf(5901					'Function %1$s was called with an argument that is <strong>deprecated</strong> since version %2$s with no alternative available.',5902					$function_name,5903					$version5904				);5905			}5906		}5907 5908		wp_trigger_error( '', $message, E_USER_DEPRECATED );5909	}5910}

Changelog

Introduced in 3.0.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 6.7.7 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.