add_query_arg ()

Retrieve a modified URL query string.

You can rebuild the URL and append a new query variable to the URL query by using this function. You can also retrieve the full URL with query data.

Adding a single key & value or an associative array. Setting a key value to an empty string removes the key. Omitting oldquery_or_uri uses the $_SERVER value. Additional values provided are expected to be encoded appropriately with urlencode() or rawurlencode().

Return: (string) New URL query string.

Source file: wp-includes/functions.php

View source


Parameters

$param1

(string|array) (Required) Either newkey or an associative_array.

$param2

(string) (Required) Either newvalue or oldquery or URI.

$param3

(string) (Optional) Old query or URI.


Explanation

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', ...), $old_query_or_uri );

Used by

Uses


Source

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


Changelog


User Contributed Notes

  1. 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 ) );
    
  2. 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/' ) );
    
  3. 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. Removing values and setting via an associative array:

    $query = 'http://example.com/link?foo=bar';
    $new_query = add_query_arg( array(
    	'foo' => false,
    	'baz' => 'qux'
    ), $query );
    print( $new_query );
    // http://example.com/link?baz=qux