Функция PHP add_rewrite_var(): всё, что нужно знать

add_rewrite_var() — это функция из WordPress API (не входит в стандартную библиотеку PHP), которая регистрирует пользовательскую переменную запроса, чтобы WordPress распознавал её при разборе URL. По умолчанию WordPress обрабатывает только фиксированный список «публичных» переменных запроса (например, p, page_id, cat, s). Любая переменная, не включённая в этот список, молча игнорируется, даже если присутствует в URL. add_rewrite_var() добавляет вашу переменную в этот белый список, после чего её можно считывать с помощью get_query_var().

На этой странице рассматривается, что делает функция, когда она действительно нужна, её синтаксис, полный рабочий пример и типичные подводные камни, из-за которых пользовательские переменные запроса оказываются «пустыми».

Что делает функция add_rewrite_var()

Когда поступает запрос, WordPress пропускает URL через свои правила перезаписи и формирует набор переменных запроса. В целях безопасности сохраняются только известные переменные. add_rewrite_var() расширяет этот допустимый набор одним дополнительным именем переменной, после чего:

• Переменная может сопоставляться в пользовательских правилах перезаписи, созданных с помощью add_rewrite_rule().
• Её значение становится доступным через get_query_var( 'name' ) внутри основного запроса.

Без регистрации переменной get_query_var() будет возвращать пустую строку независимо от того, что содержится в URL.

Синтаксис

add_rewrite_var( string $name ): void

Функция ничего не возвращает (void); её единственный эффект — регистрация имени.

Когда использовать

add_rewrite_var() нужна при создании красивых/SEO-дружественных URL, сегменты которых необходимо считывать как именованные значения — например, фильтр листинга (/shop/?filter=red) или пользовательский эндпоинт (/profile/123/). Если вы всегда читаете переменные напрямую через суперглобальный массив $_GET, эта функция вам не нужна; она существует специально для того, чтобы значения сохранялись после фильтрации переменных запроса и системы перезаписи WordPress.

Полный пример

WordPress собирает запрос в начале обработки, поэтому переменная должна быть зарегистрирована до этого момента. Стандартное место — коллбэк, подключённый к хуку init:

function my_register_query_var() {
    // Whitelist a custom query variable named "filter".
    add_rewrite_var( 'filter' );
}
add_action( 'init', 'my_register_query_var' );

function my_read_query_var() {
    // Read the value WordPress parsed from the URL, e.g. /shop/?filter=red
    $filter = get_query_var( 'filter' );

    if ( ! empty( $filter ) ) {
        echo 'Filtering by: ' . esc_html( $filter );
    }
}
add_action( 'template_redirect', 'my_read_query_var' );

Здесь add_rewrite_var( 'filter' ) регистрирует имя, а get_query_var( 'filter' ) считывает значение, которое WordPress связал с ним для текущего запроса. Проверка ! empty() защищает от вывода чего-либо, когда переменная отсутствует или пуста.

Типичные подводные камни

• Регистрируйте как можно раньше. Вызывайте функцию на хуке init (или раньше). Регистрация после построения основного запроса не даст эффекта для текущего запроса.
• Сбрасывайте правила перезаписи. Если вы также добавляете правила перезаписи, использующие эту переменную, сбросьте правила один раз — откройте Настройки → Постоянные ссылки или вызовите flush_rewrite_rules() при активации плагина. Не вызывайте flush_rewrite_rules() при каждом запросе — это затратная операция.
• Пустое значение? Пустой результат get_query_var() почти всегда означает, что переменная никогда не была добавлена в белый список или была зарегистрирована слишком поздно.

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

• reset_rewrite_vars() — очищает глобальный массив переменных перезаписи, отменяя то, что было зарегистрировано с помощью add_rewrite_var(). Полезно, когда нужно, чтобы WordPress пересчитал переменные запроса для текущего запроса.

Заключение

add_rewrite_var() добавляет одно имя в список распознаваемых WordPress переменных запроса, чтобы оно сохранялось после этапа перезаписи/разбора запроса и могло быть прочитано с помощью get_query_var(). Регистрируйте переменную на хуке init, сбрасывайте постоянные ссылки, если используете её совместно с пользовательскими правилами перезаписи, — и вы сможете чисто расширить обработку URL в WordPress.

Практика