Download the PHP package aivec/wordpress-router without Composer

WordPress REST Router

This package provides a routing library for WordPress with WordPress specific wrappers such as nonce verification and user role checking. The backbone of this package uses FastRoute, a small and succinct route resolver. FastRoute is also the route resolver used by the popular micro-framework Slim.

The Problem

Routing in WordPress is a pain for plugin authors. It relies solely on $_POST object keys to resolve routes if you go with WordPress' traditional way of registering AJAX handlers via admin-ajax.php. You could use WordPress' REST API, but you don't have control of when routes are resolved. This is important to developers who create extensions for other plugins where the load order is out of their control. This package also differs from WordPress' implementation in that it doesn't provide validate and sanitize callbacks, opting instead for generic middlewares.

Features

This library provides many features to streamline the provisioning of routes, as well as some optional default middlewares. The main features are as follows:

• Role based route registration (editor, administrator, etc.)
• Automatic nonce verification
• URL parameters (NOT REGEX :grin:)
• Passthru routing (non-AJAX routes)
• Helpers for generating HTML forms
• JWT route registration
• JWT settings page for automatic key pair generation

Installation

Install with composer:

If you plan on using this package in a plugin, we highly recommend namespacing it with mozart. If you don't, things may break in an impossible to debug way. You have been warned.

Usage Guide

• Public Route
  • Calling the Public Route
• Private Route
  • Calling the Private Route
• URL Parameters
• Form Data
• Making Everything Easier

Public Route

A public route refers to a route without nonce verification. A public route is accessible by anyone, from anywhere.

Calling the Public Route

You can test the route from the command line, like so:

Or, you can use jQuery's ajax function to send a request from a script loaded into a WordPress page:

Private Route

A private route refers to a route with nonce verification.

After declaring our routes, we instantiate the Routes class with a unique namespace.

This time, we pass in a nonce key and nonce name as the second and third argument, respectively.

Since nonce handling requires WordPress core functions, we must instantiate the Routes class after core functions have been loaded. You can use the init hook, or any other appropriate hook to ensure core functions are loaded.

Calling the Private Route

In general, private routes are called via AJAX from a JavaScript file on the WordPress site. To do this, we must make the nonce available to the script in which we want to call the route.

Leveraging wp_localize_script, we can use a helper method from the Routes class to inject the nonce variables:

Now, my-script.js will have the nonce variables we need to make the call.

URL Parameters

Curly braces are used to define a URL parameter.

URL parameters are parsed and then inserted into an $args variable, which is always the first parameter given to the handler function.

You can define as many parameters as you want.

You can also limit the type of parameter accepted, as well as provide your own patterns for more granular control.

There are many possibilities for route definitions. For detailed information about how routes are resolved, refer here.

Form Data

The router expects POST requests to be sent with a content type of application/x-www-form-urlencoded. Form data is sent as a JSON encoded string as the value of a payload key in the body of the request.

Making Everything Easier

As we've seen above, private routes require a nonce key-value pair to be present in the body of a POST request. You may have noticed that we excluded GET requests in those examples. This is because GET requests don't have body content, which means that the nonce variables must be set as URL query parameters. This whole process is tedious, and we can do better.

For people transpiling their JavaScript, we recommend using axios with our helper library. This completely abstracts nonce handling and JSON encoding, as well as automatically setting nonce variables in the request regardless of the request method (GET, POST, PUT, etc.).

The following is the Form Data example, rewritten using these libraries: