add_query_arg()
Retrieves a modified URL query string.
Contents
Description #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 #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 #Return
(string) New URL query string (unescaped).
Source #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 full source code Collapse full source code View on Trac
Changelog #Changelog
Version | Description |
---|---|
1.5.0 | Introduced. |
More Information #More Information
Usage #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 );
Related #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-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_privacy_send_request_confirmation_notification() |
Notify the site administrator via email when a request is confirmed. |
wp-includes/user.php: wp_send_user_request() |
Send a confirmation request email to confirm an action. |
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/user.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() |
Attempt 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() |
Encapsulate 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::__construct() |
Constructor. |
wp-admin/includes/class-theme-upgrader-skin.php: Theme_Upgrader_Skin::after() | |
wp-admin/includes/class-theme-installer-skin.php: Theme_Installer_Skin::after() | |
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/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() | |
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/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/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-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/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() |
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/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. |
User Contributed Notes #User Contributed Notes
You must log in before being able to contribute a note or feedback.
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.To safely redirect user to a custom page inside
plugins.php
Since
get_permalink()
returns a full URL, you could use that when you want to add variables to a post’s page.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.Removing values and setting via an associative array:
A way to get the current total url using
add_query_arg