add_query_arg() │ WP 1.5.0

Retrieves a modified URL query string.

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.

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.

Return

String. New URL query string (unescaped).

Usage

add_query_arg( ...$args );
...$args (required)
-

Examples

1

#1 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

#2 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

#3 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

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

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

#5 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 );
0

#6 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;

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.5.2

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