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