TUTORIAL: Building Custom Rewrite Endpoints in WordPress

Recently I concluded a sizable project that involved deep integration with an external API. I was responsible for creating content pages based outside of WordPress. To be clear, the pages would use an internal WP template, but all the content was generated using this external API.

In order to make this work within the WordPress Rewrite system and serve pages that WordPress knew how to handle in a non-traditional way, I had to tackle this in a multi-prong way: using the template_redirect as well as the built in Rewrite API.

Note: I’m not giving away the full sauce here as the project is non-open source. As well, I’ll be abstracting some stuff a bit. If you’re smart, you can fill in all the blanks regarding how to fully implement this.

First we need a base class:

1
2
3
4
5
6
7
8
9
10
11
12
13

<?php

class Base_Class {

public function __construct() {
$this->hooks();
}

public function hooks() {
}
}

new Base_Class;

This is the base of pretty much every class I write as part of a plugin in WordPress. If you don’t follow Object Oriented coding practices, start now.

The next step is to register some variables with WordPress. Because WordPress is using the template_redirect hook to get the proper template files, you will often lose necessary query string variables, and you definitely can’t use them in an endpoint (i.e. /foo/bar) without WordPress knowing about them.

So let’s register them using the query_vars filter.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

<?php
class Base_Class {

public function __construct() {
$this->hooks();
}

public function hooks() {
add_filter( ‘query_vars’, array( $this, ‘query_vars’ ) );
}

public function query_vars( $qv )
{
$qv[] = ‘foo’;
$qv[] = ‘bar’;
return $qv;
}
}

new Base_Class;

After this, we want to actually create some rewrite endpoints. In this example, I want to allow permalinks like /foo/content-slug/ and /bar/content-slug. With the following code that adds a rewrites() method to the class, and hooks on the generate_rewrite_rules filter, we can create these two endpoints. In our imaginary template, we would use get_query_var() function to handle logic for display purposes, but that’s outside of this article scope.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

<?php
class Base_Class {

public function __construct() {
$this->hooks();
}

public function hooks() {
add_filter( ‘query_vars’, array( $this, ‘query_vars’ ) );
add_filter( ‘generate_rewrite_rules’, array( $this, ‘rewrites’ ) );
}

public function query_vars( $qv )
{
$qv[] = ‘foo’;
$qv[] = ‘bar’;
return $qv;
}

public function rewrites( $rules )
{
global $wp_rewrite;

$new_rules = array(
‘foo/([a-z]+)/?$’ => ‘index.php?pagename=wppage-holder&foo=’ . $wp_rewrite->preg_index(1),
‘bar/([a-z]+)/?$’ => ‘index.php?pagename=wppage-holder&bar=’ . $wp_rewrite->preg_index(1),
);

$wp_rewrite->rules = $new_rules + $wp_rewrite->rules;
return $wp_rewrite->rules;
}
}

new Base_Class;

Specifically, note the new rewrite rules and how they are structured. If those permalink structures identified above match these new rules, then we will pass the request on and use the template file designated for a page (that you do have to create in WordPress, by the way) with the slug ‘wppage-holder’. This can be done by designating a template file on the page edit screen or by naming the template as page-wppage-holder.php in your theme – again, outside the scope of this article.

If the permalink matches foo, we pass the foo variable on. If it matches bar, we pass the bar variable on. Logic on the other end left to you.

This is where I have to stop using this example, for client confidentiality purposes, but imagine what is possible now if you extend this and use the template_redirect hook to handle some custom redirects leveraging wp_redirect()?

Imagine. :)