PHPackages                             upstatement/routes - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. upstatement/routes

ActiveLibrary[HTTP & Networking](/categories/http)

upstatement/routes
==================

Manage rewrites and routes in WordPress with this dead-simple plugin

0.10.0(3mo ago)2002.6M↓44.4%43[4 issues](https://github.com/Upstatement/routes/issues)[1 PRs](https://github.com/Upstatement/routes/pulls)6MITPHPPHP >=8.2CI passing

Since Feb 16Pushed 2mo ago26 watchersCompare

[ Source](https://github.com/Upstatement/routes)[ Packagist](https://packagist.org/packages/upstatement/routes)[ Docs](https://www.upstatement.com)[ RSS](/packages/upstatement-routes/feed)WikiDiscussions master Synced 3d ago

READMEChangelog (10)Dependencies (28)Versions (21)Used By (6)

Routes
======

[](#routes)

Simple routing for WordPress. Designed for usage with [Timber](https://github.com/timber/timber)

[![PHP unit tests](https://github.com/Upstatement/routes/actions/workflows/php-unit-tests.yml/badge.svg?branch=master)](https://github.com/Upstatement/routes/actions/workflows/php-unit-tests.yml?query=branch:master)[![Latest Stable Version](https://camo.githubusercontent.com/9c534b81ee5eae182cbd545dad0268a3bfaef517f2c856ddaa5d3f932bdd1e9b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f557073746174656d656e742f726f757465732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/Upstatement/routes)

Installation
------------

[](#installation)

Install via [Composer](https://getcomposer.org/):

```
composer require upstatement/routes
```

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:

```
require_once __DIR__ . '/vendor/autoload.php';
```

If you're using a WordPress-specific Composer setup (e.g. [Bedrock](https://roots.io/bedrock/)), the autoloader is usually already loaded for you.

Upgrading to 1.x
----------------

[](#upgrading-to-1x)

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

[](#php-82-required)

Routes now requires PHP 8.2 or higher.

### Singleton — no direct instantiation

[](#singleton--no-direct-instantiation)

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

```
// Before (0.x) — no longer works
$routes = new Routes();

// After (1.x)
$instance = Routes::get_instance();
```

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

### No more global `$upstatement_routes`

[](#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:

```
// Before (0.x)
global $upstatement_routes;
$upstatement_routes->match_current_request();

// After (1.x)
Routes::get_instance()->match_current_request();
```

### New `add_match_types()` method

[](#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()`:

```
Routes::add_match_types(['hex' => '[0-9A-Fa-f]+']);
Routes::map('color/[hex:color]', function($params) {
    // $params['color'] is guaranteed to be a hex string
});
```

### Class is no longer auto-instantiated on include

[](#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

[](#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:**

```
// Site URL: https://example.com/blog/
// WordPress installed in /blog/ subdirectory

// This route WILL BREAK in 1.x:
Routes::map('blog/my-page', function($params) {
    // This won't match anymore because AltoRouter strips /blog/
    // and then tries to match the remainder against 'blog/my-page'
});
```

**How to fix it:**

Simply remove the subdirectory prefix from your route patterns:

```
// Site URL: https://example.com/blog/
// WordPress installed in /blog/ subdirectory

// ✅ Correct way to define routes in 1.x:
Routes::map('my-page', function($params) {
    // This will correctly match https://example.com/blog/my-page
});

Routes::map('my-users/:userid/edit', function($params) {
    // This will correctly match https://example.com/blog/my-users/123/edit
});
```

**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

[](#basic-usage)

```
/* functions.php */
Routes::map('myfoo/bar', 'my_callback_function');
Routes::map('my-events/:event', function($params) {
    $event_slug = $params['event'];
    $event = new ECP_Event($event_slug);
    $query = new WPQuery(); //if you want to send a custom query to the page's main loop
    Routes::load('single.php', array('event' => $event), $query, 200);
});
```

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
-------------

[](#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)

```