Registering Module-Specific Routes in Expressive

In Expressive, we have standardized on a file named
config/routes.php to contain all your route registrations. A typical file
might look something like this:

declare(strict_types=1);

use ZendExpressiveCsrfCsrfMiddleware;
use ZendExpressiveSessionSessionMiddleware;

return function (
ZendExpressiveApplication $app,
ZendExpressiveMiddlewareFactory $factory,
PsrContainerContainerInterface $container
) : void {
$app->get(‘/’, AppHomePageHandler::class, ‘home’);

$app->get(‘/contact’, [
SessionMiddleware::class,
CsrfMiddleware::class,
AppContactContactPageHandler::class
], ‘contact’);
$app->post(‘/contact’, [
SessionMiddleware::class,
CsrfMiddleware::class,
AppContactProcessContactRequestHandler::class
]);
$app->get(
‘/contact/thank-you’,
AppContactThankYouHandler::class,
‘contact.done’
);

$app->get(
‘/blog[/]’,
AppBlogHandlerLandingPageHandler::class,
‘blog’
);
$app->get(‘/blog/{id:[^/]+.html’, [
SessionMiddleware::class,
CsrfMiddleware::class,
AppBlogHandlerBlogPostHandler::class,
], ‘blog.post’);
$app->post(‘/blog/comment/{id:[^/]+.html’, [
SessionMiddleware::class,
CsrfMiddleware::class,
AppBlogHandlerProcessBlogCommentHandler::class,
], ‘blog.comment’);
}

and so on.

These files can get really long, and organizing them becomes imperative.

Using Delegator Factories

One way we have recommended to make these files simpler is to use delegator
factories

registered with the ZendExpressiveApplication class to add routes. That
looks something like this:

namespace AppBlog;

use PsrContainerContainerInterface;
use ZendExpressiveApplication;
use ZendExpressiveCsrfCsrfMiddleware;
use ZendExpressiveSessionSessionMiddleware;

class RoutesDelegator
{
public function __invoke(
ContainerInterface $container,
string $serviceName,
callable $callback
) : Application {
/** @var Application $app */
$app = $callback();

$app->get(
‘/blog[/]’,
AppBlogHandlerLandingPageHandler::class,
‘blog’
);
$app->get(‘/blog/{id:[^/]+.html’, [
SessionMiddleware::class,
CsrfMiddleware::class,
HandlerBlogPostHandler::class,
], ‘blog.post’);
$app->post(‘/blog/comment/{id:[^/]+.html’, [
SessionMiddleware::class,
CsrfMiddleware::class,
HandlerProcessBlogCommentHandler::class,
], ‘blog.comment’);

return $app;
}
}

You would then register this as a delegator factory somewhere in your
configuration:

use AppBlogRoutesDelegator;
use ZendExpressiveApplication;

return [
‘dependencies’ => [
‘delegators’ => [
Application::class => [
RoutesDelegator::class,
],
],
],
];

Delegator factories run after the service has been created for the first time,
but before it has been returned by the container. They allow you to interact
with the service before it’s returned; you can configure it futher, add
listeners, use it to configure other services, or even use them to replace the
instance with an alternative. In this example, we’re opting to configure the
Application class further by registering routes with it.

We’ve even written this approach up in our documentation.

So far, so good. But it means discovering where routes are registered becomes
more difficult. You now have to look in each of:

config/routes.php

Each file in config/autoload/:

looking for delegators attached to the Application class,
and then checking those to see if they register routes.

In config/config.php to identify ConfigProvider classes, and then:

looking for delegators attached to the Application class,
and then checking those to see if they register routes.

The larger your application gets, the more work this becomes. Your
config/routes.php becomes way more readable, but it becomes far harder to find
all your routes.

One-off Functions

In examining this problem for the upteenth time this week, I stumbled upon a
solution that is initially acceptable to me, finally.

What I’ve done is as follows:

I’ve created a function in my ConfigProvider that accepts the Application
instance and any other arguments I want to pass to it, and which registers
routes with the instance.
I call that function within my config/routes.php.

Building on the example above, the ConfigProvider for the AppBlog module
now has the following method:

namespace AppBlog;

use ZendExpressiveApplication;
use ZendExpressiveCsrfCsrfMiddleware;
use ZendExpressiveSessionSessionMiddleware;

class ConfigProvider
{
public function __invoke() : array
{
/* … */
}

public function registerRoutes(
Application $app,
string $basePath = ‘/blog’
) : void {
$app->get(
$basePath . ‘[/]’,
AppBlogHandlerLandingPageHandler::class,
‘blog’
);
$app->get($basePath . ‘/{id:[^/]+.html’, [
SessionMiddleware::class,
CsrfMiddleware::class,
HandlerBlogPostHandler::class,
], ‘blog.post’);
$app->post($basePath . ‘/comment/{id:[^/]+.html’, [
SessionMiddleware::class,
CsrfMiddleware::class,
HandlerProcessBlogCommentHandler::class,
], ‘blog.comment’);
}
}

Within my config/routes.php, I can create a temporary instance and call the
method:

declare(strict_types=1);

return function (
ZendExpressiveApplication $app,
ZendExpressiveMiddlewareFactory $factory,
PsrContainerContainerInterface $container
) : void {
(new AppBlogConfigProvider())->registerRoutes($app);
}

This approach eliminates the problems of using delegator factories:

There’s a clear indication that a given class method registers routes.
I can then look directly at that method to determine what they are.

One thing I like about this approach is that it allows me to keep the routes
close to the code that handles them (i.e., within each module), while still
giving me control over their registration at the application level.

What strategies have you tried?

Registering Module-Specific Routes in Expressive was originally
published 24 January 2019
on https://mwop.net by
Matthew Weier O’Phinney.

Flatlogic Admin Templates banner

Leave a Reply

Your email address will not be published. Required fields are marked *