W3cubDocs

/WordPress

add_query_arg( $args )

Retrieves a modified URL query string.

Description

You can rebuild the URL and append query variables to the URL query by using this function. There are two ways to use this function; either a single key and value, or an associative array.

Using a single key and value:

add_query_arg( 'key', 'value', 'http://example.com' );

Using an associative array:

add_query_arg( array(
    'key1' => 'value1',
    'key2' => 'value2',
), 'http://example.com' );

Omitting the URL from either use results in the current URL being used (the value of $_SERVER['REQUEST_URI']).

Values are expected to be encoded appropriately with urlencode() or rawurlencode().

Setting any query variable’s value to boolean false removes the key (see remove_query_arg()).

Important: The return value of add_query_arg() is not escaped by default. Output should be late-escaped with esc_url() or similar to help prevent vulnerability to cross-site scripting (XSS) attacks.

Parameters

$key

(string|array) (Required) Either a query variable key, or an associative array of query variables.

$value

(string) (Optional) Either a query variable value, or a URL to act upon.

$url

(string) (Optional) A URL to act upon.

Return

(string) New URL query string (unescaped).

More Information

Usage 

// Parameters as separate arguments
add_query_arg( $param1, $param2, $old_query_or_uri );

// Parameters as array of key => value pairs
add_query_arg( 
    array( 
        'key1' => 'value1',
        'key2' => 'value2',
        ...
    ), 
    $old_query_or_uri 
);

Source

File: wp-includes/functions.php 

function add_query_arg( ...$args ) {
	if ( is_array( $args[0] ) ) {
		if ( count( $args ) < 2 || false === $args[1] ) {
			$uri = $_SERVER['REQUEST_URI'];
		} else {
			$uri = $args[1];
		}
	} else {
		if ( count( $args ) < 3 || false === $args[2] ) {
			$uri = $_SERVER['REQUEST_URI'];
		} else {
			$uri = $args[2];
		}
	}

	$frag = strstr( $uri, '#' );
	if ( $frag ) {
		$uri = substr( $uri, 0, -strlen( $frag ) );
	} else {
		$frag = '';
	}

	if ( 0 === stripos( $uri, 'http://' ) ) {
		$protocol = 'http://';
		$uri      = substr( $uri, 7 );
	} elseif ( 0 === stripos( $uri, 'https://' ) ) {
		$protocol = 'https://';
		$uri      = substr( $uri, 8 );
	} else {
		$protocol = '';
	}

	if ( strpos( $uri, '?' ) !== false ) {
		list( $base, $query ) = explode( '?', $uri, 2 );
		$base                .= '?';
	} elseif ( $protocol || strpos( $uri, '=' ) === false ) {
		$base  = $uri . '?';
		$query = '';
	} else {
		$base  = '';
		$query = $uri;
	}

	wp_parse_str( $query, $qs );
	$qs = urlencode_deep( $qs ); // This re-URL-encodes things that were already in the query string.
	if ( is_array( $args[0] ) ) {
		foreach ( $args[0] as $k => $v ) {
			$qs[ $k ] = $v;
		}
	} else {
		$qs[ $args[0] ] = $args[1];
	}

	foreach ( $qs as $k => $v ) {
		if ( false === $v ) {
			unset( $qs[ $k ] );
		}
	}

	$ret = build_query( $qs );
	$ret = trim( $ret, '?' );
	$ret = preg_replace( '#=(&|$)#', '$1', $ret );
	$ret = $protocol . $base . $ret . $frag;
	$ret = rtrim( $ret, '?' );
	return $ret;
}

Uses

Uses Description
wp-includes/class-pop3.php: stripos()
wp-includes/formatting.php: wp_parse_str()

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

Navigates through an array, object, or scalar, and encodes the values to be used in a URL.
wp-includes/functions.php: build_query()

Build URL query based on an associative and, or indexed array.

Used By

Used By Description
wp-includes/rest-api/endpoints/class-wp-rest-block-directory-controller.php: WP_REST_Block_Directory_Controller::prepare_links()

Generates a list of links to include in the response for the plugin.
wp-includes/rest-api/endpoints/class-wp-rest-block-types-controller.php: WP_REST_Block_Types_Controller::prepare_links()

