WordPress как на ладони
Недорогой хостинг для сайтов на WordPress: wordpress.jino.ru

add_query_arg() WP 1.5

Добавляет указанные параметры 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()

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

Хуков нет.

Возвращает

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

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

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

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

$new_url = add_query_arg( array('key1'=>'value1', 'key2'=>'value2' ), $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

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

#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://ссылка_на_пост_9?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 Formalized the existing and already documented parameters by adding ...$args to the function signature.

Код add_query_arg() WP 5.5.1

wp-includes/functions.php
<?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 ); // 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, '?' );
	return $ret;
}

Cвязанные функции

Из раздела: Основной запрос WP

24 коммента
Полезные 3 Вопросы 2 Все