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

Mark a function argument as deprecated and inform when it has been used.

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 hook deprecated_argument_run 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.

Parameters

$function

(string) (Required) The function that was called.

$version

(string) (Required) The version of WordPress that deprecated the argument used.

$message

(string) (Optional) A message regarding the change.

Default value: ''

Source

File: wp-includes/functions.php 

function _deprecated_argument( $function, $version, $message = '' ) {

	/**
	 * Fires when a deprecated argument is called.
	 *
	 * @since 3.0.0
	 *
	 * @param string $function 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, $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 ) {
				trigger_error(
					sprintf(
						/* translators: 1: PHP function name, 2: Version number, 3: Optional message regarding the change. */
						__( '%1$s was called with an argument that is <strong>deprecated</strong> since version %2$s! %3$s' ),
						$function,
						$version,
						$message
					),
					E_USER_DEPRECATED
				);
			} else {
				trigger_error(
					sprintf(
						/* translators: 1: PHP function name, 2: Version number. */
						__( '%1$s was called with an argument that is <strong>deprecated</strong> since version %2$s with no alternative available.' ),
						$function,
						$version
					),
					E_USER_DEPRECATED
				);
			}
		} else {
			if ( $message ) {
				trigger_error(
					sprintf(
						'%1$s was called with an argument that is <strong>deprecated</strong> since version %2$s! %3$s',
						$function,
						$version,
						$message
					),
					E_USER_DEPRECATED
				);
			} else {
				trigger_error(
					sprintf(
						'%1$s was called with an argument that is <strong>deprecated</strong> since version %2$s with no alternative available.',
						$function,
						$version
					),
					E_USER_DEPRECATED
				);
			}
		}
	}
}

Uses

Uses Description
wp-includes/l10n.php: __()

Retrieve the translation of $text.
wp-includes/functions.php: deprecated_argument_run

Fires when a deprecated argument is called.
wp-includes/functions.php: deprecated_argument_trigger_error

Filters whether to trigger an error for deprecated arguments.
wp-includes/plugin.php: do_action()

Calls the callback functions that have been added to an action hook.
wp-includes/plugin.php: apply_filters()

Calls the callback functions that have been added to a filter hook.

Used By

Used By Description
wp-includes/load.php: wp_get_environment_type()

Retrieves the current environment type.
wp-includes/class-wp-user.php: WP_User::__unset()

Magic method for unsetting a certain custom field.
wp-includes/ms-deprecated.php: update_user_status()

Update the status of a user in the database.
wp-admin/includes/image-edit.php: wp_save_image_file()

Saves image to file.
wp-admin/includes/image-edit.php: image_edit_apply_changes()

Performs group of changes on Editor specified.
wp-admin/includes/image-edit.php: wp_stream_image()

Streams image in WP_Image_Editor to browser.
wp-admin/includes/upgrade.php: wp_install()

Installs the site.
wp-includes/option.php: register_setting()

Registers a setting and its data.
wp-includes/option.php: unregister_setting()

Unregisters a setting.
wp-admin/includes/plugin.php: get_plugin_data()

Parses the plugin contents to retrieve plugin’s metadata.
wp-admin/includes/template.php: add_settings_field()

Add a new field to a section of a settings page.
wp-admin/includes/template.php: add_settings_section()

Add a new section to a settings page.
wp-admin/includes/meta-boxes.php: xfn_check()

Display checked checkboxes attribute for xfn microformat options.
wp-includes/class-wp-user.php: WP_User::has_cap()

Returns whether the user has the specified capability.
wp-includes/class-wp-user.php: WP_User::__isset()

Magic method for checking the existence of a certain custom field.
wp-includes/class-wp-user.php: WP_User::__get()

Magic method for accessing custom fields.
wp-includes/class-wp-user.php: WP_User::__set()

Magic method for setting custom user fields.
wp-includes/cron.php: wp_clear_scheduled_hook()

Unschedules all events attached to the hook with the specified arguments.
wp-includes/category-template.php: get_category_parents()

