Routing

JL
Last updated 22 days ago

Introduction

Sometimes you may want to create a page on your website but not need/want it editable in WordPress. That's when the custom Lumberjack router comes into play. It can also be used to make AJAX endpoints.

If you set up a custom route that has the same URL as a WordPress page, the router takes priority.

Route closures and controller functions are automatically dependency injected from the container.

Creating Routes

Routing is handled by using the Rareloop\Lumberjack\Facades\Router Facade. The convention is to create your Routes in the routes.php file at the base of your theme.

Typically, you only need to allow one HTTP verb for a route (e.g. POST or GET). To create a route, use the HTTP verb as the method name. The first parameter is the URI and the second is the code you wish to execute when that route is matched.

Router::get('test/route', function () {});
Router::post('test/route', function () {});
Router::put('test/route', function () {});
Router::patch('test/route', function () {});
Router::delete('test/route', function () {});
Router::options('test/route', function () {});

Route Parameters

Parameters can be defined on routes using the {keyName} syntax. When a route that contains parameters is matched, those parameters are available as injectable parameters in your callback/controller. The name of the route parameter and the controller parameter must be the same.

Router::get('posts/{id}', function($id) {
});

As the parameters are injected by name, it doesn't matter which order you have the parameters in your callback/controller:

// /posts/123/comments/1
Router::get('posts/{postId}/comments/{commentId}', function($commentId, $postId) {
echo $commendId; // 1
echo $postId; // 123
});

Parameter Constraints

By default, all parameters will match against all non / characters. You can make the match more specific by supplying a regular expression:

Router::get('posts/{id}', function () {})->where('id', '[0-9]+');
// Will match /posts/123
// Won't match /posts/abc

Named Routes

Routes can be named so that their URL can be generated programatically:

Router::get('posts/all', function () {})->name('posts.index');
$url = Router::url('posts.index');

If the route requires parameters you can be pass an associative array as a second parameter:

Router::get('posts/{id}', function () {})->name('posts.show');
$url = Router::url('posts.show', ['id' => 123]);

Route Groups

It is common to group similar routes behind a common prefix. This can be achieved using Route Groups:

Router::group('prefix', function ($group) {
$group->get('route1', function () {}); // `/prefix/route1`
$group->get('route2', function () {}); // `/prefix/route2`
});

Route Controllers

If you'd rather use a class to group related route actions together you can pass a Controller String instead of a closure.

The string takes the format {name of class}@{name of method}. The Router will be default look for classes in the App\Controllers namespace, so you don't need to include this prefix in the Controller String.

// app/Http/Controllers/TestController.php
namespace App\Http\Controllers;
class TestController
{
public function show()
{
return 'Hello World';
}
}
// routes.php
Router::get('route/uri', 'TestController@show');

If you want to reference a Controller in another namespace you'll need to append the complete namespace to the classname:

// My/Namespace/TestController.php
namespace My\Namespace;
class TestController
{
public function show()
{
return 'Hello World';
}
}
// routes.php
Router::get('route/uri', '\My\Namespace\TestController@show');

Map

If you need match a URL for multiple HTTP methods, you can use the map method and pass in an array of HTTP methods to match.

use Rareloop\Lumberjack\Facades\Router;
// Creates a route that matches the uri `/posts/list` both GET
// and POST requests.
Router::map(['GET', 'POST'], 'posts/list', function () {
return 'Hello World';
});

map() takes 3 parameters:

  • methods (array): list of matching HTTP methods, valid values:

    • GET

    • POST

    • PUT

    • PATCH

    • DELETE

    • OPTIONS

  • uri (string): The URI to match against

  • action (function|string): Either a closure or a Controller string

Middleware

PSR-15/7 Middleware can be added to both routes and groups on the route.

Adding Middleware to a route

At it's simplest, adding Middleware to a route can be done by passing an object to the middleware() function:

$middleware = new AddHeaderMiddleware('X-Key1', 'abc');
Router::get('route/uri', '\MyNamespace\TestController@testMethod')->middleware($middleware);

Multiple middleware can be added by passing more params to the middleware() function:

$header = new AddHeaderMiddleware('X-Key1', 'abc');
$auth = new AuthMiddleware();
Router::get('route/uri', '\MyNamespace\TestController@testMethod')->middleware($header, $auth);

Or alternatively, you can also pass an array of middleware:

$header = new AddHeaderMiddleware('X-Key1', 'abc');
$auth = new AuthMiddleware();
Router::get('route/uri', '\MyNamespace\TestController@testMethod')->middleware([$header, $auth]);

Adding Middleware to a group

Middleware can also be added to a group. To do so you need to pass an array as the first parameter of the group()function instead of a string.

$header = new AddHeaderMiddleware('X-Key1', 'abc');
Router::group(['prefix' => 'my-prefix', 'middleware' => $header]), function ($group) {
$group->get('route1', function () {}); // GET `/my-prefix/route1`
$group->get('route2', function () {}); // GET `/my-prefix/route2`
});

You can also pass an array of middleware if you need more than one:

$header = new AddHeaderMiddleware('X-Key1', 'abc');
$auth = new AuthMiddleware();
Router::group(['prefix' => 'my-prefix', 'middleware' => [$header, $auth]]), function ($group) {
$group->get('route1', function () {}); // GET `/my-prefix/route1`
$group->:get('route2', function () {}); // GET `/my-prefix/route2`
});

Extending the Router

The Lumberjack Router class can be extended with custom functionality at runtime (the class is "macroable"). The following example adds an redirect method to the Router class that can be used to easily declare redirect routes, without needing to handle the response logic yourself:

use Rareloop\Lumberjack\Facades\Router;
// Add the custom functionality
Router::macro('redirect', function ($inputUrl, $outputUrl) {
$this->get($inputUrl, function () use ($outputUrl) {
return new RedirectResponse($outputUrl);
});
});
// Use the custom functionality
Router::redirect('/old/url', '/new/url');

It is also possible to extend the Route class too, this can be useful for encapsulating common route behaviour in a more fluent API.

use Rareloop\Lumberjack\Facades\Router;
use Rareloop\Router\Route;
// Add the custom functionality
Route::macro('adminOnly', function () {
$this->middleware(new App\AdminMiddlewareOne);
$this->middleware(new App\AdminMiddlewareTwo);
$this->middleware(new App\AdminMiddlewareThree);
return $this;
});
// Use the custom functionality
Router::get('route/uri', 'AdminController@action')->adminOnly();

Remember to return $this in your custom Route macro extensions so that the API remains chainable.