wp_parse_args( string|array|object $args, array $defaults = array() ): array

Merges user defined arguments into defaults array.

Description
Parameters
Return
More Information
Source
Related
- Uses
- Used By
Changelog
User Contributed Notes

Description

This function is used throughout WordPress to allow for both string or array to be merged into another array.

Top ↑

Parameters

$args string|array|object Required: Value to merge with $defaults.
$defaults array Optional: Array that serves as the defaults.

Default: array()

Top ↑

Return

array Merged user defined values with defaults.

Top ↑

wp_parse_args is a generic utility for merging together an array of arguments and an array of default values. It can also be given a URL query type string which will be converted into an array (i.e. "id=5&status=draft").

It is used throughout WordPress to avoid having to worry about the logic of defaults and input and produces a stable pattern for passing arguments around. Functions like query_posts, wp_list_comments and get_terms are common examples of the simplifying power of wp_parse_args.

Functions that have an $args based setting are able to infinitely expand the number of values that can potentially be passed into them, avoiding the annoyance of super-long function calls because there are too many arguments to keep track of, many of whose only function is to override usually-good defaults on rare occasions.

Top ↑

Source

File: wp-includes/functions.php. View all references

function wp_parse_args( $args, $defaults = array() ) {
	if ( is_object( $args ) ) {
		$parsed_args = get_object_vars( $args );
	} elseif ( is_array( $args ) ) {
		$parsed_args =& $args;
	} else {
		wp_parse_str( $args, $parsed_args );
	}

	if ( is_array( $defaults ) && $defaults ) {
		return array_merge( $defaults, $parsed_args );
	}
	return $parsed_args;
}

View on Trac View on GitHub

Top ↑

Uses

Uses
Uses	Description
wp_parse_str() wp-includes/formatting.php	Parses a string into variables to be stored in an array.

Top ↑

Used By