Prepares links for the request.
wp-admin/includes/class-plugin-installer-skin.php: Plugin_Installer_Skin::do_overwrite()

Check if the plugin can be overwritten and output the HTML for overwriting a plugin on upload.
wp-admin/includes/class-theme-installer-skin.php: Theme_Installer_Skin::do_overwrite()

Check if the theme can be overwritten and output the HTML for overwriting a theme on upload.
wp-admin/includes/class-wp-ms-themes-list-table.php: WP_MS_Themes_List_Table::column_autoupdates()

Handles the auto-updates column output.
wp-admin/includes/class-wp-privacy-data-removal-requests-list-table.php: WP_Privacy_Data_Removal_Requests_List_Table::column_next_steps()

Next steps column.
wp-admin/includes/class-wp-ms-sites-list-table.php: WP_MS_Sites_List_Table::get_views()

Gets links to filter sites by status.
wp-admin/includes/class-wp-privacy-data-export-requests-list-table.php: WP_Privacy_Data_Export_Requests_List_Table::column_next_steps()

Displays the next steps column.
wp-includes/class-wp-recovery-mode-link-service.php: WP_Recovery_Mode_Link_Service::handle_begin_link()

Enters recovery mode when the user hits wp-login.php with a valid recovery mode link.
wp-includes/class-wp-recovery-mode-link-service.php: WP_Recovery_Mode_Link_Service::get_recovery_mode_begin_url()

Gets a URL to begin recovery mode.
wp-includes/admin-bar.php: wp_admin_bar_recovery_mode_menu()

Add a link to exit recovery mode when Recovery Mode is active.
wp-admin/includes/theme.php: resume_theme()

Tries to resume a single theme.
wp-admin/includes/update.php: wp_recovery_mode_nag()

Displays a notice when the user is in recovery mode.
wp-admin/includes/class-wp-site-health.php: WP_Site_Health::get_test_rest_availability()

Test if the REST API is accessible.
wp-admin/includes/plugin.php: resume_plugin()

Tries to resume a single plugin.
wp-admin/includes/class-wp-site-health-auto-updates.php: WP_Site_Health_Auto_Updates::test_wp_version_check_attached()

Check if updates are intercepted by a filter.
wp-admin/includes/misc.php: wp_check_php_version()

Checks if the user needs to update PHP.
wp-includes/rest-api/endpoints/class-wp-rest-search-controller.php: WP_REST_Search_Controller::get_items()

Retrieves a collection of search results.
wp-includes/script-loader.php: wp_get_script_polyfill()

Returns contents of an inline script used in appending polyfill scripts for browsers which fail the provided tests. The provided array is a mapping from a condition to verify feature support to its polyfill script handle.
wp-admin/includes/template.php: do_block_editor_incompatible_meta_box()

Function that renders a “fake” meta box with an information message, shown on the block editor, when an incompatible meta box is found.
wp-includes/user.php: wp_send_user_request()

Send a confirmation request email to confirm an action.
wp-admin/includes/class-wp-privacy-requests-table.php: WP_Privacy_Requests_Table::get_views()

Get an associative array ( id => link ) with the list of views available on this table.
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::handle_load_themes_request()

Load themes into the theme browsing/installation UI.
wp-admin/press-this.php: wp_load_press_this()
wp-admin/includes/misc.php: wp_print_plugin_file_tree()

Outputs the formatted file list for the plugin editor.
wp-admin/includes/misc.php: wp_print_theme_file_tree()

Outputs the formatted file list for the theme editor.
wp-admin/includes/file.php: wp_edit_theme_plugin_file()

Attempts to edit a file for a theme or plugin.
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::add_state_query_params()

Add customize state query params to a given URL if preview is allowed.
wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php: WP_REST_Users_Controller::get_items()

Retrieves all users.
wp-includes/rest-api/endpoints/class-wp-rest-revisions-controller.php: WP_REST_Revisions_Controller::get_items()

Gets a collection of revisions.
wp-includes/rest-api/endpoints/class-wp-rest-post-statuses-controller.php: WP_REST_Post_Statuses_Controller::prepare_item_for_response()