Retrieves category parents with separator.
wp-includes/category-template.php: wp_dropdown_categories()

Displays or retrieves the HTML dropdown list of categories.
wp-includes/l10n.php: load_plugin_textdomain()

Loads a plugin’s translated strings.
wp-includes/formatting.php: is_email()

Verifies that an email is valid.
wp-includes/formatting.php: convert_chars()

Converts lone & characters into &#038; (a.k.a. &amp;)
wp-includes/pluggable.php: wp_new_user_notification()

Email login credentials to a newly-registered user.
wp-includes/pluggable.php: wp_notify_postauthor()

Notify an author (and/or others) of a comment/trackback/pingback on a post.
wp-includes/general-template.php: get_bloginfo()

Retrieves information about the current site.
wp-includes/kses.php: safecss_filter_attr()

Filters an inline style attribute and removes disallowed rules.
wp-includes/class-wp-query.php: WP_Query::get_posts()

Retrieves an array of posts based on query variables.
wp-includes/category.php: get_categories()

Retrieves a list of category objects.
wp-includes/functions.php: wp_upload_bits()

Create a file in the upload folder with given content.
wp-includes/functions.php: wp_get_http_headers()

Retrieve HTTP Headers from URL.
wp-includes/link-template.php: get_adjacent_post()

Retrieves the adjacent post.
wp-includes/link-template.php: get_delete_post_link()

Retrieves the delete posts link for post.
wp-includes/class-wp-admin-bar.php: WP_Admin_Bar::__get()
wp-includes/class-wp-admin-bar.php: WP_Admin_Bar::add_node()

Adds a node to the menu.
wp-includes/feed.php: get_wp_title_rss()

Retrieve the blog title for the feed title.
wp-includes/feed.php: wp_title_rss()

Display the blog title for display of the feed title.
wp-includes/option.php: update_option()

Updates the value of an option that was already added.
wp-includes/option.php: add_option()

Adds a new option.
wp-includes/option.php: get_option()

Retrieves an option value based on an option name.
wp-includes/user.php: get_user_option()

Retrieve user option that can be either per Site or per Network.
wp-includes/post-template.php: wp_list_post_revisions()

Display a list of a post’s revisions.
wp-includes/post-template.php: the_attachment_link()

Display an attachment page link using an image or icon.
wp-includes/post-template.php: get_the_excerpt()

Retrieves the post excerpt.
wp-includes/post.php: wp_get_recent_posts()

Retrieve a number of recent posts.
wp-includes/author-template.php: the_author_posts_link()

Displays an HTML link to the author page of the current post’s author.
wp-includes/ms-blogs.php: update_blog_status()

Update a blog details field.
wp-includes/ms-blogs.php: get_last_updated()

Get a list of most recently updated blogs.
wp-includes/author-template.php: get_the_author()

Retrieve the author of the current post.
wp-includes/author-template.php: the_author()

Display the name of the author of the current post.
wp-includes/ms-blogs.php: update_blog_option()

Update an option for a particular blog.
wp-includes/ms-default-constants.php: ms_subdomain_constants()

Defines Multisite subdomain constants and handles warnings and notices.
wp-includes/widgets.php: wp_get_sidebars_widgets()

Retrieve full list of sidebars and their widget instance IDs.
wp-includes/comment-template.php: trackback_url()

Displays the current post’s trackback URL.
wp-includes/comment-template.php: trackback_rdf()

Generates and displays the RDF for the trackback information of current post.
wp-includes/comment-template.php: comments_link()

Displays the link to the current post comments.
wp-includes/comment.php: discover_pingback_server_uri()

Finds a pingback server URI based on the given URL.
wp-includes/class-wp-editor.php: _WP_Editors::parse_settings()

Parse default arguments for the editor instance.

Changelog

Version Description
5.4.0 The error type is now classified as E_USER_DEPRECATED (used to default to E_USER_NOTICE).
3.0.0 Introduced.

© 2003–2021 WordPress Foundation
Licensed under the GNU GPLv2+ License.
https://developer.wordpress.org/reference/functions/_deprecated_argument