add_query_arg() – Retrieves a modified URL query string.

You appear to be a bot. Output may be restricted

Description

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.

Usage

$string = add_query_arg( $args );

Parameters

$args
( mixed ) optional

Returns

string New URL query string (unescaped).

Source

File name: wordpress/wp-includes/functions.php
Lines:

1 to 67 of 67
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 ( 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 ( 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;
}
 

 View on GitHub View on Trac