PHP add_rewrite_var() Function: Everything You Need to Know

add_rewrite_var() is a function from the WordPress API (not part of PHP's standard library) that registers a custom query variable so WordPress recognizes it when parsing the URL. By default, WordPress only honors a fixed list of "public" query variables (such as p, page_id, cat, s). Any variable not on that list is silently ignored, even if it appears in the URL. add_rewrite_var() adds your variable to that whitelist so you can read it later with get_query_var().

This page covers what the function does, when you actually need it, its syntax, a complete working example, and the common pitfalls that make custom query variables appear "empty."

What the add_rewrite_var() function does

When a request comes in, WordPress runs the URL through its rewrite rules and produces a set of query variables. For security reasons it only keeps variables it knows about. add_rewrite_var() extends that allowed set with one extra variable name, after which:

• The variable can be matched in custom rewrite rules created with add_rewrite_rule().
• Its value becomes readable via get_query_var( 'name' ) inside the main query.

Without registering the variable, get_query_var() returns an empty string no matter what the URL contains.

Syntax

add_rewrite_var( string $name ): void

The function returns nothing (void); its only effect is to register the name.

When to use it

Reach for add_rewrite_var() when you build pretty/SEO-friendly URLs whose segments need to be read as named values — for example a listing filter (/shop/?filter=red) or a custom endpoint (/profile/123/). If you only ever read variables through the $_GET superglobal directly, you do not need this function; it exists specifically so values survive WordPress's query-variable filtering and rewrite system.

A complete example

WordPress builds its query early in the request, so the variable must be registered before that happens. The standard place is a callback hooked to the init action:

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

Here add_rewrite_var( 'filter' ) registers the name, and get_query_var( 'filter' ) reads whatever value WordPress associated with it for the current request. The ! empty() check guards against printing anything when the variable is missing or blank.

Common gotchas

• Register early. Call it on init (or earlier). Registering it after the main query is built has no effect for the current request.
• Flush rewrite rules. If you also add rewrite rules that use the variable, flush the rules once — visit Settings → Permalinks or call flush_rewrite_rules() during plugin activation. Do not call flush_rewrite_rules() on every request; it is expensive.
• Empty value? An empty get_query_var() almost always means the variable was never whitelisted, or it was registered too late.

Related functions

• reset_rewrite_vars() — clears the global rewrite-variable array, undoing what add_rewrite_var() registered. Useful when you need WordPress to recalculate query variables for the current request.

Conclusion

add_rewrite_var() adds a single name to WordPress's list of recognized query variables so it survives the rewrite/query-parsing stage and can be read with get_query_var(). Register it on the init hook, flush permalinks if you pair it with custom rewrite rules, and you can cleanly extend WordPress URL handling.

Practice