Funzione PHP add_rewrite_var(): tutto quello che devi sapere

add_rewrite_var() è una funzione dell'API WordPress (non fa parte della libreria standard di PHP) che registra una variabile query personalizzata affinché WordPress la riconosca durante il parsing dell'URL. Per impostazione predefinita, WordPress accetta solo un elenco fisso di variabili query "pubbliche" (come p, page_id, cat, s). Qualsiasi variabile non presente in tale elenco viene ignorata silenziosamente, anche se appare nell'URL. add_rewrite_var() aggiunge la tua variabile a questa whitelist, così potrai leggerla in seguito con get_query_var().

Questa pagina descrive cosa fa la funzione, quando effettivamente ne hai bisogno, la sua sintassi, un esempio funzionante completo e le insidie comuni che fanno sembrare "vuote" le variabili query personalizzate.

Cosa fa la funzione add_rewrite_var()

Quando arriva una richiesta, WordPress analizza l'URL attraverso le sue regole di riscrittura e produce un insieme di variabili query. Per motivi di sicurezza, conserva solo le variabili che conosce. add_rewrite_var() estende questo insieme consentito con un nome di variabile aggiuntivo; dopodiché:

• La variabile può essere abbinata alle regole di riscrittura personalizzate create con add_rewrite_rule().
• Il suo valore diventa leggibile tramite get_query_var( 'name' ) all'interno della query principale.

Senza registrare la variabile, get_query_var() restituisce una stringa vuota indipendentemente da ciò che contiene l'URL.

Sintassi

add_rewrite_var( string $name ): void

La funzione non restituisce nulla (void); il suo unico effetto è registrare il nome.

Quando usarla

Utilizza add_rewrite_var() quando crei URL gradevoli/SEO-friendly i cui segmenti devono essere letti come valori nominati — ad esempio un filtro per le liste (/shop/?filter=red) o un endpoint personalizzato (/profile/123/). Se leggi le variabili solo attraverso il superglobale $_GET direttamente, non hai bisogno di questa funzione; esiste specificamente perché i valori sopravvivano al filtraggio delle variabili query e al sistema di riscrittura di WordPress.

Un esempio completo

WordPress costruisce la sua query all'inizio della richiesta, quindi la variabile deve essere registrata prima che ciò accada. Il posto standard è una callback agganciata all'azione 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' );

Qui add_rewrite_var( 'filter' ) registra il nome e get_query_var( 'filter' ) legge qualsiasi valore che WordPress ha associato ad esso per la richiesta corrente. Il controllo ! empty() evita di stampare qualcosa quando la variabile è assente o vuota.

Insidie comuni

• Registra in anticipo. Chiamala su init (o prima). Registrarla dopo che la query principale è già stata costruita non ha effetto per la richiesta corrente.
• Svuota le regole di riscrittura. Se aggiungi anche regole di riscrittura che usano la variabile, svuota le regole una volta — visita Impostazioni → Permalink oppure chiama flush_rewrite_rules() durante l'attivazione del plugin. Non chiamare flush_rewrite_rules() a ogni richiesta; è costoso.
• Valore vuoto? Un get_query_var() vuoto quasi sempre significa che la variabile non è mai stata aggiunta alla whitelist, oppure è stata registrata troppo tardi.

Funzioni correlate

• reset_rewrite_vars() — azzera l'array globale delle variabili di riscrittura, annullando quanto registrato da add_rewrite_var(). È utile quando hai bisogno che WordPress ricalcoli le variabili query per la richiesta corrente.

Conclusione

add_rewrite_var() aggiunge un singolo nome all'elenco di variabili query riconosciute da WordPress, affinché sopravviva alla fase di riscrittura/parsing e possa essere letta con get_query_var(). Registrala sull'hook init, svuota i permalink se la abbini a regole di riscrittura personalizzate e potrai estendere in modo pulito la gestione degli URL di WordPress.

Pratica