add_rewrite_tag( string $tag, string $regex, string $query = '' )
Adds a new rewrite tag (like %postname%).
Contents
Description
The $query
parameter is optional. If it is omitted you must ensure that you call this on, or before, the ‘init’ hook. This is because $query
defaults to $tag=
, and for this to work a new query var has to be added.
Parameters
-
$tag
string Required -
Name of the new rewrite tag.
-
$regex
string Required -
Regular expression to substitute the tag for in rewrite rules.
-
$query
string Optional -
String to append to the rewritten query. Must end in
'='
.Default:
''
More Information
This function can be used to make WordPress aware of custom querystring variables. Generally, it’s used in combination with add_rewrite_rule() to create rewrite rules for pages with custom templates.
If you use this function to declare a rewrite tag that already exists, the existing tag will be overwritten.
This function must be called on init or earlier.
What it does
- Gets a query var name by stripping the % signs from the name of the tag: trim($tag, ‘%’)
- Calls $wp_rewrite::add_rewrite_tag() with the name, generated QV name and regex.
- Adds the QV as a query var (again, this could be done by filtering query_vars but it might be nicer to add a function to the WP class that stores ‘extra’ QVs like above)
Source
File: wp-includes/rewrite.php
.
View all references
function add_rewrite_tag( $tag, $regex, $query = '' ) {
// Validate the tag's name.
if ( strlen( $tag ) < 3 || '%' !== $tag[0] || '%' !== $tag[ strlen( $tag ) - 1 ] ) {
return;
}
global $wp_rewrite, $wp;
if ( empty( $query ) ) {
$qv = trim( $tag, '%' );
$wp->add_query_var( $qv );
$query = $qv . '=';
}
$wp_rewrite->add_rewrite_tag( $tag, $regex, $query );
}
Changelog
Version | Description |
---|---|
2.1.0 | Introduced. |
User Contributed Notes
You must log in before being able to contribute a note or feedback.
In the following examples, imagine a site has a custom taxonomy ‘location’ and all posts are assigned a location term like “Paris” or “Madrid”. We add a rewrite tag “%location%” to establish the
location
query var. We also add a rewrite rule so that an URL such as example.com/goto/madrid/budget-lodging/ is properly handled.Even though rewrite tags look just like permalink structure tags, if you try to use your rewrite tag in a permalink structure, the URLs generated by WordPress will look something like example.com/goto/%location%/budget-lodging/. The proper term does not replace the rewrite tag as you might expect. To make your tag behave like a structure tag, use the “post_link” filter to replace the tag with the proper term.
Anytime you change something related to the Rewrite API, don’t forget to flush the rewrite rules! This can be done without code by going to Permalink Settings and clicking Save Changes. You don’t actually need to make any changes on the settings screen.
(From Codex)
Example
The following will register a tag called ‘film_title’:
This is particularly important when you are using rewrites with custom page templates.
Retrieving the Value of a Rewritten URL
With a rewrite tag defined, you can now retrieve the value of your rewritten querystring variables using WordPress’s $wp_query variable. To get the value of the above tag out of a rewrite, you could use the following in your page template:
Note that using $_GET on a rewritten URL will not work, even if the rewrite includes the querystring variables. You must use $wp_query.