add_query_arg()

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

Source

File: wp-includes/functions.php

function add_query_arg() {
	$args = func_get_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];
	}

	if ( $frag = strstr( $uri, '#' ) )
		$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 ( $v === false )
			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;
}

Expand Source Code View on GitHub

Uses

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
Used By	Description
wp-includes/deprecated.php: wp_get_links()	Gets the links associated with category.
wp-includes/deprecated.php: dropdown_cats()	Deprecated method for generating a drop-down of categories.
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 ClassicPress 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_lostpassword_url()	Returns the URL that allows the user to retrieve the lost password
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/script-loader.php: wp_style_loader_src()	Administration Screen CSS for changing the styles.
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/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-users-controller.php: WP_REST_Users_Controller::get_items()	Retrieves all users.
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-terms-controller.php: WP_REST_Terms_Controller::prepare_links()	Prepares links for the request.
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-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-posts-controller.php: WP_REST_Posts_Controller::get_items()	Retrieves a collection of posts.
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_audio_shortcode()	Builds the Audio shortcode output.
wp-includes/media.php: wp_video_shortcode()	Builds the Video shortcode output.
wp-includes/class.wp-styles.php: WP_Styles::_css_href()	Generates an enqueued style’s fully-qualified URL.
wp-includes/media-template.php: wp_print_media_templates()	Prints the templates used in the media manager.
wp-includes/admin-bar.php: wp_admin_bar_customize_menu()	Adds the “Customize” link to the Toolbar.
wp-includes/cron.php: spawn_cron()	Sends a request to run cron through HTTP request that doesn’t halt page loading.
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/link-template.php: get_avatar_data()	Retrieves default data about the avatar.
wp-includes/link-template.php: wp_get_canonical_url()	Returns the canonical URL for a post.
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_delete_post_link()	Retrieves the delete posts link for post.
wp-includes/link-template.php: get_edit_user_link()	Retrieves the edit user link.
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_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_preview_post_link()	Retrieves the URL used for the post preview.
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/post-formats.php: _post_format_link()	Filters the post format term link to remove the format prefix.
wp-includes/user.php: wp_send_user_request()	Send a confirmation request email to confirm an action.
wp-includes/user.php: _wp_privacy_send_request_confirmation_notification()	Notify the site administrator via email when a request is confirmed.
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::customize_pane_settings()	Print JavaScript settings for parent window.
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::handle_load_themes_request()	Load themes into the theme browsing/installation UI.
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/post-template.php: _wp_link_page()	Helper function for wp_link_pages().
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/rest-api.php: get_rest_url()	Retrieves the URL to a REST endpoint on a site.
wp-includes/class.wp-scripts.php: WP_Scripts::do_item()	Processes a script dependency.
wp-includes/comment-template.php: get_comment_reply_link()	Retrieve HTML content for reply to comment link.
wp-includes/comment-template.php: get_comment_link()	Retrieve the link to a given comment.
wp-includes/class-oembed.php: WP_oEmbed::fetch()	Connects to a oEmbed provider and returns the result.
wp-includes/class-oembed.php: WP_oEmbed::_fetch_with_format()	Fetches result from an oEmbed provider for a specific format and complete provider URL
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-admin/press-this.php: wp_load_press_this()
wp-admin/custom-header.php: Custom_Image_Header::step_1()	Display first step of custom header image page.
wp-admin/custom-header.php: Custom_Image_Header::step_2()	Display second step of custom header image page.
wp-admin/menu-header.php: _wp_menu_output()	Display menu.
wp-admin/includes/class-wp-media-list-table.php: WP_Media_List_Table::column_default()	Handles output for the default column.
wp-admin/includes/class-theme-upgrader-skin.php: Theme_Upgrader_Skin::after()
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-plugins-list-table.php: WP_Plugins_List_Table::__construct()	Constructor.
wp-admin/includes/class-wp-plugins-list-table.php: WP_Plugins_List_Table::get_views()
wp-admin/includes/misc.php: wp_print_plugin_file_tree()	Outputs the formatted file list for the Plugin Editor.
wp-admin/includes/misc.php: set_screen_options()	Saves option for number of rows when listing posts, pages, comments, etc.
wp-admin/includes/misc.php: wp_print_theme_file_tree()	Outputs the formatted file list for the Theme Editor.
wp-admin/includes/media.php: wp_media_attach_action()	Encapsulate logic for Attach/Detach actions
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-list-table.php: WP_List_Table::view_switcher()	Display a view switcher
wp-admin/includes/class-wp-list-table.php: WP_List_Table::comments_bubble()	Display a comment count bubble
wp-admin/includes/class-wp-list-table.php: WP_List_Table::pagination()	Display the pagination.
wp-admin/includes/class-wp-list-table.php: WP_List_Table::print_column_headers()	Print column headers, accounting for hidden and sortable columns.
wp-admin/includes/media.php: media_upload_library_form()	Outputs the legacy media upload form for the media library.
wp-admin/includes/media.php: get_upload_iframe_src()
wp-admin/includes/class-wp-ms-themes-list-table.php: WP_MS_Themes_List_Table::get_views()
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/media.php: the_media_upload_tabs()	Outputs the legacy media upload tabs UI.
wp-admin/includes/class-wp-comments-list-table.php: WP_Comments_List_Table::get_views()
wp-admin/includes/class-wp-comments-list-table.php: WP_Comments_List_Table::column_author()
wp-admin/includes/translation-install.php: translations_api()	Retrieve translations from ClassicPress Translation API.
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-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-ms-users-list-table.php: WP_MS_Users_List_Table::handle_row_actions()	Generates and displays row action links.
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/plugin-install.php: install_plugin_information()	Display plugin information in dialog box form.
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_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-admin/includes/ajax-actions.php: wp_ajax_search_plugins()	Ajax handler for searching plugins.
wp-admin/includes/ajax-actions.php: wp_ajax_query_themes()	Ajax handler for getting themes from themes_api().
wp-admin/includes/class-wp-plugin-install-list-table.php: WP_Plugin_Install_List_Table::display_rows()
wp-admin/includes/meta-boxes.php: post_submit_meta_box()	Displays post submit form fields.
wp-admin/includes/class-theme-installer-skin.php: Theme_Installer_Skin::after()
wp-admin/includes/user.php: WP_Privacy_Requests_Table::get_views()	Get an associative array ( id => link ) with the list of views available on this table.
wp-admin/includes/user.php: WP_Privacy_Data_Export_Requests_Table::column_next_steps()	Displays the next steps column.
wp-admin/includes/user.php: WP_Privacy_Data_Removal_Requests_Table::column_next_steps()	Next steps column.
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: wp_prepare_themes_for_js()	Prepare themes for JavaScript.
wp-admin/includes/class-walker-nav-menu-edit.php: Walker_Nav_Menu_Edit::start_el()	Start the element output.
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/post.php: redirect_post()	Redirect to previous page.
wp-admin/includes/file.php: wp_edit_theme_plugin_file()	Attempt to edit a file for a theme or plugin.
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/import.php: wp_get_popular_importers()	Returns a list from ClassicPress.net of popular importer plugins.
wp-admin/includes/dashboard.php: wp_dashboard_browser_nag()
wp-admin/includes/update.php: wp_theme_update_row()	Displays update information for a theme.
wp-admin/includes/class-wp-theme-install-list-table.php: WP_Theme_Install_List_Table::single_row()	Prints a theme from the ClassicPress.net API.
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/dashboard.php: wp_add_dashboard_widget()	Adds a new dashboard widget.
wp-admin/includes/ms.php: network_edit_site_nav()	Outputs the HTML for a network’s “Edit Site” tabular interface.
wp-admin/includes/revision.php: wp_prepare_revisions_for_js()	Prepare revisions for JavaScript.
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/widgets.php: wp_widget_control()	Meta widget used to display the control form for a widget.
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::handle_row_actions()	Generates and displays row action links.
wp-admin/includes/class-wp-terms-list-table.php: WP_Terms_List_Table::column_posts()
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.

Show 120 more used by Hide more used by

Changelog

Changelog
Version	Description
WP-1.5.0	Introduced.