wp_parse_args( string|array|object $args, array $defaults = array() ): array
Merges user defined arguments into defaults array.
Contents
Description
This function is used throughout WordPress to allow for both string or array to be merged into another array.
Parameters
-
$args
string|array|object Required -
Value to merge with $defaults.
-
$defaults
array Optional -
Array that serves as the defaults.
Default:
array()
Return
array Merged user defined values with defaults.
More Information
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
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;
}
Related
Uses
Uses | Description |
---|---|
wp_parse_str() wp-includes/formatting.php |
Parses a string into variables to be stored in an array. |
Used By
Used By | Description |
---|---|
_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/script-loader.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 |
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 |
Get 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. |
Language_Pack_Upgrader::bulk_upgrade() wp-admin/includes/class-language-pack-upgrader.php |
Bulk upgrade language packs. |
Core_Upgrader::upgrade() wp-admin/includes/class-core-upgrader.php |
Upgrade WordPress core. |
Theme_Upgrader::install() wp-admin/includes/class-theme-upgrader.php |
Install a theme package. |
Theme_Upgrader::upgrade() wp-admin/includes/class-theme-upgrader.php |
Upgrade a theme. |
Theme_Upgrader::bulk_upgrade() wp-admin/includes/class-theme-upgrader.php |
Upgrade several themes at once. |
Plugin_Upgrader::bulk_upgrade() wp-admin/includes/class-plugin-upgrader.php |
Bulk upgrade several plugins at once. |
Plugin_Upgrader::install() wp-admin/includes/class-plugin-upgrader.php |
Install a plugin package. |
Plugin_Upgrader::upgrade() wp-admin/includes/class-plugin-upgrader.php |
Upgrade a plugin. |
WP_Upgrader::install_package() wp-admin/includes/class-wp-upgrader.php |
Install a package. |
WP_Upgrader::run() wp-admin/includes/class-wp-upgrader.php |
Run an upgrade/installation. |
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. |
Theme_Upgrader_Skin::__construct() wp-admin/includes/class-theme-upgrader-skin.php |
Constructor. |
Language_Pack_Upgrader_Skin::__construct() wp-admin/includes/class-language-pack-upgrader-skin.php | |
Theme_Installer_Skin::__construct() wp-admin/includes/class-theme-installer-skin.php | |
Plugin_Installer_Skin::__construct() wp-admin/includes/class-plugin-installer-skin.php | |
Bulk_Upgrader_Skin::__construct() wp-admin/includes/class-bulk-upgrader-skin.php | |
Plugin_Upgrader_Skin::__construct() wp-admin/includes/class-plugin-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 |
An internal method that 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 |
Ajax handler for getting themes from themes_api() . |
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 |
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 |
Parse a query string and set 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_Curl::request() wp-includes/class-wp-http-curl.php |
Send a HTTP request to a URI using cURL extension. |
WP_Http_Streams::request() wp-includes/class-wp-http-streams.php |
Send a HTTP request to a URI using PHP Streams. |
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_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_Meta::form() wp-includes/widgets/class-wp-widget-meta.php |
Outputs the settings form for the Meta widget. |
WP_Widget_Pages::form() wp-includes/widgets/class-wp-widget-pages.php |
Outputs the settings form for the Pages widget. |
WP_Widget_Links::form() wp-includes/widgets/class-wp-widget-links.php |
Outputs the settings form for the Links 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. |
get_terms() wp-includes/taxonomy.php |
Retrieves the terms in a given taxonomy or list of taxonomies. |
term_exists() wp-includes/taxonomy.php |
Determines whether a taxonomy term exists. |
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 a 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. |
get_approved_comments() wp-includes/comment.php |
Retrieves the approved comments for a post. |
register_meta() wp-includes/meta.php |
Registers a meta key. |
_WP_Editors::parse_settings() wp-includes/class-wp-editor.php |
Parse default arguments for the editor instance. |
Changelog
Version | Description |
---|---|
2.3.0 | $args can now also be an object. |
2.2.0 | Introduced. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.
Basic usage:
Thank you bhlarsen for this function but there is a little mistake:
must be replaced by
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.If you are looking to recursively merge two arrays, here is the function:
Test case: