Master the Rewrite API Recap

Last night, the Developer Meetup welcomed Daniel Bachhuber (@danielbachhuber), code wranger for WordPress.com VIP, to talk the group through WordPress’ Rewrite API.

Daniel started out asking the room how many thought the rewrite API was a deep, dark, mysterious thing. Many agreed with that, no one thought it was easy. One of the first tools mentioned was the Rewrite Rule Inspector plugin. Daniel wrote this to lessen the pain of adding rewrite rules to WordPress.com VIP sites. He spent about a month and a half diving in to how the API works and out of that came this awesome plugin. The point of the plugin is to show you how WordPress interprets different URI patterns.

In general terms the rewrite API allows you to programmatically specify new, custom rewrite rules. There are some core rules that exist on all new WordPress installs and the API allows you to extend this. It takes human readable URIs and turns them in to query strings that WordPress can understand.

The first step in this is your .htaccess file if running Apache. If you’re on Nginx you’re on your own to configure that. The Codex lists the default .htaccess rules. From there Daniel talked about parse_request. This is the handler that translates the request URI in to query variables that WordPress can understand. It uses regex to match the URIs so it may look messy. 🙂

Daniel also covered some lovely API functions. He covered register_taxonomy, add_rewrite_rule, add_rewrite_endpoint, and add_feed. All of those are detailed in the Codex.

Another tool mentioned to help with all of this was the Debug Bar plugin. With this plugin you can see how many queries were made, how WP interpreted the URI, the SQL WP ran to generate the query object, and the query object. Neat stuff.

The key takeaways Daniel outlined were:

  1. Pay attention to priorities: More often than not your problem is that one rewrite rule is conflicting with another and getting matched before you want it to.
  2. When in doubt, step through the code: Trace the execution path and see how WordPress is interpreting that at different stages.
  3. Canonical redirect is the cause and solution to all of your problems: What can happen is a new rewrite rule you create still redirects you to another page. The canonical redirect takes the data it can see and falls back to the “proper” post.
  4. Flushing rewrites on the plugin activation hook happens way too late: Best pattern is to a) show an interface, admin nag that says “Visit Settings > Permalink” or b) instead of flushing on plugin activation flush on the next admin page load.

Author: Andrew Spittle

Andrew is a Happiness Engineer at Automattic. Previously he was CoPress' Hosting Director. You should follow him on Twitter.