The WordPress Rewrite API

WordPress has a really useful API called “the rewrite API“. I guess that have already of “url rewriting”, this is the process that makes URLs more readable. For example a url written like this http://mysite.com/?page=12&category=12&author=47 isn’t that good looking. It’s hard to remember it, and search engines don’t like it that much. That’s why nearly every CMS has a builtin function that “rewrites” urls to make them look like this: http://mysite.com/category/business/finance.

The rewrite API and the WP_Rewrite class

Inside WordPress, this process is also known as the permalinks structure. When you switch from the default permalink structure to a custom structure you automatically activate the rewrite API. This is fully automatic. But sometimes you need to create your own custom rewrite rules.

In this post, we are going to create simple functions to create a simple custom rewrite rule. Let’s says we want to get a referrer value, sort of equivalent to a $_GET[‘referrer’].

If we have a look at the Codex, we can see on the rewrite API page that this API has 6 builtin functions. The most common use of the rewrite is to use these functions, there are plenty of tutorials about that, that’s why i’m going to use filters instead of functions. Because yes, the rewrite API can also be used with filters! Those filters are listed on the WP_Rewrite class Codex page.

Adding a new Query Var

To start, we need to create a function that will tell WordPress that a new rewrite rule is set. This is the job of the add_rewrite_rule() and add_rewrite_tag()  functions, but you can also do it using the query_vars and rewrite_rules_array filters. To do so, we need to create two functions and two filters. The first function is going to simply add a new variable to the query_vars filter, and the second one is going to register this new variable into the global rewrite rules:

/*
|--------------------------------------------------------------------------
| Start Rewrite. Sample: http://mysite.com/referrer/remi
|--------------------------------------------------------------------------
*/

// Register a new var
function rc_add_query_vars( $vars) {
	$vars[] = "referrer"; // name of the var as seen in the URL
return $vars;
}

// Hook our function into query_vars
add_filter('query_vars', 'rc_add_query_vars');

// Add the new rewrite rule to existings ones
function rc_add_rewrite_rules($rules) {
	$new_rules = array('referrer/([^/]+)/?$' => 'index.php?referrer=$matches[1]');
	$rules = $new_rules + $rules;
	return $rules;
}

// Hook the function into rewrite_rules_array
add_filter('rewrite_rules_array', 'rc_add_rewrite_rules');

Once you add this code to any of your plugin file or your theme functions.php file, got to settings > Permalinks, and save the permalinks structure. This action is needed. You should now be able to access your site with this kind or url: http://mysite.com/referrer/your-name. If you want to be redirected on a specific page, change index.php?referrer=$matches[1] by index.php?pagename=my-page&referrer=$matches[1] where “my-page” is the page to be redirected to slug.

Retrieving the variable value

Now that your rewrite rule is set, you might want to access the variable value. But if you do a simple $_GET[‘referrer’], you won’t get any value. To retrieve the URL vars values, you need to hook a function to the “template_redirect” filter. Hooking to the “init” filter is too early. Then you can access the needed variables through the $wp_query object. Here is a quick sample of how to do it:

// Retrieve URL var
function rc_get_my_vars() {
	global $wp_query;
	
	if(isset($wp_query->query_vars['referrer'])) {
		$referrer = get_query_var('referrer');
	}
}

// Hook the function into template_redirect
add_action( 'template_redirect', 'rc_get_my_vars');

You can next echo the $referrer value or use it as would have done with a normal GET variable.

You can of course modify  use more than one variable:

// in rc_add_query_vars()
$vars[] = "referrer";
$vars[] = "campaign";

// in rc_add_rewrite_rules()
$new_rules = array('referrer/([^/]+)/([^/]+)/?$' => 'index.php?pagename=my-page&referrer=$matches[1]&campaign=$matches[2]');

Don’t forget that you need PHP mod_rewrite module enable to use url rewriting.