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 Додаємо параметри до поточної УРЛ сторінки

Припустимо, ми знаходимося на сторінці 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() перед виведенням результату на екран. Тому що параметри запиту можуть додаватися користувачем довільно.

#2 Додаємо параметри до зазначеного УРЛ

Якщо потрібно обробити не той УРЛ на якому ми зараз, а будь-який інший, то потрібно вказати його в третьому або другому параметрі, див.

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/' );

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

Тут немає потреби використовувати esc_url() , як у прикладі вище, тому що ми знаємо, до якого УРЛ додаються параметри і він не може бути змінений користувачем.

#3 Додамо параметри до УРЛу посту 9

Отримаємо УРЛ функцією get_permalink() :

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

// Отримаємо: http://example.com/post-name?hello=there

#4 Видалимо параметр запиту з URL:

$url = 'http://example.com/asd?key=val&key_1=val_1';
echo esc_url(add_query_arg(array('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( array('foo'=>'bar'), $URL ); // передається 2 параметри

// або так
$url = add_query_arg( array('foo'=>'bar') ); // Передається 1 параметр

список змін

З версії 1.5.0	Введено.
З версії 5.3.0	Formalizated the existing and already documented parameters by adding `…$args` to the функція signature.

add query arg ^{WP 6.0.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 ( 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); // Це 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;
}