wp_parse_args() – Function | Developer.WordPress.org

Merges user defined arguments into defaults array.

Description

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

Parameters

$argsstring|array|objectrequired: Value to merge with $defaults.
$defaultsarrayoptional: Array that serves as the defaults.

Default:array()

Return

array Merged user defined values with defaults.

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.

Source

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 all references View on Trac View on GitHub

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

Used by	Description
WP_Font_Utils::get_font_face_slug()`wp-includes/fonts/class-wp-font-utils.php`	Generates a slug from font face properties, e.g. `open sans;normal;400;100%;U+0-10FFFF`
WP_Font_Collection::get_data()`wp-includes/fonts/class-wp-font-collection.php`	Retrieves the font collection data.
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`
Language_Pack_Upgrader_Skin::__construct()`wp-admin/includes/class-language-pack-upgrader-skin.php`	Constructor.
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`	Constructor.
Theme_Installer_Skin::__construct()`wp-admin/includes/class-theme-installer-skin.php`	Constructor.
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`	Constructor.
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_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 199 more Show less

Changelog

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

User Contributed Notes

Jules Colle 4 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 6 content

Benjiwp 9 years ago

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

Codex 9 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' );

Andrei Surdu 7 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',
];
*/

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

In this article