Used By
Used By	Description
wp_get_admin_notice() wp-includes/functions.php	Creates and returns the markup for an admin notice.
WP_Font_Face::validate_font_face_declarations() wp-includes/fonts/class-wp-font-face.php	Validates each font-face declaration (property and value pairing).
_wp_build_title_and_description_for_single_post_type_block_template() wp-includes/block-template-utils.php	Builds the title and description of a post-specific template based on the underlying referenced post.
_wp_build_title_and_description_for_taxonomy_block_template() wp-includes/block-template-utils.php	Builds the title and description of a taxonomy-specific template based on the underlying entity referenced.
WP_Style_Engine_Processor::get_css() wp-includes/style-engine/class-wp-style-engine-processor.php	Gets the CSS rules as a string.
wp_style_engine_get_styles() wp-includes/style-engine.php	Global public interface method to generate styles from a single style object, e.g. the value of a block’s attributes.style object or the top level styles in theme.json.
wp_style_engine_get_stylesheet_from_css_rules() wp-includes/style-engine.php	Returns compiled CSS from a collection of selectors and declarations.
_wp_theme_json_webfonts_handler() wp-includes/deprecated.php	Runs the theme.json webfonts handler.
wp_json_file_decode() wp-includes/functions.php	Reads and decodes a JSON file.
wp_list_users() wp-includes/user.php	Lists all the users of the site, with several options available.
wp_enqueue_block_style() wp-includes/script-loader.php	Enqueues a stylesheet for a specific block.
WP_Widget_Block::form() wp-includes/widgets/class-wp-widget-block.php	Outputs the Block widget settings form.
WP_Widget_Block::widget() wp-includes/widgets/class-wp-widget-block.php	Outputs the content for the current Block widget instance.
WP_Theme_JSON_Resolver::get_theme_data() wp-includes/class-wp-theme-json-resolver.php	Returns the theme’s data.
WP_REST_Templates_Controller::prepare_item_for_database() wp-includes/rest-api/endpoints/class-wp-rest-templates-controller.php	Prepares a single template for create or update.
WP_REST_Comments_Controller::check_is_comment_content_allowed() wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php	If empty comments are not allowed, checks if the provided comment content is not empty.
WP_Block::render() wp-includes/class-wp-block.php	Generates the render output for the block.
WP_REST_Block_Types_Controller::prepare_item_for_response() wp-includes/rest-api/endpoints/class-wp-rest-block-types-controller.php	Prepares a block type object for serialization.
register_theme_feature() wp-includes/theme.php	Registers a theme feature for use in add_theme_support() .
WP_Embed::get_embed_handler_html() wp-includes/class-wp-embed.php	Returns embed HTML for a given URL from embed handlers.
WP_Debug_Data::debug_data() wp-admin/includes/class-wp-debug-data.php	Static function for generating site debug data when required.
wp_initialize_site() wp-includes/ms-site.php	Runs the initialization routine for a given site.
wp_prepare_site_data() wp-includes/ms-site.php	Prepares site data for insertion or update in the database.
_wp_die_process_input() wp-includes/functions.php	Processes arguments passed to wp_die() consistently for its handlers.
populate_network_meta() wp-admin/includes/schema.php	Creates WordPress network meta and sets the default values.
get_oembed_response_data_for_url() wp-includes/embed.php	Retrieves the oEmbed response data for a given URL.
WP_Block_Type::set_props() wp-includes/class-wp-block-type.php	Sets block type properties.
WP_Widget_Custom_HTML::form() wp-includes/widgets/class-wp-widget-custom-html.php	Outputs the Custom HTML widget settings form.
get_term_parents_list() wp-includes/category-template.php	Retrieves term parents with separator.
WP_oEmbed::get_data() wp-includes/class-wp-oembed.php	Takes a URL and attempts to return the oEmbed data.
WP_Widget_Media::form() wp-includes/widgets/class-wp-widget-media.php	Outputs the settings update form.
WP_Widget_Media::widget() wp-includes/widgets/class-wp-widget-media.php	Displays the widget on the front-end.
WP_Widget_Media::__construct() wp-includes/widgets/class-wp-widget-media.php	Constructor.
WP_Widget_Media_Image::render_media() wp-includes/widgets/class-wp-widget-media-image.php	Render the media on the frontend.
register_rest_field() wp-includes/rest-api.php	Registers a new field on an existing WordPress object type.
wp_update_custom_css_post() wp-includes/theme.php	Updates the `custom_css` post for a given theme.
WP_Taxonomy::set_props() wp-includes/class-wp-taxonomy.php	Sets taxonomy properties.
WP_Term_Query::parse_query() wp-includes/class-wp-term-query.php	Parse arguments passed to the term query with default query parameters.
WP_Term_Query::query() wp-includes/class-wp-term-query.php	Sets up the query and retrieves the results.
WP_Customize_Manager::validate_setting_values() wp-includes/class-wp-customize-manager.php	Validates setting values.
WP_Network_Query::query() wp-includes/class-wp-network-query.php	Sets up the WordPress query for retrieving networks.
WP_Network_Query::parse_query() wp-includes/class-wp-network-query.php	Parses arguments passed to the network query with default query parameters.
WP_Post_Type::set_props() wp-includes/class-wp-post-type.php	Sets post type properties.
WP_Site_Query::query() wp-includes/class-wp-site-query.php	Sets up the WordPress query for retrieving sites.
WP_Site_Query::parse_query() wp-includes/class-wp-site-query.php	Parses arguments passed to the site query with default query parameters.
network_edit_site_nav() wp-admin/includes/ms.php	Outputs the HTML for a network’s “Edit Site” tabular interface.
get_header_image_tag() wp-includes/theme.php	Creates image tag markup for a custom header image.
WP_REST_Server::get_routes() wp-includes/rest-api/class-wp-rest-server.php	Retrieves the route map.
WP_Comment::get_children() wp-includes/class-wp-comment.php	Gets the children of a comment.
WP_User_Query::fill_query_vars() wp-includes/class-wp-user-query.php	Fills in missing query variables with default values.
get_the_comments_navigation() wp-includes/link-template.php	Retrieves navigation to next/previous set of comments, when applicable.
get_the_comments_pagination() wp-includes/link-template.php	Retrieves a paginated navigation to next/previous set of comments, when applicable.
WP_Screen::set_screen_reader_content() wp-admin/includes/class-wp-screen.php	Adds accessible hidden headings and text for the screen.
WP_Customize_Media_Control::__construct() wp-includes/customize/class-wp-customize-media-control.php	Constructor.
WP_Comment_Query::parse_query() wp-includes/class-wp-comment-query.php	Parse arguments passed to the comment query with default query parameters.
get_avatar_data() wp-includes/link-template.php	Retrieves default data about the avatar.
get_children() wp-includes/post.php	Retrieves all children of the post parent ID.
get_the_post_navigation() wp-includes/link-template.php	Retrieves the navigation to next/previous post, when applicable.
get_the_posts_navigation() wp-includes/link-template.php	Returns the navigation to next/previous set of posts, when applicable.
get_the_posts_pagination() wp-includes/link-template.php	Retrieves a paginated navigation to next/previous set of posts, when applicable.
WP_oEmbed::get_provider() wp-includes/class-wp-oembed.php	Takes a URL and returns the corresponding oEmbed provider’s URL, if there is one.
wp_dropdown_languages() wp-includes/l10n.php	Displays or returns a Language selector.
Core_Upgrader::upgrade() wp-admin/includes/class-core-upgrader.php	Upgrades WordPress core.
Language_Pack_Upgrader::bulk_upgrade() wp-admin/includes/class-language-pack-upgrader.php	Upgrades several language packs at once.
Plugin_Upgrader::bulk_upgrade() wp-admin/includes/class-plugin-upgrader.php	Upgrades several plugins at once.
Theme_Upgrader::install() wp-admin/includes/class-theme-upgrader.php	Install a theme package.
Theme_Upgrader::upgrade() wp-admin/includes/class-theme-upgrader.php	Upgrades a theme.
Theme_Upgrader::bulk_upgrade() wp-admin/includes/class-theme-upgrader.php	Upgrades several themes at once.
WP_Upgrader::install_package() wp-admin/includes/class-wp-upgrader.php	Install a package.
WP_Upgrader::run() wp-admin/includes/class-wp-upgrader.php	Runs an upgrade/installation.
Plugin_Upgrader::install() wp-admin/includes/class-plugin-upgrader.php	Install a plugin package.
Plugin_Upgrader::upgrade() wp-admin/includes/class-plugin-upgrader.php	Upgrades a plugin.
WP_Screen::render_screen_options() wp-admin/includes/class-wp-screen.php	Renders the screen options tab.
WP_Screen::add_help_tab() wp-admin/includes/class-wp-screen.php	Adds a help tab to the contextual help for the screen.
WP_Plugins_List_Table::prepare_items() wp-admin/includes/class-wp-plugins-list-table.php
export_wp() wp-admin/includes/export.php	Generates the WXR export file for download.
Language_Pack_Upgrader_Skin::__construct() wp-admin/includes/class-language-pack-upgrader-skin.php
Theme_Upgrader_Skin::__construct() wp-admin/includes/class-theme-upgrader-skin.php	Constructor.
Plugin_Installer_Skin::__construct() wp-admin/includes/class-plugin-installer-skin.php
Theme_Installer_Skin::__construct() wp-admin/includes/class-theme-installer-skin.php
Plugin_Upgrader_Skin::__construct() wp-admin/includes/class-plugin-upgrader-skin.php	Constructor.
Bulk_Upgrader_Skin::__construct() wp-admin/includes/class-bulk-upgrader-skin.php
WP_Upgrader_Skin::__construct() wp-admin/includes/class-wp-upgrader-skin.php	Constructor.
WP_List_Table::__construct() wp-admin/includes/class-wp-list-table.php	Constructor.
WP_List_Table::set_pagination_args() wp-admin/includes/class-wp-list-table.php	Sets all the necessary pagination arguments.
populate_options() wp-admin/includes/schema.php	Create WordPress options and set the default values.
wp_insert_category() wp-admin/includes/taxonomy.php	Updates an existing Category or creates a new Category.
register_setting() wp-includes/option.php	Registers a setting and its data.
wp_star_rating() wp-admin/includes/template.php	Outputs a HTML element with a star rating for a given rating.
add_settings_section() wp-admin/includes/template.php	Adds a new section to a settings page.
wp_terms_checklist() wp-admin/includes/template.php	Outputs an unordered list of checkbox input elements labelled with term names.
get_media_item() wp-admin/includes/media.php	Retrieves HTML form for modifying the image attachment.
get_compat_media_markup() wp-admin/includes/media.php
wp_ajax_query_themes() wp-admin/includes/ajax-actions.php	Handles getting themes from themes_api() via AJAX.
wp_insert_link() wp-admin/includes/bookmark.php	Inserts a link into the database, or updates an existing link.
post_tags_meta_box() wp-admin/includes/meta-boxes.php	Displays post tags form fields.
post_categories_meta_box() wp-admin/includes/meta-boxes.php	Displays post categories form fields.
wp_tag_cloud() wp-includes/category-template.php	Displays a tag cloud.
wp_generate_tag_cloud() wp-includes/category-template.php	Generates a tag cloud (heatmap) from provided data.
wp_dropdown_categories() wp-includes/category-template.php	Displays or retrieves the HTML dropdown list of categories.
wp_list_categories() wp-includes/category-template.php	Displays or retrieves the HTML list of categories.
add_theme_support() wp-includes/theme.php	Registers theme support for a given feature.
get_custom_header() wp-includes/theme.php	Gets the header image data.
wp_get_themes() wp-includes/theme.php	Returns an array of WP_Theme objects based on the arguments.
get_avatar() wp-includes/pluggable.php	Retrieves the avatar `<img>` tag for a user, email address, MD5 hash, comment, or post.
wp_text_diff() wp-includes/pluggable.php	Displays a human readable HTML representation of the difference between two strings.
paginate_links() wp-includes/general-template.php	Retrieves paginated links for archive post pages.
feed_links() wp-includes/general-template.php	Displays the links to the general feeds.
feed_links_extra() wp-includes/general-template.php	Displays the links to the extra feeds such as category feeds.
wp_get_archives() wp-includes/general-template.php	Displays archive links based on type and format.
wp_login_form() wp-includes/general-template.php	Provides a simple login form for use anywhere within WordPress.
get_search_form() wp-includes/general-template.php	Displays search form.
wp_get_links() wp-includes/deprecated.php	Gets the links associated with category.
wp_get_linksbyname() wp-includes/deprecated.php	Gets the links associated with the named category.
wp_list_cats() wp-includes/deprecated.php	Lists categories.
WP_Query::query() wp-includes/class-wp-query.php	Sets up the WordPress query by parsing query string.
WP_Query::parse_query() wp-includes/class-wp-query.php	Parses a query string and sets query type booleans.
get_tags() wp-includes/category.php	Retrieves all post tags.
get_categories() wp-includes/category.php	Retrieves a list of category objects.
WP_Http_Streams::request() wp-includes/class-wp-http-streams.php	Send a HTTP request to a URI using PHP Streams.
WP_Http_Curl::request() wp-includes/class-wp-http-curl.php	Send a HTTP request to a URI using cURL extension.
WP_Http::post() wp-includes/class-wp-http.php	Uses the POST HTTP method.
WP_Http::get() wp-includes/class-wp-http.php	Uses the GET HTTP method.
WP_Http::head() wp-includes/class-wp-http.php	Uses the HEAD HTTP method.
WP_Http::request() wp-includes/class-wp-http.php	Send an HTTP request to a URI.
_ajax_wp_die_handler() wp-includes/functions.php	Kills WordPress execution and displays Ajax response with an error message.
WP_Widget_Categories::form() wp-includes/widgets/class-wp-widget-categories.php	Outputs the settings form for the Categories widget.
WP_Widget_Text::update() wp-includes/widgets/class-wp-widget-text.php	Handles updating settings for the current Text widget instance.
WP_Widget_Text::form() wp-includes/widgets/class-wp-widget-text.php	Outputs the Text widget settings form.
WP_Widget_Calendar::form() wp-includes/widgets/class-wp-widget-calendar.php	Outputs the settings form for the Calendar widget.
WP_Widget_Meta::form() wp-includes/widgets/class-wp-widget-meta.php	Outputs the settings form for the Meta widget.
WP_Widget_Archives::update() wp-includes/widgets/class-wp-widget-archives.php	Handles updating settings for the current Archives widget instance.
WP_Widget_Archives::form() wp-includes/widgets/class-wp-widget-archives.php	Outputs the settings form for the Archives widget.
WP_Widget_Search::form() wp-includes/widgets/class-wp-widget-search.php	Outputs the settings form for the Search widget.
WP_Widget_Search::update() wp-includes/widgets/class-wp-widget-search.php	Handles updating settings for the current Search widget instance.
WP_Widget_Links::form() wp-includes/widgets/class-wp-widget-links.php	Outputs the settings form for the Links widget.
WP_Widget_Pages::form() wp-includes/widgets/class-wp-widget-pages.php	Outputs the settings form for the Pages widget.
wp_widget_rss_output() wp-includes/widgets.php	Display the RSS entries in a list.
wp_widget_rss_form() wp-includes/widgets.php	Display RSS widget options form.
WP_Embed::shortcode() wp-includes/class-wp-embed.php	The do_shortcode() callback function.
the_taxonomies() wp-includes/taxonomy.php	Displays the taxonomies of a post with available options.
get_the_taxonomies() wp-includes/taxonomy.php	Retrieves all taxonomies associated with a post.
wp_update_term() wp-includes/taxonomy.php	Updates term based on arguments provided.
wp_get_object_terms() wp-includes/taxonomy.php	Retrieves the terms associated with the given object(s), in the supplied taxonomies.
wp_insert_term() wp-includes/taxonomy.php	Adds a new term to the database.
wp_count_terms() wp-includes/taxonomy.php	Counts how many terms are in taxonomy.
wp_delete_term() wp-includes/taxonomy.php	Removes a term from the database.
term_exists() wp-includes/taxonomy.php	Determines whether a taxonomy term exists.
get_terms() wp-includes/taxonomy.php	Retrieves the terms in a given taxonomy or list of taxonomies.
register_taxonomy() wp-includes/taxonomy.php	Creates or modifies a taxonomy object.
get_objects_in_term() wp-includes/taxonomy.php	Retrieves object IDs of valid taxonomy and term.
paginate_comments_links() wp-includes/link-template.php	Displays or retrieves pagination links for the comments on the current post.
get_posts_nav_link() wp-includes/link-template.php	Retrieves the post pages link navigation for previous and next pages.
WP_Ajax_Response::add() wp-includes/class-wp-ajax-response.php	Appends data to an XML response based on given arguments.
WP_Admin_Bar::add_node() wp-includes/class-wp-admin-bar.php	Adds a node to the menu.
wp_http_supports() wp-includes/http.php	Determines if there is an HTTP Transport that can process this request.
WP_oEmbed::fetch() wp-includes/class-wp-oembed.php	Connects to an oEmbed provider and returns the result.
get_users() wp-includes/user.php	Retrieves list of users matching criteria.
wp_dropdown_users() wp-includes/user.php	Creates dropdown HTML content of users.
_walk_bookmarks() wp-includes/bookmark-template.php	The formatted output of a list of bookmarks.
wp_list_bookmarks() wp-includes/bookmark-template.php	Retrieves or echoes all of the bookmarks.
wp_nav_menu() wp-includes/nav-menu-template.php	Displays a navigation menu.
wp_link_pages() wp-includes/post-template.php	The formatted output of a list of pages.
wp_dropdown_pages() wp-includes/post-template.php	Retrieves or displays a list of pages as a dropdown (select list).
wp_list_pages() wp-includes/post-template.php	Retrieves or displays a list of pages (or hierarchical post type items) in list (li) format.
wp_page_menu() wp-includes/post-template.php	Displays or retrieves a list of pages with an optional home link.
the_title_attribute() wp-includes/post-template.php	Sanitizes the current title when retrieving or displaying.
wp_enqueue_media() wp-includes/media.php	Enqueues all scripts, styles, settings, and templates necessary to use all media JS APIs.
wp_get_attachment_image() wp-includes/media.php	Gets an HTML img element representing an image attachment.
wp_insert_attachment() wp-includes/post.php	Inserts an attachment.
get_pages() wp-includes/post.php	Retrieves an array of pages (or hierarchical post type items).
wp_get_post_categories() wp-includes/post.php	Retrieves the list of categories for a post.
wp_get_post_terms() wp-includes/post.php	Retrieves the terms for a post.
wp_get_recent_posts() wp-includes/post.php	Retrieves a number of recent posts.
wp_insert_post() wp-includes/post.php	Inserts or update a post.
get_posts() wp-includes/post.php	Retrieves an array of the latest posts, or posts matching the given criteria.
register_post_status() wp-includes/post.php	Registers a post status. Do not use before init.
WP_Rewrite::add_permastruct() wp-includes/class-wp-rewrite.php	Adds a new permalink structure.
wp_get_post_revisions() wp-includes/revision.php	Returns all revisions of specified post.
wp_get_sites() wp-includes/ms-deprecated.php	Return an array of sites for a network or networks.
wpmu_create_blog() wp-includes/ms-functions.php	Creates a site.
get_bookmarks() wp-includes/bookmark.php	Retrieves the list of bookmarks.
wp_list_authors() wp-includes/author-template.php	Lists all the authors of the site, with several options available.
wp_update_nav_menu_item() wp-includes/nav-menu.php	Saves the properties of a menu item or create a new one.
wp_get_nav_menus() wp-includes/nav-menu.php	Returns all navigation menu objects.
wp_get_nav_menu_items() wp-includes/nav-menu.php	Retrieves all menu items of a navigation menu.
wp_xmlrpc_server::_insert_post() wp-includes/class-wp-xmlrpc-server.php	Helper method for wp_newPost() and wp_editPost(), containing shared logic.
WP_Widget::display_callback() wp-includes/class-wp-widget.php	Generates the actual widget content (Do NOT override).
WP_Widget::form_callback() wp-includes/class-wp-widget.php	Generates the widget control form (Do NOT override).
WP_Widget::__construct() wp-includes/class-wp-widget.php	PHP5 constructor.
the_widget() wp-includes/widgets.php	Output an arbitrary widget as a template tag.
register_sidebar() wp-includes/widgets.php	Builds the definition for a single sidebar and returns the ID.
wp_register_sidebar_widget() wp-includes/widgets.php	Register an instance of a widget.
wp_register_widget_control() wp-includes/widgets.php	Registers widget control callback for customizing options.
_register_widget_form_callback() wp-includes/widgets.php	Registers the form callback for a widget.
get_post_reply_link() wp-includes/comment-template.php	Retrieves HTML content for reply to post link.
wp_list_comments() wp-includes/comment-template.php	Displays a list of comments.
comment_form() wp-includes/comment-template.php	Outputs a complete commenting form for use within a template.
get_comment_reply_link() wp-includes/comment-template.php	Retrieves HTML content for reply to comment link.
get_comment_link() wp-includes/comment-template.php	Retrieves the link to a given comment.
WP_Comment_Query::query() wp-includes/class-wp-comment-query.php	Sets up the WordPress query for retrieving comments.
get_page_of_comment() wp-includes/comment.php	Calculates what page number a comment will appear on for comment paging.
register_meta() wp-includes/meta.php	Registers a meta key.
get_approved_comments() wp-includes/comment.php	Retrieves the approved comments for a post.
_WP_Editors::parse_settings() wp-includes/class-wp-editor.php	Parse default arguments for the editor instance.

