Download the PHP package sformisano/jetrouter without Composer

JetRouter - WordPress Routing, Fast & Easy

This WordPress plugin adds a regular expression based router on top of the WordPress standard routing system. Any route declared through this router will take priority over standard WordPress URLs.

• Installation
• Usage
  • Initialization & Configuration
  • Configuration properties
  • Adding Routes
  • The basics
  • Dynamic routes
  • Parameters regular expressions
  • Optional parameters
  • Reverse Routing
  • Dynamic routes reverse routing
  • Handler's respond_to Feature
• Why I built it
• Credits

Installation

Download zip

Download via WordPress plugin page

You can visit the WordPress plugin page and download the latest plugin version there.

Download via GitHub repo release page

You can also grab the latest release from this repository's releases page.

Composer

If your setup uses Composer for proper dependency management (check out the awesome Bedrock project if you are interested in running WordPress as a 12 factor app) installing the JetRouter is quite easy.

Composer via WordPress Packagist (simpler & better)

WordPress Packagist is a site that scans the WordPress Subversion repository every hour for plugins and themes and then mirrors them as Composer repositories.

Search for "jetrouter" (here's the search results for that ), click on the latest version in the "Versions" column of the record and you will be given the code to paste in your composer.json file in the require property.

It should look something like this:

Please note: I have had no time to verify this, but even without using the Bedrock WordPress boilerplate, wpackagist packages should automatically install in the plugins directory (which is what you would want) rather than the default composer vendor directory. If that is not the case, reference the Composer via GitHub releases section below to learn how to tell composer where to install your WordPress plugins.

Composer via GitHub releases

Add this package to the "repositories" property of your composer json definition (make sure the release version is the one you want to install):

Once that's done, add the JetRouter in the composer require property (the version has to match the package version):

Finally, make sure to specify the correct path for the "wordpress-plugin" type we assigned to the JetRouter package in the definition above (note: if you are using Bedrock this is already taken care of).

Run composer update from your composer directory and you're good to go!

Usage

Initialization & Configuration

In your theme’s functions.php file or somewhere in your plugin:

Available router configuration properties:

• namespace: if defined, the namespace prefixes all routes, e.g. if you set the namespace to “my-api” and then define a route as “comments/published”, the actual endpoint will be “/my-api/comments/published/“.
• outputFormat: determines the routes handlers output format. Available values: auto, json, html.

The router automatically hooks itself to WordPress, so once you’ve created the router instance with the configuration that suits your needs, all that is left to do is adding routes. After that, the router is ready to dispatch requests.

Pro tip on the namespace

If you use the JetRouter to build a json/data api, or if you simply don’t mind having a namespace before your urls, having one will speed up standard WordPress requests, especially if you have many dynamic routes.

This is because, if the router has a namespace, but the http request’s path does not begin with that namespace (like it would be the case with all WordPress urls), the router won’t even try to dispatch the request.

Without a namespace, on the other hand, the router will try to dispatch all requests, building the dynamic routes array every time. (Note: caching the generated dynamic routes is on my todo list.)

Adding Routes

The basics

The basic method to add routes is addMethod. Example:

The addRoute method has aliases for each http method (get, post, put, patch, delete, head, options). Example:

Dynamic routes

Use curly braces to outline parameters, then declare them as arguments of the callback function and the router will take care of everything else. Example:

Parameters regular expressions

By default, all parameters are matched against a very permissive regular expression:

You can use your own regular expressions by adding a colon after the parameter name and the regex right after it. Example:

You can also use one of these regex shortcuts for convenience:

If, for example, we wanted to write the same get_school_students_by_year route by using the :i shortcut, this is how we would do it:

Optional parameters

You can make a parameter optional by adding a question mark after the closing curly brace. Example:

You can make all parameters optionals, even when they are not the last segment in a route. Example:

All the example requests below would match the route defined above:

This is not necessarily the best use of optional parameters. The examples here are just to show that, if you have a valid use case, the JetRouter will allow you to setup your routes this way.

Reverse Routing

Reverse routing is done through the same router object for simplicity’s sake.

Given this simple example route:

To print out the full path you use the thePath method:

You can also get the value returned, rather than printed out, by using the getThePath method (trying to follow some WordPress conventions with this):

Dynamic routes reverse routing

Dynamic routes work in the exact same way, you just pass the values of the parameters after the route name in the same order they are defined in when you created the route.

For example, given this route:

This is how you would print out a full path to this route:

As the last parameter is optional you can simply omit it:

If the optional parameter you need to omit is not the last parameter, you can simply pass null as a value and it will be ignored. Example:

I prefer this approach to the more common associative array for arguments as it makes everything simpler (less typing in the vast majority of scenarios) and more explicit (a missing optional parameter is still defined as null, so there’s a 1:1 match between formal parameters and arguments).

Handler's respond_to Feature

If you ever played around with Ruby on Rails, you're probably familiar with the respond_to and respond_with blocks. This respond_to feature is a basic, simplistic imitation of that clever way to handle different request types with different behaviours.

If you never tried out Rails, let me make this simple with an example:

You created a public signup form that posts to a create_user endpoint created with the JetRouter. You definitely want that form to work with ajax, but you're one of those few developers left who still cares about graceful degradation, so you don't just want to set the outputFormat config parameter to json and do a return $data; of sorts. You need to be able to receive json data with ajax requests, while doing something else (redirects, loading views in error mode etc.) for standard, synchronous requests.

Technically, you could manually check for $_SERVER['HTTP_X_REQUESTED_WITH'] and write some conditional code that works with that, but who wants to do that kind of manual labour for every single endpoint?

JetRouter's respond_to to the rescue! All you have to do is leave the outputFormat config parameter to auto and have your route handler return an array following this format:

Pro tip: appending ?json to a request path will force the json output.

Why I built the JetRouter

• I wanted something fast, easy to setup and with a minimal API. The JetRouter is setup with one line of code ($r = Router::create();) and all functionality is readily available through that object.

• I needed extra features not offered by any other small footprint php router I am familiar with, including the ones I credited below.

• The routers I am aware of, even the ones I credited below, are conceived to be used as the core routing system of a website/webapp. This does not make them the best fit for the use case of a WordPress extra routing layer, e.g. they will throw an exception if a route is not found or if there’s a path match but the http method of the request is different. Because this router is an extra layer on top of WordPress, it needs to fail silently in most of these scenarios and give control back to WordPress. WordPress can then dispatch those requests matching, return a 404 or do whatever else it’s supposed to do.

• Finally, building this looked like a fun way to revisit PCRE, which are something I have not worked with in many years.

Credits

• This router implements Nikita Popov’s group position based, non-chunked approach to regex matching for lightning fast routing. Learn more about it by reading this great post by Nikita himself.

• Joe Green and his phroute project (also loosely based on Nikita’s work) are to be thanked for:
  • the regex used to capture dynamic routes parameters
  • the regex shortcuts (a simple yet very elegant idea)
  • the basics of the optional parameters and reverse routing implementation

Go check both these authors and their projects, they are awesome.