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 );
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.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:
To safely redirect user to a custom page inside
plugins.php
A way to get the current total url using
add_query_arg