Show 200 more used by Hide more used by

Top ↑

Changelog

Changelog
Version	Description
2.3.0	`$args` can now also be an object.
2.2.0	Introduced.

Top ↑

User Contributed Notes

Contributed by Jules Colle — 3 years ago

Basic usage:

function wpdocs_my_function( $args ) {

  $defaults = array(
    'name' => 'Mr. nobody',
    'favorite_color' => 'unknown',
    'age' => 'unknown',
  );

  $args = wp_parse_args( $args, $defaults );

  print_r( $args );

}

$args = array( 'age' => 36 );
wpdocs_my_function( $args );

// Output:
// 
// Array(
//   'name' => 'Mr. nobody',
//   'favorite_color' => 'unknown',
//   'age' => 36,
// )

Skip to note 2 content

You must log in to vote on the helpfulness of this noteVote results for this note: 4You must log in to vote on the helpfulness of this note

Contributed by Benjiwp — 8 years ago
Thank you bhlarsen for this function but there is a little mistake:

if (!$echo)
must be replaced by
if (!$args['echo'])
Log in to add feedback

Contributed by Codex — 8 years ago

Below is an example function using the wp_parse_args system to manage its single $args argument, which could be given whatever values you wanted.
In this case $args stores detailed display overrides, a pattern found in many WordPress functions.

/**
 * Define a new function that uses $args and wp_parse_args()
 */
function wpdocs_explain_parse_args( $args ) {
	$defaults = array (
		'text' => 'wp_parse_args() merges $args into $defaults',
		'before' => "<p>",
		'after' => "</p> \n",
 		'echo' => TRUE
	);
	
	// Parse incoming $args into an array and merge it with $defaults
	$args = wp_parse_args( $args, $defaults );
	
	$output = $args['before'] . $args['text'] . $args['after'];
	
	if (!$echo) 
		return $output;
	
	echo $output;
}

/**
 * Run our new function using the defaults (no $args)
 * This would print out: 
 * 	<p>wp_parse_args() merges $args into $defaults</p>
 */
wpdocs_explain_parse_args();

/**
 * Run the function with some options overridden with an array
 * This would echo the output with the modified text and before arguments:
 * 	<p class='specialclass'>A better explanation</p>
 */
wpdocs_explain_parse_args( array (
	'text' => "A better explanation",
	'before' => "<p class='specialclass'>"
) );

/**
 * We can also pass in URL-style string-query and it will be converted
 * This would set $args['echo'] to 1 and $args['text'] to 0	
 */
wpdocs_explain_parse_args( 'echo=1&text=0' );

Contributed by Andrei Surdu — 6 years ago