Prepares a post status object for serialization.
wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php: WP_REST_Terms_Controller::prepare_links()

Prepares links for the request.
wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php: WP_REST_Terms_Controller::get_items()

Retrieves terms associated with a taxonomy.
wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php: WP_REST_Posts_Controller::prepare_links()

Prepares links for the request.
wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php: WP_REST_Posts_Controller::get_items()

Retrieves a collection of posts.
wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php: WP_REST_Comments_Controller::prepare_links()

Prepares links for the request.
wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php: WP_REST_Comments_Controller::get_items()

Retrieves a list of comment items.
wp-includes/link-template.php: wp_get_canonical_url()

Returns the canonical URL for a post.
wp-admin/includes/ms.php: network_edit_site_nav()

Outputs the HTML for a network’s “Edit Site” tabular interface.
wp-admin/includes/ajax-actions.php: wp_ajax_search_install_plugins()

Ajax handler for searching plugins to install.
wp-admin/includes/ajax-actions.php: wp_ajax_search_plugins()

Ajax handler for searching plugins.
wp-admin/includes/ajax-actions.php: wp_ajax_install_theme()

Ajax handler for installing a theme.
wp-admin/includes/ajax-actions.php: wp_ajax_install_plugin()

Ajax handler for installing a plugin.
wp-includes/rest-api.php: get_rest_url()

Retrieves the URL to a REST endpoint on a site.
wp-includes/embed.php: get_post_embed_url()

Retrieves the URL to embed a specific post in an iframe.
wp-includes/embed.php: get_oembed_endpoint_url()

Retrieves the oEmbed endpoint URL for a given permalink.
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::customize_pane_settings()

Print JavaScript settings for parent window.
wp-includes/link-template.php: get_preview_post_link()

Retrieves the URL used for the post preview.
wp-admin/includes/class-wp-posts-list-table.php: WP_Posts_List_Table::get_edit_link()

Helper to create links to edit.php with params.
wp-includes/admin-bar.php: wp_admin_bar_customize_menu()

Adds the “Customize” link to the Toolbar.
wp-admin/includes/class-wp-ms-themes-list-table.php: WP_MS_Themes_List_Table::column_name()

Handles the name column output.
wp-admin/includes/class-wp-terms-list-table.php: WP_Terms_List_Table::handle_row_actions()

Generates and displays row action links.
wp-admin/includes/class-wp-ms-users-list-table.php: WP_MS_Users_List_Table::handle_row_actions()

Generates and displays row action links.
wp-admin/includes/class-wp-ms-users-list-table.php: WP_MS_Users_List_Table::column_username()

Handles the username column output.
wp-admin/includes/class-wp-media-list-table.php: WP_Media_List_Table::column_author()

Handles the author column output.
wp-admin/includes/class-wp-media-list-table.php: WP_Media_List_Table::column_parent()

Handles the parent column output.
wp-admin/includes/class-wp-media-list-table.php: WP_Media_List_Table::column_default()

Handles output for the default column.
wp-includes/link-template.php: get_avatar_data()

Retrieves default data about the avatar.
wp-admin/includes/media.php: wp_media_attach_action()

Encapsulates the logic for Attach/Detach actions.
wp-admin/includes/theme.php: wp_prepare_themes_for_js()

Prepare themes for JavaScript.
wp-admin/includes/theme.php: get_theme_update_available()

Retrieve the update link if there is a theme update available.
wp-admin/includes/theme.php: themes_api()

Retrieves theme installer pages from the WordPress.org Themes API.
wp-admin/includes/class-wp-plugins-list-table.php: WP_Plugins_List_Table::get_views()
wp-admin/includes/class-wp-plugins-list-table.php: WP_Plugins_List_Table::single_row()
wp-admin/includes/class-wp-plugins-list-table.php: WP_Plugins_List_Table::__construct()

Constructor.
wp-admin/includes/class-theme-upgrader-skin.php: Theme_Upgrader_Skin::after()

Action to perform following a single theme update.
wp-admin/includes/class-theme-installer-skin.php: Theme_Installer_Skin::after()

Action to perform following a single theme install.
wp-admin/includes/class-wp-list-table.php: WP_List_Table::view_switcher()

