Download the PHP package upstatement/routes without Composer

Routes

Simple routing for WordPress. Designed for usage with Timber

Installation

Install via Composer:

Then make sure Composer's autoloader is included in your project. In a standard WordPress setup this is typically done in functions.php or your plugin's main file:

If you're using a WordPress-specific Composer setup (e.g. Bedrock), the autoloader is usually already loaded for you.

Upgrading to 1.x

Version 1.0 introduces several breaking changes. If you're upgrading from 0.x, read through the following sections to make sure your code is compatible.

PHP 8.2+ required

Routes now requires PHP 8.2 or higher.

Singleton — no direct instantiation

The class is now a singleton. You can no longer instantiate it directly:

In practice most applications never instantiated Routes directly, so this is unlikely to affect you.

No more global $upstatement_routes

The global variable $upstatement_routes used internally in 0.x has been removed. If your code accessed called $upstatement_routes->match_current_request() directly, update it:

New add_match_types() method

Custom AltoRouter match types can now be registered via Routes::add_match_types() and may be called before or after Routes::map():

Class is no longer auto-instantiated on include

In 0.x, including Routes.php immediately instantiated the class and registered WordPress hooks. In 1.x, the singleton is created lazily on the first call to Routes::map() or Routes::add_match_types(). No action is required as long as you call Routes::map() before wp_loaded fires, which is the standard usage pattern.

Base path handling for subdirectory installs

⚠️ Potential breaking change for WordPress subdirectory installations

In 0.x, the base path logic was route-dependent and would detect if you included the subdirectory in your route pattern. In 1.x, the base path is always calculated from your site URL regardless of your route patterns.

If your WordPress site is installed in a subdirectory (e.g., https://example.com/blog/) and your routes included that subdirectory in the pattern, those routes will break in 1.x.

Example of code that will break:

How to fix it:

Simply remove the subdirectory prefix from your route patterns:

Note: If your site is not in a subdirectory, or if your routes never included the subdirectory prefix, this change does not affect you.

Basic Usage

Using routes makes it easy for you to implement custom pagination — and anything else you might imagine in your wildest dreams of URLs and parameters. OMG so easy!

Some examples

In your functions.php file, this can be called anywhere (don't hook it to init or another action or it might be called too late)

map

Routes::map($pattern, $callback)

Usage

A functions.php where I want to display custom paginated content:

Arguments

$pattern (required) Set a pattern for Routes to match on, by default everything is handled as a string. Any segment that begins with a : is handled as a variable, for example:

To paginate:

To edit a user:

$callback A function that should fire when the pattern matches the request. Callback takes one argument which is an array of the parameters passed in the URL.

So in this example: 'info/:name/page/:pg', $params would have data for:

• $data['name']
• $data['pg']

... which you can use in the callback function as a part of your query

load

Routes::load($php_file, $args, $query = null, $status_code = 200)

Arguments

$php_file (required) A PHP file to load, in my experience this is usually your archive.php or a generic listing page (but don't worry it can be anything!)

$template_params Any data you want to send to the resulting view. Example:

$query The query you want to use, it can accept a string or array just like Timber::get_posts -- use the standard WP_Query syntax (or a WP_Query object too)

$status_code Send an optional status code. Defaults to 200 for 'Success/OK'

add_match_types

This method makes it possible to add custom match types in Routes.