If you are looking to recursively merge two arrays, here is the function:

if ( ! function_exists( 'wpdocs_recursive_parse_args' ) ) {
	function wpdocs_recursive_parse_args( $args, $defaults ) {
		$new_args = (array) $defaults;

		foreach ( $args as $key => $value ) {
			if ( is_array( $value ) && isset( $new_args[ $key ] ) ) {
				$new_args[ $key ] = wpdocs_recursive_parse_args( $value, $new_args[ $key ] );
			}
			else {
				$new_args[ $key ] = $value;
			}
		}

		return $new_args;
	}
}

Test case:

$defaults = [
	'x1' => 'level1',
	'x2' => [
		'a1' => 'level1',
		'a2' => 'level1',
	],
	'x4' => [
		'b1' => [
			'c1' => 'level1',
		],
		'b2' => 'level1',
	],
	'x3' => 'level1',
];
$args     = [
	'x3' => 'level2',
	'x2' => [
		'a2' => 'level2',
	],
	'x4' => [
		'b1' => [
			'c1' => 'level2',
			'c2' => 'leve2',
			'c3' => [
				'd1' => [
					'e1' => 'ok',
				],
			],
		],
	],
];

print_r( awps_recursive_parse_args( $args, $defaults );

/**
 * Result
 */
/*
[
	'x1' => 'level1',
	'x2' => [
		'a1' => 'level1',
		'a2' => 'level2',
	],
	'x4' => [
		'b1' => [
			'c1' => 'level2',
			'c2' => 'leve2',
			'c3' => [
				'd1' => [
					'e1' => 'ok',
				],
			],
		],
		'b2' => 'level1',
	],
	'x3' => 'level2',
];
*/

You must log in before being able to contribute a note or feedback.

Developer Resources

wp_parse_args( string|array|object $args, array $defaults = array() ): array

Contents

Description

Parameters

Return

More Information

Source

Changelog

User Contributed Notes