The WordPress API known as “the rewrite API” is a useful tool that makes URLs more readable. This process is commonly referred to as “url rewriting”. For instance, a URL such as http://mysite.com/?page=12&category=12&author=47 is not user-friendly and search engines do not favor it. Therefore, most content management systems (CMS) have built-in functions that rewrite URLs to make them look like this: http://mysite.com/category/business/finance. The rewrite API is also known as the permalinks structure within WordPress. When you switch from the default permalink structure to a custom structure, you automatically activate the rewrite API. However, sometimes you may need to create your own custom rewrite rules.
In this article, we will create simple functions to create a custom rewrite rule. Suppose we want to get a referrer value, which is equivalent to a $_GET[‘referrer’]. If we look at the Codex, we can see that the rewrite API has six built-in functions. The most common use of the rewrite is to use these functions. There are plenty of tutorials about that, which is why we will use filters instead of functions. The 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 will add a new variable to the query_vars filter, and the second one will 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, go to settings > Permalinks, and save the permalinks structure. This action is needed. You should now be able to access your site with this kind of URL: http://mysite.com/referrer/your-name. If you want to be redirected to 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 you would have done with a normal GET variable.
You can, of course, modify and 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 enabled to use URL rewriting.
