add_query_arg() │ WP 1.5.0

Добавляет указанные параметры GET запроса в текущий или указанный URL.

Функция позволяет удобно создавать URL, добавляя в него новые параметры запроса: ?var=val&var_2=val_2.

Если в значении параметра указать false: [ 'key'=>false ], то функция удалит указанный параметр запроса из УРЛ.

Если пропустить второй и третий параметры, функция будет использовать вместо них значения глобального массива $_SERVER['REQUEST_URI'].

Важно! Функция не использует esc_url(), т.е. не очищает результат. Поэтому, если вы не указываете в функции в какой УРЛ нужно добавить данные, то функция использует $_SERVER['REQUEST_URI'], поэтому перед выводом обязательно нужно очищайте УРЛ с помощью esc_url(). Нужно это, для защиты от XSS атак, т.к. любой пользователь может дописать в УРЛ произвольный параметр запроса, который затем будет выведен в HTML самой страницы.

Важно! Передаваемый URL в результате парсится PHP функцией parse_str(), у которой есть следующая особенность: имена переменных PHP не могут содержать пробелы и точки ., эти символы будут заменены на символ подчеркивания _.

На примере этой функции, данное замечание выглядит так:

$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

// Пример с пробелом
$url = 'https://ya.ru?my key=123';
echo $url = add_query_arg( ['foo'=>'bar'], $url ); // https://ya.ru?my_key=123&foo=bar

Функция обратная этой: wp_parse_str()

Работает на основе: build_query()

Основа для: get_edit_term_link(), remove_query_arg()

1 раз — 0.000057 сек (очень быстро) | 50000 раз — 0.12 сек (очень быстро) | PHP 7.1.5, WP 4.8.2

Хуков нет.

Возвращает

Строку. Новый URL с параметрами запроса.

Шаблон использования

$new_url = add_query_arg( [ 'key1'=>'value1', 'key2'=>'value2' ], $uri );

Использование

add_query_arg( $param1, $param2, $old_query_or_uri );

$param1(строка/массив/логический) (обязательный): Новый ключ или ассоциативный массив новых параметров запроса: array( ключ => значение ).
$param2(строка/массив/логический): Новое значение параметра (если в первом параметре была указана строка - ключ). Или URL в который нужно добавить параметры, если в первом значении указан массив. По умолчанию используется текущий УРЛ — $_SERVER[REQUEST_URI].
$old_query_or_uri(строка/массив): Старый запрос или URL.
По умолчанию: $_SERVER[REQUEST_URI]

Примеры

#1 Добавим параметры к УРЛу поста 9

Получим УРЛ функцией get_permalink():

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

// получим: http://example.com/post-name?hello=there

#2 Добавляем параметры в текущий УРЛ страницы

Предположим мы находимся на странице http://example.com/client/?s=word, тогда:

echo esc_url( add_query_arg( 'foo', 'bar' ) );
// вернет: /client/?s=word&foo=bar

$arr_params = array( 'foo' => 'bar', 'baz' => 'tiny' );
echo esc_url( add_query_arg( $arr_params ) );
// вернет: /client/?s=word&foo=bar&baz=tiny

Важно! В таком коде, когда не указан конкретный УРЛ куда добавляются параметры, нужно обязательно использовать esc_url() перед выводом результата на экран. Потому что параметры запроса могут быть добавлены пользователем произвольно.

#3 Добавляем параметры в указанный УРЛ

Если нужно обработать не тот УРЛ на котором мы находимся сейчас, а любой другой, то нужно указать его в третьем или втором параметре, см. оба примера.

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

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

// оба примера вернут: http://blog.example.com/2009/04/16/?hello=world

Здесь нет нужды использовать esc_url(), как в примере выше, потому что мы знаем к какому УРЛ добавляются параметры и он не может быть изменен пользователем.

#4 Удалим параметр запроса из URL:

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

#5 Разные варианты установки параметров

// можно добавить параметр в текущий Url так
$url = add_query_arg( 'foo' );

// или задать ему значение
$url = add_query_arg( 'foo', 'bar' );

// или указать для какого URL это делается
$url = add_query_arg( 'foo', 'bar', $URL ); // передается 3 параметра

// или так
$url = add_query_arg( [ 'foo'=>'bar' ], $URL ); // передается 2 параметра

// или так
$url = add_query_arg( [ 'foo'=>'bar' ] ); // передается 1 параметр

Список изменений

С версии 1.5.0	Введена.
С версии 5.3.0	Formalized the existing and already documented parameters by adding `...$args` to the function signature.

Код `add_query_arg() add query arg` ^{WP 6.7.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;
}