Функция ADD_QUERY_ARG() │ WP 1.5.0

Функция add_query_arg() позволяет изменить строку запроса URL, добавляя к ней параметры.

Как использовать функцию

Существует два способа использования этой функции: передача единственного ключа и значения, либо массив ассоциативных данных (ключ-значение).

Использование единственного ключа и значения:

add_query_arg( 'key', 'value', 'http://example.com' );

Использование ассоциативного массива:

add_query_arg( array(
    'key1' => 'value1',
    'key2' => 'value2',
), 'http://example.com' );

Если не указать URL, функция использует текущий URL на странице (значение $_SERVER['REQUEST_URI']).

Кодирование значений

Значения параметров должны быть корректно закодированы с помощью функций urlencode() или rawurlencode().

Важно: Если значение какого-либо параметра равно false, этот параметр будет удалён. Для этого используйте функцию remove_query_arg().

Важные замечания

Результат работы add_query_arg() не экранирован по умолчанию. Чтобы избежать уязвимостей, связанных с атаками на сайты (XSS), вывод должен быть безопасно экранирован с помощью esc_url() или аналогичных функций.

Использование функции

add_query_arg( ...$args );

• ...$args (обязательный параметр) — вы можете передать как массив, так и парные значения.

Примеры использования

Пример 1: Перенаправление пользователя на страницу плагина

// Перенаправление на страницу приветствия.
$redirect_url = add_query_arg( array( 'page' => 'your_plugin_page' ), admin_url( 'plugins.php' ) );
wp_safe_redirect( $redirect_url );
exit;

Пример 2: Добавление параметров к указанному URL

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

Пример 3: Добавление параметров к текущему URL

// Предположим, что мы находимся на 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

Примечание: Если не указан конкретный URL для добавления параметров, обязательно используйте esc_url() перед выводом на экран. Это необходимо, так как параметры запроса могут добавляться пользователем произвольным образом.

Пример 4: Добавление параметра к URL поста

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

// Получаем: http://example.com/post-name?hello=there

Пример 5: Удаление параметра запроса из URL

$url = 'http://example.com/asd?key=val&key1=val1';
echo esc_url( add_query_arg( [ 'key'=>null ], $url ) );
// Вернет: http://example.com/asd?key1=val1

Пример 6: Разные способы задания параметров

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

// Или установить его значение:
$url = add_query_arg( 'foo', 'bar' );

// Или так:
$url = add_query_arg( array('foo'=>'bar') );

// Указываем, для какого URL это делается:
$url = add_query_arg( 'foo', 'bar', $URL );

// Или так:
$url = add_query_arg( array('foo'=>'bar'), $URL );

Изменения

• С версии 1.5.0 функция была введена.
• С версии 5.3.0 формализованы уже существующие и задокументированные параметры с добавлением ...$args в сигнатуру функции.

Код функции ADD_QUERY_ARG()

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 ); // Пере-кодирует данные, которые уже есть в строке запроса.
    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;
}

Теперь вы знаете, как использовать функцию add_query_arg() и как управлять параметрами URL на вашем сайте WordPress!