Displays a view switcher.
wp-admin/includes/class-wp-list-table.php: WP_List_Table::comments_bubble()

Displays a comment count bubble.
wp-admin/includes/class-wp-list-table.php: WP_List_Table::pagination()

Displays the pagination.
wp-admin/includes/class-wp-list-table.php: WP_List_Table::print_column_headers()

Prints column headers, accounting for hidden and sortable columns.
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/class-wp-ms-themes-list-table.php: WP_MS_Themes_List_Table::get_views()
wp-admin/includes/misc.php: set_screen_options()

Saves option for number of rows when listing posts, pages, comments, etc.
wp-admin/includes/class-wp-theme-install-list-table.php: WP_Theme_Install_List_Table::install_theme_info()

Prints the info for a theme (to be used in the theme installer modal).
wp-admin/includes/class-wp-theme-install-list-table.php: WP_Theme_Install_List_Table::single_row()

Prints a theme from the WordPress.org API.
wp-admin/includes/update.php: wp_theme_update_row()

Displays update information for a theme.
wp-admin/includes/plugin-install.php: plugins_api()

Retrieves plugin installer pages from the WordPress.org Plugins API.
wp-admin/includes/plugin-install.php: install_plugin_information()

Display plugin information in dialog box form.
wp-admin/includes/dashboard.php: wp_welcome_panel()

Displays a welcome panel to introduce users to WordPress.
wp-admin/includes/dashboard.php: wp_dashboard_browser_nag()

Displays the browser update nag.
wp-admin/includes/dashboard.php: wp_add_dashboard_widget()

Adds a new dashboard widget.
wp-admin/includes/plugin.php: menu_page_url()

Get the URL to access a particular menu page based on the slug it was registered with.
wp-admin/includes/plugin.php: activate_plugin()

Attempts activation of plugin in a “sandbox” and redirects on success.
wp-admin/includes/plugin.php: activate_plugins()

Activate multiple plugins.
wp-admin/includes/class-wp-plugin-install-list-table.php: WP_Plugin_Install_List_Table::display_rows()
wp-admin/includes/class-wp-users-list-table.php: WP_Users_List_Table::single_row()

Generate HTML for a single row on the users.php admin panel.
wp-admin/includes/class-wp-users-list-table.php: WP_Users_List_Table::get_views()

Return an associative array listing all the views that can be used with this table.
wp-admin/includes/media.php: media_upload_library_form()

Outputs the legacy media upload form for the media library.
wp-admin/includes/media.php: the_media_upload_tabs()

Outputs the legacy media upload tabs UI.
wp-admin/includes/media.php: get_upload_iframe_src()
wp-admin/includes/post.php: _admin_notice_post_locked()

Outputs the HTML for the notice to say that someone else is editing or has taken over editing of this post.
wp-admin/includes/ajax-actions.php: wp_ajax_query_themes()

Ajax handler for getting themes from themes_api().
wp-admin/includes/revision.php: wp_prepare_revisions_for_js()

Prepare revisions for JavaScript.
wp-admin/includes/meta-boxes.php: post_submit_meta_box()

Displays post submit form fields.
wp-admin/includes/class-wp-comments-list-table.php: WP_Comments_List_Table::column_author()
wp-admin/includes/class-wp-comments-list-table.php: WP_Comments_List_Table::get_views()
wp-admin/includes/class-wp-terms-list-table.php: WP_Terms_List_Table::column_name()
wp-admin/includes/class-wp-terms-list-table.php: WP_Terms_List_Table::column_posts()
wp-admin/includes/class-walker-nav-menu-edit.php: Walker_Nav_Menu_Edit::start_el()

Start the element output.
wp-admin/includes/nav-menu.php: wp_nav_menu_item_post_type_meta_box()

Displays a meta box for a post type menu item.
wp-admin/includes/nav-menu.php: wp_nav_menu_item_taxonomy_meta_box()

Displays a meta box for a taxonomy menu item.
wp-admin/includes/widgets.php: wp_widget_control()

Meta widget used to display the control form for a widget.
wp-admin/includes/import.php: wp_get_popular_importers()

