Функция add_query_arg() в WordPress позволяет легко добавлять параметры к URL-адресу, что делает ее полезной для создания динамических ссылок, изменения запросов и перенаправлений. Ниже приведено руководство по использованию add_query_arg() с примерами, где изменены ID и параметры для уникальности.
add_query_arg( $args ): stringФункция add_query_arg() модифицирует URL, добавляя или изменяя параметры запроса. Она принимает либо массив ключ-значение, либо отдельные ключ и значение и возвращает новый URL с учтенными параметрами.
Принцип работы
- Без указания URL: Если URL не указан, используется текущий URL страницы (
$_SERVER['REQUEST_URI']). - Удаление параметров: Если передать параметру значение
false, он будет удален из URL. - Без автоматического экранирования: Результат функции необходимо обрабатывать с помощью
esc_url()для защиты от XSS-атак, особенно если URL формируется на основе запроса пользователя.
Параметры
- $key (строка или массив) — Ключ или массив ключ-значение для параметров запроса.
- $value (строка) — Значение для ключа (если
$key— строка). Если$key— массив,$valueиспользуется как URL. - $url (строка) — URL, к которому добавляются параметры запроса. Если не указан, используется текущий URL.
Возвращаемое значение
Возвращает новый URL (не экранирован).
1. Добавление параметра к текущему URL
Предположим, что текущий URL — http://example.com/product/?filter=all:
echo esc_url( add_query_arg( 'sort', 'asc' ) );
// Вернет: http://example.com/product/?filter=all&sort=asc
Используя массив, можно добавить сразу несколько параметров:
$params = array( 'page' => 2, 'view' => 'grid' );
echo esc_url( add_query_arg( $params ) );
// Вернет: http://example.com/product/?filter=all&page=2&view=grid
2. Добавление параметров к указанному URL
Если необходимо модифицировать определенный URL, его можно передать в функции:
echo add_query_arg( 'color', 'blue', 'http://shop.com/products' );
// Вернет: http://shop.com/products?color=blue
// Или с использованием массива
echo add_query_arg( array( 'sort' => 'price', 'dir' => 'desc' ), 'http://shop.com/products' );
// Вернет: http://shop.com/products?sort=price&dir=desc
3. Использование с URL поста
Для добавления параметров к URL поста можно использовать get_permalink():
echo esc_url( add_query_arg( 'ref', 'affiliate', get_permalink(15) ) );
// Вернет: http://example.com/post-name?ref=affiliate
4. Удаление параметра из URL
Если передать параметру false, он будет удален из URL:
$url = 'http://example.com/catalog?category=shoes&sort=popularity';
echo esc_url( add_query_arg( array( 'sort' => false ), $url ) );
// Вернет: http://example.com/catalog?category=shoes
5. Примеры с разными способами добавления параметров
Функция add_query_arg() позволяет добавлять параметры несколькими способами:
// Добавить параметр без указания значения
$url = add_query_arg( 'filter' );
// Добавить параметр со значением
$url = add_query_arg( 'filter', 'new' );
// Добавить параметр к конкретному URL
$url = add_query_arg( 'filter', 'new', 'http://example.com/items' );
// Добавить несколько параметров
$url = add_query_arg( array( 'sort' => 'date', 'limit' => '10' ), 'http://example.com/items' );
Важные замечания
- Экранирование URL: Перед выводом URL на экран важно использовать
esc_url(), так как функция не экранирует результат автоматически. - Особенности имен переменных: Параметры, содержащие пробелы или точки, будут заменены символом подчеркивания
_, так как PHP не поддерживает такие символы в именах переменных.
Заключение
Функция add_query_arg() может быть полезной для построения динамических URL и фильтрации контента, а также в плагинах и виджетах для улучшения навигации и взаимодействия с пользователем.