add_query_arg() │ WP 1.5.0

Adds the specified GET parameters to the current or specified URL.

The function allows you to conveniently create a URL by adding new query parameters to it: ?var=val&var2=val2.

If you specify false in the parameter value: [ 'key'=>false ], the function will remove the specified query parameter from the URL.

If the second and third parameters are skipped, the function will use the values from the global array $_SERVER['REQUEST_URI'] instead.

Important! The function does not use esc_url(), i.e., it does not sanitize the result. Therefore, if you do not specify in the function which URL to add the data to, the function will use $_SERVER['REQUEST_URI'], so you must sanitize the URL with esc_url() before outputting it. This is necessary to protect against XSS attacks, as any user can append arbitrary query parameters to the URL, which will then be output in the HTML of the page itself.

Important! The passed URL is parsed by the PHP function parse_str(), which has the following peculiarity: PHP variable names cannot contain spaces   and dots ., these characters will be replaced with the underscore character _.

In the example of this function, this note looks like this:

$url = 'https://ya.ru';
echo $url = add_query_arg( ['my.key'=>'123'], $url ); // https://ya.ru?my.key=123
echo $url = add_query_arg( ['foo'=>'bar'], $url );    // https://ya.ru?my_key=123&foo=bar

// Example with space
$url = 'https://ya.ru?my key=123';
echo $url = add_query_arg( ['foo'=>'bar'], $url ); // https://ya.ru?my_key=123&foo=bar

The function opposite to this: wp_parse_str()

Uses: build_query()
Used By: get_edit_term_link(), remove_query_arg()
1 time — 0.000057 sec (very fast) | 50000 times — 0.12 sec (very fast) | PHP 7.1.5, WP 4.8.2

No Hooks.

Returns

String. New URL with query parameters.

Usage

add_query_arg( $key, $value, $url );
// or
add_query_arg( $key, $url );
$key(string/array/bool) (required)
Key (parameter name) to be added.
Or an associative array of new query parameters: [ key => value ].
$value(string/array/bool)
  • The value of the parameter - if a string (key) was specified in the first parameter.
  • The URL to which parameters need to be added - if an array was specified in the first parameter.

By default: the current URL — $_SERVER[REQUEST_URI].

$url(string/array)
The old query or URL.
By default: $_SERVER[REQUEST_URI]

Examples

6

#1 Redirect user

To safely redirect user to a custom page inside plugins.php

// Redirect to Welcome Page.
// Redirects to your-domain.com/wp-admin/plugin.php?page=your_plugin_page.
$redirect_url = add_query_arg( array( 'page' => 'your_plugin_page' ), admin_url( 'plugins.php' ) );
wp_safe_redirect( $redirect_url );
exit;
1

#2 Adding parameters to the specified URL

If you want to process any other URL than the one we are on now, you have to specify it in the third or second parameter, see both examples.

echo add_query_arg( 'hello', 'world', 'http://blog.example.com/2009/04/16/' );

echo add_query_arg( array('hello' => 'world'), 'http://blog.example.com/2009/04/16/' );

// both examples will return: http://blog.example.com/2009/04/16/?hello=world

There is no need to use esc_url() as in the example above, because we know which URL the parameters are added to and it cannot be changed by the user.

0

#3 Adding parameters to the current page URL

Suppose we are at http://example.com/client/?s=word, then:

echo esc_url( add_query_arg( 'foo', 'bar' ) );
// will return: /client/?s=word&foo=bar

$arr_params = array( 'foo' => 'bar', 'baz' => 'tiny' );
echo esc_url( add_query_arg( $arr_params ) );
// will return: /client/?s=word&foo=bar&baz=tiny

Note: In such a code, when no specific URL is specified where parameters are added, it is obligatory to use esc_url() before displaying the result on the screen. This is because request parameters can be added by the user in a custom way.

0

#4 Let's add parameters to the URL of post 9

Get the URL with get_permalink():

echo add_query_arg( 'hello', 'there', get_permalink(9) );

// get: http://example.com/post-name?hello=there
0

#5 Let's remove the query parameter from the URL: 

$url = 'http://example.com/asd?key=val&key2=val2';
echo esc_url( add_query_arg( [ 'key'=>null ], $url ) );
// http://example.com/asd?key2=val2

Or use function remove_query_arg().

0

#6 Different options for setting parameters 

// you can add a parameter to the current Url like this
$url = add_query_arg( 'foo' );

// or set it to a value
$url = add_query_arg( 'foo', 'bar' );

// or like this
$url = add_query_arg( array('foo'=>'bar') );

// Specify for which URL this is done
$url = add_query_arg( 'foo', 'bar', $URL );

// or like this
$url = add_query_arg( array('foo'=>'bar'), $URL );

Changelog

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

add_query_arg() code WP 6.8.1

wp-includes/functions.php 
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 ( str_contains( $uri, '?' ) ) {
		list( $base, $query ) = explode( '?', $uri, 2 );
		$base                .= '?';
	} elseif ( $protocol || ! str_contains( $uri, '=' ) ) {
		$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;
}

Main Query