add_query_arg()
Додає вказані параметри 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()
(дуже швидко) | 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. |