Returns a list from WordPress.org of popular importer plugins.
wp-admin/includes/class-custom-image-header.php: Custom_Image_Header::step_1()

Display first step of custom header image page.
wp-admin/includes/class-custom-image-header.php: Custom_Image_Header::step_2()

Display second step of custom header image page.
wp-admin/includes/post.php: redirect_post()

Redirect to previous page.
wp-admin/menu-header.php: _wp_menu_output()

Display menu.
wp-includes/class.wp-styles.php: WP_Styles::_css_href()

Generates an enqueued style’s fully-qualified URL.
wp-includes/cron.php: spawn_cron()

Sends a request to run cron through HTTP request that doesn’t halt page loading.
wp-includes/general-template.php: paginate_links()

Retrieve paginated link for archive post pages.
wp-includes/general-template.php: wp_admin_css_uri()

Displays the URL of a WordPress admin CSS file.
wp-includes/general-template.php: wp_get_archives()

Display archive links based on type and format.
wp-includes/general-template.php: wp_logout_url()

Retrieves the logout URL.
wp-includes/general-template.php: wp_login_url()

Retrieves the login URL.
wp-includes/general-template.php: wp_lostpassword_url()

Returns the URL that allows the user to retrieve the lost password
wp-includes/deprecated.php: dropdown_cats()

Deprecated method for generating a drop-down of categories.
wp-includes/deprecated.php: wp_get_links()

Gets the links associated with category.
wp-includes/functions.php: wp_auth_check_html()

Output the HTML that shows the wp-login dialog when the user is no longer logged in.
wp-includes/functions.php: wp_nonce_url()

Retrieve URL with nonce added to URL query.
wp-includes/functions.php: remove_query_arg()

Removes an item or items from a query string.
wp-includes/link-template.php: get_comments_pagenum_link()

Retrieves the comments page number link.
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_pagenum_link()

Retrieves the link for a page number.
wp-includes/link-template.php: get_edit_user_link()

Retrieves the edit user link.
wp-includes/link-template.php: get_search_comments_feed_link()

Retrieves the permalink for the search results comments feed.
wp-includes/link-template.php: get_post_type_archive_feed_link()

Retrieves the permalink for a post type archive feed.
wp-includes/link-template.php: get_delete_post_link()

Retrieves the delete posts link for post.
wp-includes/link-template.php: get_edit_term_link()

Retrieves the URL for editing a given term.
wp-includes/link-template.php: get_search_feed_link()

Retrieves the permalink for the search results feed.
wp-includes/link-template.php: get_post_comments_feed_link()

Retrieves the permalink for the post comments feed.
wp-includes/link-template.php: get_post_permalink()

Retrieves the permalink for a post of a custom post type.
wp-includes/class-wp-oembed.php: WP_oEmbed::fetch()

Connects to a oEmbed provider and returns the result.
wp-includes/class-wp-oembed.php: WP_oEmbed::_fetch_with_format()

Fetches result from an oEmbed provider for a specific format and complete provider URL
wp-includes/post-template.php: _wp_link_page()

Helper function for wp_link_pages().
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_video_shortcode()

Builds the Video shortcode output.
wp-includes/media.php: wp_audio_shortcode()

Builds the Audio shortcode output.
wp-includes/class-wp-rewrite.php: WP_Rewrite::add_rule()

Adds a rewrite rule that transforms a URL structure to a set of query vars.
wp-includes/canonical.php: redirect_canonical()

Redirects incoming links to the proper URL based on the site url.
wp-includes/post-formats.php: _post_format_link()

Filters the post format term link to remove the format prefix.
wp-includes/class.wp-scripts.php: WP_Scripts::do_item()

Processes a script dependency.
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/script-loader.php: wp_style_loader_src()

Administration Screen CSS for changing the styles.
wp-includes/media-template.php: wp_print_media_templates()

Prints the templates used in the media manager.

Changelog

Version Description
5.3.0 Formalized the existing and already documented parameters by adding ...$args to the function signature.
1.5.0 Introduced.

© 2003–2019 WordPress Foundation
Licensed under the GNU GPLv2+ License.
https://developer.wordpress.org/reference/functions/add_query_arg