add_query_arg( $args ): string

Retrieves a modified URL query string.

Contents

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.

Top ↑

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.

Top ↑

Return

string New URL query string (unescaped).

Top ↑

More Information

Top ↑

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

Top ↑

Source

File: wp-includes/functions.php. View all references 

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, '?' );
	$ret = str_replace( '?#', '#', $ret );
	return $ret;
}

View on Trac View on GitHub

Top ↑

Top ↑

Uses

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

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

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

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

Top ↑

Used By

Used By
Used By Description
WP_REST_Sidebars_Controller::prepare_links() wp-includes/rest-api/endpoints/class-wp-rest-sidebars-controller.php

Prepares links for the sidebar.
core_auto_updates_settings() wp-admin/update-core.php

Display WordPress auto-updates settings.
WP_REST_Block_Directory_Controller::prepare_links() wp-includes/rest-api/endpoints/class-wp-rest-block-directory-controller.php

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

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

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

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

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

Actions column.
WP_Privacy_Data_Removal_Requests_List_Table::column_next_steps() wp-admin/includes/class-wp-privacy-data-removal-requests-list-table.php

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

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

Actions column.
WP_Privacy_Data_Export_Requests_List_Table::column_next_steps() wp-admin/includes/class-wp-privacy-data-export-requests-list-table.php

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

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

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

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

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

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

Tests if the REST API is accessible.
WP_Site_Health::get_test_https_status() wp-admin/includes/class-wp-site-health.php

Tests if the site is serving content over HTTPS.
resume_plugin() wp-admin/includes/plugin.php

Tries to resume a single plugin.
wp_check_php_version() wp-admin/includes/misc.php

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

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

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.
do_block_editor_incompatible_meta_box() wp-admin/includes/template.php

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Retrieves theme installer pages from the WordPress.org Themes API.
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() wp-admin/includes/class-wp-plugins-list-table.php

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

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

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

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

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

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

Prints column headers, accounting for hidden and sortable columns.
WP_List_Table::set_pagination_args() wp-admin/includes/class-wp-list-table.php

An internal method that sets all the necessary pagination arguments
WP_MS_Themes_List_Table::get_views() wp-admin/includes/class-wp-ms-themes-list-table.php
set_screen_options() wp-admin/includes/misc.php

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

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

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

Displays update information for a plugin.
wp_theme_update_row() wp-admin/includes/update.php

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

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

Displays plugin information in dialog box form.
wp_dashboard_browser_nag() wp-admin/includes/dashboard.php

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

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

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

Activates multiple plugins.
activate_plugin() wp-admin/includes/plugin.php

Attempts activation of plugin in a “sandbox” and redirects on success.
WP_Plugin_Install_List_Table::display_rows() wp-admin/includes/class-wp-plugin-install-list-table.php
WP_Users_List_Table::single_row() wp-admin/includes/class-wp-users-list-table.php

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

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

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

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

Retrieves the upload iframe source URL.
_admin_notice_post_locked() wp-admin/includes/post.php

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

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

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

Displays post submit form fields.
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-comments-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-wp-terms-list-table.php
Walker_Nav_Menu_Edit::start_el() wp-admin/includes/class-walker-nav-menu-edit.php

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

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

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

Meta widget used to display the control form for a widget.
WP_Posts_List_Table::get_views() wp-admin/includes/class-wp-posts-list-table.php
wp_get_popular_importers() wp-admin/includes/import.php

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

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

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

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

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

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

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

Retrieves paginated links for archive post pages.
wp_admin_css_uri() wp-includes/general-template.php

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

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

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

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

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

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

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

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

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

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

Retrieves the comments page number link.
paginate_comments_links() wp-includes/link-template.php

Displays or retrieves pagination links for the comments on the current post.
get_pagenum_link() wp-includes/link-template.php

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

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

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

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

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

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

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

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

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

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

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

Helper function for wp_link_pages() .
wp_enqueue_media() wp-includes/media.php

Enqueues all scripts, styles, settings, and templates necessary to use all media JS APIs.
wp_video_shortcode() wp-includes/media.php

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

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

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

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

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

Processes a script dependency.
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_style_loader_src() wp-includes/script-loader.php

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

Prints the templates used in the media manager.
Show 146 more used by Hide more used by

Top ↑

Changelog

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

Top ↑

User Contributed Notes

  1. Skip to note 1 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 23You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Assuming we’re at the WordPress URL “http://blog.example.com/client/?s=word”… Note the use of esc_url() before outputting the link. This is necessary because this function does not escape URLs and if output without escaping, would make the page vulnerable to XSS scripting.

    // This would output '/client/?s=word&foo=bar'
echo esc_url( add_query_arg( 'foo', 'bar' ) );

// This would output '/client/?s=word&foo=bar&baz=tiny'
$arr_params = array( 'foo' => 'bar', 'baz' => 'tiny' );
echo esc_url( add_query_arg( $arr_params ) );
  3. Skip to note 3 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    Since get_permalink() returns a full URL, you could use that when you want to add variables to a post’s page.

    /*
 * This would output whatever the URL to post ID 9 is, with 'hello=there'
 * appended with either ? or &, depending on what's needed.
 */
echo esc_url( add_query_arg( 'hello', 'there', get_permalink( 9 ) ) );
  4. Skip to note 4 content
    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note
    Contributed by Codex —

    More often than not you’ll probably find yourself creating URLs using the following method within the page you’re currently on. In these cases you can use the URL you want to affect as the last parameter. The use of esc_url() is not required here, because the value is known to be safe.

    // This would output 'http://blog.example.com/2009/04/16/?hello=world'
echo esc_url( add_query_arg( 'hello', 'world', 'http://blog.example.com/2009/04/16/' ) );
  7. Skip to note 7 content
    You must log in to vote on the helpfulness of this noteVote results for this note: -4You must log in to vote on the helpfulness of this note
    Contributed by janw.oostendorp —

    A way to get the current total url using add_query_arg

    home_url( add_query_arg( null, null ));

You must log in before being able to contribute a note or feedback.