Função PHP add_rewrite_var(): Tudo o Que Você Precisa Saber

add_rewrite_var() é uma função da API do WordPress (não faz parte da biblioteca padrão do PHP) que registra uma variável de consulta personalizada para que o WordPress a reconheça ao analisar a URL. Por padrão, o WordPress só aceita uma lista fixa de variáveis de consulta "públicas" (como p, page_id, cat, s). Qualquer variável que não esteja nessa lista é silenciosamente ignorada, mesmo que apareça na URL. add_rewrite_var() adiciona sua variável a essa lista de permissões para que você possa lê-la posteriormente com get_query_var().

Esta página aborda o que a função faz, quando você realmente precisa dela, sua sintaxe, um exemplo completo e funcional, e as armadilhas comuns que fazem variáveis de consulta personalizadas parecerem "vazias".

O que a função add_rewrite_var() faz

Quando uma requisição chega, o WordPress passa a URL pelas suas regras de reescrita e produz um conjunto de variáveis de consulta. Por razões de segurança, ele mantém apenas as variáveis que conhece. add_rewrite_var() estende esse conjunto permitido com um nome de variável extra; após isso:

• A variável pode ser correspondida em regras de reescrita personalizadas criadas com add_rewrite_rule().
• Seu valor torna-se legível via get_query_var( 'name' ) dentro da consulta principal.

Sem registrar a variável, get_query_var() retorna uma string vazia independentemente do que a URL contenha.

Sintaxe

add_rewrite_var( string $name ): void

A função não retorna nada (void); seu único efeito é registrar o nome.

Quando usar

Use add_rewrite_var() quando você criar URLs amigáveis/SEO-friendly cujos segmentos precisam ser lidos como valores nomeados — por exemplo, um filtro de listagem (/shop/?filter=red) ou um endpoint personalizado (/profile/123/). Se você só lê variáveis diretamente pelo superglobal $_GET, não precisa desta função; ela existe especificamente para que os valores sobrevivam à filtragem de variáveis de consulta e ao sistema de reescrita do WordPress.

Um exemplo completo

O WordPress constrói sua consulta cedo no ciclo da requisição, portanto a variável deve ser registrada antes que isso aconteça. O lugar padrão é um callback conectado à ação 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' );

Aqui add_rewrite_var( 'filter' ) registra o nome, e get_query_var( 'filter' ) lê qualquer valor que o WordPress associou a ele para a requisição atual. A verificação ! empty() protege contra a impressão de qualquer coisa quando a variável está ausente ou em branco.

Armadilhas comuns

• Registre cedo. Chame no init (ou antes). Registrar após a construção da consulta principal não tem efeito para a requisição atual.
• Limpe as regras de reescrita. Se você também adicionar regras de reescrita que usam a variável, limpe as regras uma vez — visite Configurações → Links Permanentes ou chame flush_rewrite_rules() durante a ativação do plugin. Não chame flush_rewrite_rules() em toda requisição; é custoso.
• Valor vazio? Um get_query_var() vazio quase sempre significa que a variável nunca foi adicionada à lista de permissões, ou foi registrada tarde demais.

Funções relacionadas

• reset_rewrite_vars() — limpa o array global de variáveis de reescrita, desfazendo o que add_rewrite_var() registrou. Útil quando você precisa que o WordPress recalcule as variáveis de consulta para a requisição atual.

Conclusão

add_rewrite_var() adiciona um único nome à lista de variáveis de consulta reconhecidas pelo WordPress para que ele sobreviva ao estágio de reescrita/análise de consulta e possa ser lido com get_query_var(). Registre-o no hook init, limpe os links permanentes se você combiná-lo com regras de reescrita personalizadas, e você poderá estender o tratamento de URLs do WordPress de forma limpa.

Prática