Custom URL rewrites in WordPress — A Getting Started Guide

Hey every­one.
I’ve been tweet­ing quite a bit recently about cus­tom URL rewrites in WordPress. After a few hours of trial and error, I’ve man­aged to get my spe­cific cus­tom URL rewrites work­ing. After read­ing through sev­eral tutori­als online (the major­ity of which used the same examples to explain only a por­tion the inform­a­tion I was look­ing for), here’s my tutorial– a get­ting star­ted guide to Custom URL rewrites in WordPress.

The pro­cess

So, what exactly are we doing here? To put things in point form, this is the process:

1. Create cus­tom rewrite rules
2. Add our new vari­ables to the public_​query_​vars array
3. Flush (and thus, regen­er­ate) all WordPress rewrite rules
4. Add our func­tions from steps 1, 2 and 3 into WordPress via actions and filters

Right, so lets get down to it then.

Create cus­tom rewrite rules

Rewrite rules use a  token which is replaced by the neces­sary query vari­able. For example, we cre­ate a token called %token% which, using a reg­u­lar expres­sion, gets replaced by “id=”. This will be shown fur­ther below.

Add our new vari­ables to the public_​query_​vars array

By default, WordPress has an array of pub­lic query vari­ables which can be used within tem­plates and plu­gins. In order to access our query vari­ables (ie: the “id=” in the above example), the vari­able needs to be added to the pub­lic query vars array.

/**
* add_custom_page_variables()
* Add the custom token as an allowed query variable.
* return array $public_query_vars.
**/

function add_custom_page_variables( $public_query_vars ) {
$public_query_vars[] = 'car';

return $public_query_vars;

} // End add_custom_page_variables()


Flush all WordPress rewrite rules

By flush­ing the rules, we are for­cing WordPress to regen­er­ate it’s rules list, includ­ing our new rules in the rules set.

/**
* flush_rewrite_rules()
* Flush the rewrite rules, which forces the regeneration with new rules.
* return void.
**/

function flush_rewrite_rules() {

global $wp_rewrite;

$wp_rewrite->flush_rules();

} // End flush_rewrite_rules()


Add our func­tions from steps 1, 2 and 3 into WordPress via actions and filters

Now that our func­tions have been cre­ated, we need to hook them into the vari­ous neces­sary pro­cesses within WordPress. We do this using a com­bin­a­tion of actions and filters.

Our first action runs on ini­tial­iz­a­tion. This is where we flush the rewrite rules in WordPress, caus­ing them to be regenerated.

The regen­er­a­tion brings us to action num­ber 2. This is where we cre­ate our cus­tom rewrite rule, hook it on to the global rewrites array and gen­er­ate the rules.

Our final line is our fil­ter where we add the new pub­lic query vari­able into the global public_​query_​vars array. We then later use this array to access the vari­able in our theme.

add_action( 'init', 'flush_rewrite_rules' );
add_action( 'generate_rewrite_rules', 'create_custom_rewrite_rules' );
add_filter( 'query_vars', 'add_custom_page_variables' );


The scope of rewrite rules

By default, WordPress rules are applied across all pages. Thus, the tag “%page­name%” is used in place of a spe­cific page slug. To use your rules on only a single page, replace “%page­name%” with a spe­cific page slug. You can either gen­er­ate this slug dynam­ic­ally or staticly.

That’s all, folks

And there you have it. A cus­tom rewrite rule in WordPress. This post is inten­ded as a start­ing point for using cus­tom rewrite rules in WordPress. There are vir­tu­ally infin­ite pos­sib­il­it­ies cre­ated when using rewrite rules (either one or many) and some really inter­est­ing plu­gins and func­tion­al­it­ies can come out of using rewrite rules.

Thanks must also go to Joe Hoyle who’s use of rewrite rules provided the inspir­a­tion for this tutorial.

If there’s any­thing that isn’t clear, please com­ment below and I’ll do my best to cla­rify and help.

Before I go… wouldn’t you like the files?

I thought you might. Click below to down­load the code writ­ten above (it’s been writ­ten into a class for easy imple­ment­a­tion in your projects).

Download the  “Custom URL rewrites in WordPress — A Getting Started Guide” code example.

Related Posts

• My (updated) WordPress Plugins Toolbox
• Javascript and WordPress – The Definitive Guide
• Child plu­gins in WordPress. An idea?
• WordPress theme fea­tures: What would you like to see?
• A few guidelines for WordPress plu­gin development