WordPress.org

Marks 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 ‘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.

Parameters

$function_namestringrequired: The function that was called.
$versionstringrequired: The version of WordPress that deprecated the argument used.
$messagestringoptional: A message regarding the change. Default empty string.

Source

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 );
	}
}

View all references View on Trac View on GitHub

Hooks

do_action( ‘deprecated_argument_run’, string $function_name, string $message, string $version ): Fires when a deprecated argument is called.
apply_filters( ‘deprecated_argument_trigger_error’, bool $trigger ): Filters whether to trigger an error for deprecated arguments.

Uses	Description
wp_trigger_error()`wp-includes/functions.php`	Generates a user-level error/warning/notice/deprecation message.
__()`wp-includes/l10n.php`	Retrieves the translation of $text.
do_action()`wp-includes/plugin.php`	Calls the callback functions that have been added to an action hook.
apply_filters()`wp-includes/plugin.php`	Calls the callback functions that have been added to a filter hook.

Show 2 more Show less

Used by	Description
inject_ignored_hooked_blocks_metadata_attributes()`wp-includes/block-template-utils.php`	Inject ignoredHookedBlocks metadata attributes into a template or template part.
_load_remote_block_patterns()`wp-includes/block-patterns.php`	Register Core’s official patterns from wordpress.org/patterns.
WP_Theme_JSON_Resolver::get_theme_data()`wp-includes/class-wp-theme-json-resolver.php`	Returns the theme’s data.
WP_Theme_JSON_Resolver::get_merged_data()`wp-includes/class-wp-theme-json-resolver.php`	Returns the data merged from multiple origins.
WP_Theme_JSON::get_stylesheet()`wp-includes/class-wp-theme-json.php`	Returns the stylesheet that results of processing the theme.json structure this object represents.
wp_get_environment_type()`wp-includes/load.php`	Retrieves the current environment type.
WP_User::__unset()`wp-includes/class-wp-user.php`	Magic method for unsetting a certain custom field.
update_user_status()`wp-includes/ms-deprecated.php`	Update the status of a user in the database.
wp_save_image_file()`wp-admin/includes/image-edit.php`	Saves image to file.
image_edit_apply_changes()`wp-admin/includes/image-edit.php`	Performs group of changes on Editor specified.
wp_stream_image()`wp-admin/includes/image-edit.php`	Streams image in WP_Image_Editor to browser.
wp_install()`wp-admin/includes/upgrade.php`	Installs the site.
register_setting()`wp-includes/option.php`	Registers a setting and its data.
unregister_setting()`wp-includes/option.php`	Unregisters a setting.
get_plugin_data()`wp-admin/includes/plugin.php`	Parses the plugin contents to retrieve plugin’s metadata.
add_settings_field()`wp-admin/includes/template.php`	Adds a new field to a section of a settings page.
add_settings_section()`wp-admin/includes/template.php`	Adds a new section to a settings page.
xfn_check()`wp-admin/includes/meta-boxes.php`	Displays ‘checked’ checkboxes attribute for XFN microformat options.
WP_User::has_cap()`wp-includes/class-wp-user.php`	Returns whether the user has the specified capability.
WP_User::__isset()`wp-includes/class-wp-user.php`	Magic method for checking the existence of a certain custom field.
WP_User::__get()`wp-includes/class-wp-user.php`	Magic method for accessing custom fields.
WP_User::__set()`wp-includes/class-wp-user.php`	Magic method for setting custom user fields.
wp_clear_scheduled_hook()`wp-includes/cron.php`	Unschedules all events attached to the hook with the specified arguments.
get_category_parents()`wp-includes/category-template.php`	Retrieves category parents with separator.
wp_dropdown_categories()`wp-includes/category-template.php`	Displays or retrieves the HTML dropdown list of categories.
load_plugin_textdomain()`wp-includes/l10n.php`	Loads a plugin’s translated strings.
is_email()`wp-includes/formatting.php`	Verifies that an email is valid.
convert_chars()`wp-includes/formatting.php`	Converts lone & characters into `&` (a.k.a. `&`)
wp_new_user_notification()`wp-includes/pluggable.php`	Emails login credentials to a newly-registered user.
wp_notify_postauthor()`wp-includes/pluggable.php`	Notifies an author (and/or others) of a comment/trackback/pingback on a post.
get_bloginfo()`wp-includes/general-template.php`	Retrieves information about the current site.
safecss_filter_attr()`wp-includes/kses.php`	Filters an inline style attribute and removes disallowed rules.
WP_Query::get_posts()`wp-includes/class-wp-query.php`	Retrieves an array of posts based on query variables.
get_categories()`wp-includes/category.php`	Retrieves a list of category objects.
wp_upload_bits()`wp-includes/functions.php`	Creates a file in the upload folder with given content.
wp_get_http_headers()`wp-includes/functions.php`	Retrieves HTTP Headers from URL.
get_adjacent_post()`wp-includes/link-template.php`	Retrieves the adjacent post.
get_delete_post_link()`wp-includes/link-template.php`	Retrieves the delete posts link for post.
WP_Admin_Bar::add_node()`wp-includes/class-wp-admin-bar.php`	Adds a node to the menu.
get_wp_title_rss()`wp-includes/feed.php`	Retrieves the blog title for the feed title.
wp_title_rss()`wp-includes/feed.php`	Displays the blog title for display of the feed title.
update_option()`wp-includes/option.php`	Updates the value of an option that was already added.
add_option()`wp-includes/option.php`	Adds a new option.
WP_Dependencies::add_data()`wp-includes/class-wp-dependencies.php`	Add extra item data.
get_option()`wp-includes/option.php`	Retrieves an option value based on an option name.
WP_User_Query::prepare_query()`wp-includes/class-wp-user-query.php`	Prepares the query variables.
get_user_option()`wp-includes/user.php`	Retrieves user option that can be either per Site or per Network.
wp_list_post_revisions()`wp-includes/post-template.php`	Displays a list of a post’s revisions.
the_attachment_link()`wp-includes/post-template.php`	Displays an attachment page link using an image or icon.
get_the_excerpt()`wp-includes/post-template.php`	Retrieves the post excerpt.
wp_get_recent_posts()`wp-includes/post.php`	Retrieves a number of recent posts.
the_author_posts_link()`wp-includes/author-template.php`	Displays an HTML link to the author page of the current post’s author.
update_blog_status()`wp-includes/ms-blogs.php`	Updates a blog details field.
get_last_updated()`wp-includes/ms-blogs.php`	Gets a list of most recently updated blogs.
get_the_author()`wp-includes/author-template.php`	Retrieves the author of the current post.
the_author()`wp-includes/author-template.php`	Displays the name of the author of the current post.
update_blog_option()`wp-includes/ms-blogs.php`	Updates an option for a particular blog.
ms_subdomain_constants()`wp-includes/ms-default-constants.php`	Defines Multisite subdomain constants and handles warnings and notices.
wp_get_sidebars_widgets()`wp-includes/widgets.php`	Retrieves the full list of sidebars and their widget instance IDs.
trackback_url()`wp-includes/comment-template.php`	Displays the current post’s trackback URL.
trackback_rdf()`wp-includes/comment-template.php`	Generates and displays the RDF for the trackback information of current post.
comments_link()`wp-includes/comment-template.php`	Displays the link to the current post comments.
discover_pingback_server_uri()`wp-includes/comment.php`	Finds a pingback server URI based on the given URL.
_WP_Editors::parse_settings()`wp-includes/class-wp-editor.php`	Parse default arguments for the editor instance.

Show 59 more Show less

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.

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

In this article

Description

Parameters

Source

Hooks

Related

Changelog

User Contributed Notes