WordPress Custom Routing: Stop Hacking the Rewrite API

Got a call from a client running a big WooCommerce site with a custom-built event registration plugin from years ago. It worked, but the URLs were a mess—think /?event_action=view_attendees&event_id=123. They wanted to modernize it with clean URLs like /events/123/attendees. Simple, right? But this site was already a tangled web of plugins and custom code. Just throwing more rules at it felt like a disaster waiting to happen. This is a classic problem when a WordPress site starts growing into a full-blown application: you outgrow the basics of the Rewrite API.

My first thought was to just do it the “quick” way. Add a new rule with add_rewrite_rule() to handle the new URL structure, register the new query variables, and then slap a big if/else block in a template_redirect hook to check the vars and load the right template. And yeah, it worked for that one URL. But then they wanted another for editing, and another for exporting a CSV. It was turning into a procedural nightmare. One wrong regex and the whole thing could conflict with another plugin. Total mess.

The Problem with “Just” Using the Rewrite API

Here’s the kicker: the Rewrite API isn’t really a routing system. Not in the way a developer coming from a framework like Laravel or Symfony would think of one. Its main job is to translate a “pretty” URL into a set of WordPress query variables. That’s it. It doesn’t directly map a URL to a specific function or controller. The logic is completely disconnected from the URL definition, and that’s where things get fragile on big projects.

A proper routing system, on the other hand, is about creating explicit relationships: this URL path maps to this specific piece of logic. It’s a much more robust and readable way to build. This is a concept that Carl Alexander detailed in a fantastic, deep-dive post on building a routing system, which really lays out the object-oriented approach. Instead of a mess of functions, you create a simple, declarative map of your application’s endpoints.

// A cleaner, more declarative way to think about routes
$router->add_route('event_attendees', new Route(
    '/events/{id}/attendees',
    'my_display_event_attendees_callback'
));

$router->add_route('event_edit', new Route(
    '/events/{id}/edit',
    'my_edit_event_form_callback'
));

// The logic is neatly separated
function my_display_event_attendees_callback($id) {
    // Go get attendees for event $id and load a template...
}

So, What’s the Point?

Moving from the standard Rewrite API to a more structured, object-oriented routing system for WordPress custom routing isn’t about just making URLs look better. It’s about making your entire application more stable, maintainable, and easier for other developers (or your future self) to understand.

• It’s Declarative: You can see all your custom endpoints in one place.
• It’s Maintainable: No more hunting through hooks and conditionals to debug a URL. The path and the logic are linked.
• It’s Scalable: As the application grows, you just add new routes. The core logic doesn’t become more complex.

Look, this stuff gets complicated fast. If you’re tired of debugging someone else’s mess and just want your site to work, drop my team a line. We’ve probably seen it before.

When you’re building something that feels more like an “app” on top of WordPress, you have to start thinking like an app developer. And that means building a real routing system. Trust me on this, it’ll save you a world of pain down the road.