add_query_arg()
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.
No Hooks.
Return
String
. New URL query string (unescaped).
Usage
add_query_arg( ...$args );
- ...$args (required)
- -
Examples
#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;
#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.
#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.
#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
#5 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
#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. |