3.4.6. Custom Matching Rules

3.4.6.1. Writing A Custom Rule

Writing a custom matching rule, say one that checks the authentication state, is a bit involved but not difficult.

1. Write a rule class that implements the RuleInterface.

2. Get the RuleIterator from the RouterContainer and append() or prepend() your new Rule. (You can also wrap it in a callable to make it lazy-loaded, such as with Aura.Di Lazy instances.)

3. Use the Matcher as normal.

Here is a naive rule that checks to see if the request has a particular header set; the rule passes if it is, and fails if it does not. The header value is captured into the route attributes.

<?php
use Aura\Router\Route;
use Aura\Router\Rule\RuleInterface;
use Psr\Http\Message\ServerRequestInterface;

class ApiVersionRule implements RuleInterface
{
    public function __invoke(ServerRequestInterface $request, Route $route)
    {
        $versions = $request->getHeader('X-Api-Version');
        if (count($versions) !== 1) {
            return false;
        }

        $route->attributes(['apiVersion' => $versions[0]]);
        return true;
    }
}
?>

You can then prepend() or append() the rule to the RuleIterator from the RouterContainer. (Prepended rules get run first, appended ones last.)

<?php
$ruleIterator = $routerContainer->getRuleIterator();
$ruleIterator->append(new ApiVersionRule());
?>

Then you can run the Matcher as normal, and your new rule will be honored.

<?php
$matcher = $routerContainer->getMatcher();
$route = $matcher->match($request);
?>

3.4.6.2. Setting Rules

If you want, you can set all the matching rules into the RouterContainer in advance. They will be injected into the RuleIterator and thereby into the Matcher automatically.

For good or bad, you need to pass the entire set of rules, not just your custom ones. This is because you need to include not just your own rules, but the default ones as well. It would look something like this:

use Aura\Router\Rule;

$routerContainer->getRuleIterator()->set([
    // default rules
    new Rule\Secure(),
    new Rule\Host(),
    new Rule\Path(),
    new Rule\Allows(),
    new Rule\Accepts(),
    new Rule\Special(),
    // custom rule
    new ApiVersionRule()
]);

N.b. You can review the RouterContainer::getRules() method to see the default rule set.

Setting all the rules at once means you can place your rule exactly where you want. If you want your custom rule to go right in the middle of the default set, you could do something like this:

use Aura\Router\Rule;

$routerContainer->getRuleIterator()->set([
    new Rule\Secure(),
    new Rule\Host(),
    new ApiVersionRule(), // custom rule in the middle
    new Rule\Path(),
    new Rule\Allows(),
    new Rule\Accepts(),
    new Rule\Special(),
]);

Finally, if you feel you don't need some rules, you can omit them from the list. For example, you may only care about path and HTTP method matching:

use Aura\Router\Rule;

$routerContainer->getRuleIterator()->set([
    new Rule\Path(),
    new Rule\Allows(),
]);