PHP add_rewrite_var()-Funktion: Alles, was Sie wissen müssen

add_rewrite_var() ist eine Funktion aus der WordPress-API (kein Bestandteil der PHP-Standardbibliothek), die eine benutzerdefinierte Query-Variable registriert, damit WordPress sie beim Parsen der URL erkennt. Standardmäßig berücksichtigt WordPress nur eine feste Liste „öffentlicher" Query-Variablen (wie p, page_id, cat, s). Jede Variable, die nicht auf dieser Liste steht, wird stillschweigend ignoriert, selbst wenn sie in der URL vorkommt. add_rewrite_var() fügt Ihre Variable zu dieser Whitelist hinzu, sodass Sie sie später mit get_query_var() auslesen können.

Diese Seite erklärt, was die Funktion tut, wann Sie sie tatsächlich benötigen, ihre Syntax, ein vollständiges Beispiel sowie häufige Fallstricke, durch die benutzerdefinierte Query-Variablen „leer" erscheinen.

Was die Funktion add_rewrite_var() macht

Wenn eine Anfrage eingeht, leitet WordPress die URL durch seine Rewrite-Regeln und erzeugt eine Menge von Query-Variablen. Aus Sicherheitsgründen behält es nur Variablen, die es kennt. add_rewrite_var() erweitert diesen erlaubten Satz um einen zusätzlichen Variablennamen, danach gilt:

• Die Variable kann in benutzerdefinierten Rewrite-Regeln, die mit add_rewrite_rule() erstellt wurden, abgeglichen werden.
• Ihr Wert ist über get_query_var( 'name' ) innerhalb der Hauptabfrage lesbar.

Ohne Registrierung der Variable gibt get_query_var() immer einen leeren String zurück, unabhängig vom Inhalt der URL.

Syntax

add_rewrite_var( string $name ): void

Die Funktion gibt nichts zurück (void); ihr einziger Effekt ist das Registrieren des Namens.

Wann man sie verwendet

Greifen Sie auf add_rewrite_var() zurück, wenn Sie benutzerfreundliche/SEO-freundliche URLs erstellen, deren Segmente als benannte Werte ausgelesen werden sollen – zum Beispiel ein Listing-Filter (/shop/?filter=red) oder ein benutzerdefinierter Endpunkt (/profile/123/). Wenn Sie Variablen ausschließlich über das $_GET-Superglobal direkt lesen, benötigen Sie diese Funktion nicht; sie existiert speziell dafür, dass Werte das Query-Variable-Filtering und das Rewrite-System von WordPress überstehen.

Ein vollständiges Beispiel

WordPress baut seine Abfrage früh im Request auf, daher muss die Variable davor registriert werden. Der standardmäßige Ort ist ein Callback, der an die init-Action gehängt wird:

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' );

Hier registriert add_rewrite_var( 'filter' ) den Namen, und get_query_var( 'filter' ) liest den Wert, den WordPress für die aktuelle Anfrage damit verknüpft hat. Die ! empty()-Prüfung schützt davor, dass etwas ausgegeben wird, wenn die Variable fehlt oder leer ist.

Häufige Fallstricke

• Früh registrieren. Rufen Sie die Funktion bei init (oder früher) auf. Eine Registrierung nach dem Aufbau der Hauptabfrage hat für die aktuelle Anfrage keine Wirkung.
• Rewrite-Regeln leeren. Wenn Sie zusätzlich Rewrite-Regeln hinzufügen, die die Variable verwenden, leeren Sie die Regeln einmalig – besuchen Sie Einstellungen → Permalinks oder rufen Sie flush_rewrite_rules() beim Aktivieren des Plugins auf. Rufen Sie flush_rewrite_rules() nicht bei jeder Anfrage auf; das ist aufwendig.
• Leerer Wert? Ein leerer Rückgabewert von get_query_var() bedeutet fast immer, dass die Variable nie in die Whitelist aufgenommen wurde oder zu spät registriert wurde.

Verwandte Funktionen

• reset_rewrite_vars() — löscht das globale Rewrite-Variablen-Array und macht damit rückgängig, was add_rewrite_var() registriert hat. Nützlich, wenn WordPress die Query-Variablen für die aktuelle Anfrage neu berechnen soll.

Fazit

add_rewrite_var() fügt einen einzelnen Namen zur Liste der von WordPress erkannten Query-Variablen hinzu, sodass er die Rewrite-/Query-Parse-Phase übersteht und mit get_query_var() ausgelesen werden kann. Registrieren Sie ihn beim init-Hook, leeren Sie die Permalinks, wenn Sie ihn mit benutzerdefinierten Rewrite-Regeln kombinieren, und Sie können die URL-Verarbeitung von WordPress sauber erweitern.

Übungen