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

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

$value

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

$url

(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

Related

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.