Función PHP add_rewrite_var(): Todo lo que Necesitas Saber

add_rewrite_var() es una función de la API de WordPress (no forma parte de la biblioteca estándar de PHP) que registra una variable de consulta personalizada para que WordPress la reconozca al analizar la URL. Por defecto, WordPress solo acepta una lista fija de variables de consulta "públicas" (como p, page_id, cat, s). Cualquier variable que no esté en esa lista es ignorada silenciosamente, aunque aparezca en la URL. add_rewrite_var() añade tu variable a esa lista blanca para que puedas leerla más tarde con get_query_var().

Esta página explica qué hace la función, cuándo la necesitas realmente, su sintaxis, un ejemplo completo y funcional, y los errores comunes que hacen que las variables de consulta personalizadas aparezcan "vacías".

Qué hace la función add_rewrite_var()

Cuando llega una solicitud, WordPress procesa la URL a través de sus reglas de reescritura y produce un conjunto de variables de consulta. Por razones de seguridad, solo conserva las variables que conoce. add_rewrite_var() amplía ese conjunto permitido con un nombre de variable adicional, tras lo cual:

• La variable puede ser utilizada en reglas de reescritura personalizadas creadas con add_rewrite_rule().
• Su valor se puede leer mediante get_query_var( 'name' ) dentro de la consulta principal.

Sin registrar la variable, get_query_var() devuelve una cadena vacía sin importar lo que contenga la URL.

Sintaxis

add_rewrite_var( string $name ): void

La función no devuelve nada (void); su único efecto es registrar el nombre.

Cuándo usarla

Utiliza add_rewrite_var() cuando construyas URLs amigables/SEO cuyos segmentos necesiten leerse como valores con nombre — por ejemplo, un filtro de listado (/shop/?filter=red) o un endpoint personalizado (/profile/123/). Si solo lees variables a través de la superglobal $_GET directamente, no necesitas esta función; existe específicamente para que los valores sobrevivan al filtrado de variables de consulta y al sistema de reescritura de WordPress.

Un ejemplo completo

WordPress construye su consulta al inicio de la solicitud, por lo que la variable debe registrarse antes de que eso ocurra. El lugar estándar es un callback enganchado a la acción 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' );

Aquí add_rewrite_var( 'filter' ) registra el nombre, y get_query_var( 'filter' ) lee el valor que WordPress asoció con él para la solicitud actual. La verificación ! empty() evita imprimir algo cuando la variable está ausente o en blanco.

Errores comunes

• Registra pronto. Llámala en init (o antes). Registrarla después de que se haya construido la consulta principal no tiene efecto para la solicitud actual.
• Vacía las reglas de reescritura. Si también añades reglas de reescritura que usen la variable, vacía las reglas una vez — visita Ajustes → Enlaces permanentes o llama a flush_rewrite_rules() durante la activación del plugin. No llames a flush_rewrite_rules() en cada solicitud; es una operación costosa.
• ¿Valor vacío? Un get_query_var() vacío casi siempre significa que la variable nunca fue incluida en la lista blanca, o que se registró demasiado tarde.

Funciones relacionadas

• reset_rewrite_vars() — vacía el array global de variables de reescritura, deshaciendo lo que registró add_rewrite_var(). Útil cuando necesitas que WordPress recalcule las variables de consulta para la solicitud actual.

Conclusión

add_rewrite_var() añade un nombre a la lista de variables de consulta reconocidas por WordPress para que sobreviva la etapa de reescritura/análisis de consultas y pueda leerse con get_query_var(). Regístrala en el hook init, vacía los enlaces permanentes si la combinas con reglas de reescritura personalizadas, y podrás ampliar el manejo de URL de WordPress de forma limpia.

Práctica