Documentation

RouterChunkedMode extends Router
in package

Chunked mode will match routes with a big chunked regex.

This is largely inspired by FastRoute. https://www.npopov.com/2014/02/18/Fast-request-routing-using-regular-expressions.html

Table of Contents

Constants

ATTR_ALL  : mixed = self::ATTR_ATTRIBUTES | self::ATTR_DOCS
Extract all attribute routes.
ATTR_ATTRIBUTES  : mixed = 1
Extract attribute (PHP8) routes.
ATTR_DOCS  : mixed = 2
Extract doc routes.
EXTRACT_ALL  : mixed = 3
Extract routes from both namespaces + attributes.
EXTRACT_ATTRIBUTES  : mixed = 2
Extract routes from attributes.
EXTRACT_CONVERT_REGEX  : mixed = 128
Convert extracted rule-style patterns to regex.
EXTRACT_NAMESPACES  : mixed = 1
Extract routes from method namespaces.
EXTRACT_NESTED_PREFIXES  : mixed = 1024
Add prefixes, but also permit multiple controllers per rule.
EXTRACT_NONE  : mixed = 0
Do not extract routes from classes.
EXTRACT_SHORT_NAMESPACES  : mixed = 512
Use only the class::method when extracting namespace rules.
EXTRACT_SORT_ATTRIBUTES  : mixed = 2048
Sort attributes by priority.
EXTRACT_WITH_PREFIXES  : mixed = 256
Add prefixes (from the route table) to the extracted extract routes.
METHODS  : mixed = ['HEAD', 'GET', 'OPTIONS', 'POST', 'PUT', 'PATC...
Some standard default methods.
MODE_CHUNKED  : mixed = 'chunked'
Use (fast) 'rule' patterns when parsing rules.
MODE_REGEX  : mixed = 'regex'
Use regex patterns when parsing rules.
MODE_SINGLE  : mixed = 'single'
Use (slow) 'rule' patterns when parsing rules.
MODES  : mixed = [self::MODE_SINGLE => \karmabunny\router\Modes\...
PATTERN_POSITION  : string = '([^/]+?)'
PATTERN_RULE  : string = '!(?:\\\\{([a-z][a-z0-9_]*)\\\\}|\\\\\\*+)!i'
Regex {var} or wildcard.
PATTERN_WILD  : string = '(.+?)'
RULE_TEMPLATE  : string = '!\\\\{([a-z][a-z0-9_]*)\\\\}!i'
Match for rule variables like `{var}`, after `preg_quote`.

Properties

$config  : RouterConfig
$patterns  : array<string|int, mixed>
$routes  : array<string, mixed>
$rule_inspector  : callable|null

Methods

compile()  : void
Creates chunked regex patterns and related metadata.
create()  : Router
Create a router.
extractFromAttributes()  : array<string|int, mixed>
Find all the attribute routes on a target object/class.
extractFromNamespaces()  : array<string|int, mixed>
Find all the namespace routes on a target object/class.
extractRuleNames()  : array<string|int, string>
Determine the parameter names of a route pattern.
fillRuleValues()  : string
Insert parameters into a route pattern.
find()  : null|Action
Find a matching route.
getRoutes()  : array<string, mixed>
Get the currently loaded routes.
getRuleInspector()  : callable
Get the rule inspector function.
isCallable()  : bool
Is the 'target' callable?
load()  : array<string, mixed>
Load routes.
loadAttributes()  : void
Load attribute routes from a class.
loadFrom()  : void
Load magic routes from a class.
loadNamespaces()  : void
Load namespace routes from a class.
normalizeMatches()  : array<string|int, mixed>
Given an array of matches from `preg_match()` the named groups are duplicate entries. This will strip the numeric versions _and_ append non-named groups to the end of the array.
sortAttributes()  : void
Sort attributes by priority.
__construct()  : mixed
editNamespaceRule()  : string
Call the user-configured edit namespace rule config.
extractAll()  : array<string, mixed>
Perform rule extractions, as appropriate.
insertPrefix()  : string
Insert a prefix.

Constants

ATTR_ALL

Extract all attribute routes.

public mixed ATTR_ALL = self::ATTR_ATTRIBUTES | self::ATTR_DOCS

ATTR_ATTRIBUTES

Extract attribute (PHP8) routes.

public mixed ATTR_ATTRIBUTES = 1

ATTR_DOCS

Extract doc routes.

public mixed ATTR_DOCS = 2

EXTRACT_ALL

Extract routes from both namespaces + attributes.

public mixed EXTRACT_ALL = 3

EXTRACT_ATTRIBUTES

Extract routes from attributes.

public mixed EXTRACT_ATTRIBUTES = 2

EXTRACT_CONVERT_REGEX

Convert extracted rule-style patterns to regex.

public mixed EXTRACT_CONVERT_REGEX = 128

EXTRACT_NAMESPACES

Extract routes from method namespaces.

public mixed EXTRACT_NAMESPACES = 1

EXTRACT_NESTED_PREFIXES

Add prefixes, but also permit multiple controllers per rule.

public mixed EXTRACT_NESTED_PREFIXES = 1024

EXTRACT_NONE

Do not extract routes from classes.

public mixed EXTRACT_NONE = 0

EXTRACT_SHORT_NAMESPACES

Use only the class::method when extracting namespace rules.

public mixed EXTRACT_SHORT_NAMESPACES = 512

EXTRACT_SORT_ATTRIBUTES

Sort attributes by priority.

public mixed EXTRACT_SORT_ATTRIBUTES = 2048

Like so:

  1. METHOD + no variables
  2. METHOD + variables
  3. METHOD + wildcards
  4. (all) + no variables
  5. (all) + variables
  6. (all) + wildcards
  7. rule length (longer first)
  8. lexicographic

NOTE: rules are sorted per target/controller, not globally.

EXTRACT_WITH_PREFIXES

Add prefixes (from the route table) to the extracted extract routes.

public mixed EXTRACT_WITH_PREFIXES = 256

METHODS

Some standard default methods.

public mixed METHODS = ['HEAD', 'GET', 'OPTIONS', 'POST', 'PUT', 'PATCH', 'DELETE']

MODE_CHUNKED

Use (fast) 'rule' patterns when parsing rules.

public mixed MODE_CHUNKED = 'chunked'

MODE_REGEX

Use regex patterns when parsing rules.

public mixed MODE_REGEX = 'regex'

MODE_SINGLE

Use (slow) 'rule' patterns when parsing rules.

public mixed MODE_SINGLE = 'single'

MODES

public mixed MODES = [self::MODE_SINGLE => \karmabunny\router\Modes\RouterSingleMode::class, self::MODE_CHUNKED => \karmabunny\router\Modes\RouterChunkedMode::class, self::MODE_REGEX => \karmabunny\router\Modes\RouterRegexMode::class]

PATTERN_RULE

Regex {var} or wildcard.

public string PATTERN_RULE = '!(?:\\\\{([a-z][a-z0-9_]*)\\\\}|\\\\\\*+)!i'
  • Match one, contains a var name
  • Empty, it's a wildcard

RULE_TEMPLATE

Match for rule variables like `{var}`, after `preg_quote`.

public string RULE_TEMPLATE = '!\\\\{([a-z][a-z0-9_]*)\\\\}!i'

Properties

$routes

public array<string, mixed> $routes = []

[ rule => target ]

$rule_inspector

protected callable|null $rule_inspector = null

Methods

compile()

Creates chunked regex patterns and related metadata.

public compile(array<string, mixed> $routes) : void

If you're following the FastRoute blog, this creates patterns with the 'Group Position Based Chunked' method.

I couldn't grok how to create 'Group Count Based' and it's complexity didn't feel beneficial. I may eat my words later. We can always switch that in later if we need to.

Parameters
$routes : array<string, mixed>

[ rule => target ]

create()

Create a router.

public static create([RouterConfig|array<string, mixed> $config = [] ]) : Router
Parameters
$config : RouterConfig|array<string, mixed> = []
Tags
throws
InvalidArgumentException
Return values
Router

extractFromAttributes()

Find all the attribute routes on a target object/class.

public extractFromAttributes(string|object $class[, string $prefix = '' ]) : array<string|int, mixed>

An attribute route is a PHP8 attribute or a @route doc comment.

Parameters
$class : string|object
$prefix : string = ''
Tags
throws
ReflectionException
Return values
array<string|int, mixed> —

[ rule => target ]

extractFromNamespaces()

Find all the namespace routes on a target object/class.

public extractFromNamespaces(string|object $class[, string $prefix = '' ][, bool $short = false ]) : array<string|int, mixed>

A namespace route is one generated from the class namespace + method + arguments.

Like so:

## /Bloom/Controllers/ToolsController::dbSync($schema)
=> 'ACTION /tools/db-sync/{$schema}'

Note the verb is 'ACTION'. It's up to you what an 'action' is.

If you want to match everything I guess something like this works:

$route = $router->find($method, $path);
if (!$route) {
   $route = $router->find('ACTION', $path);
}

The router can be configured to clean up the rule before inserting into the route table with the edit_namespace_rule config. By default, this cleans out tokens like 'controller', 'app', 'core', 'module'.

What qualifies as an acceptable action method:

  • must be public
  • cannot be variadic
  • cannot be a constructor/destructor
  • cannot start with an underscore
  • arguments must be one of: string, int, float, mixed
Parameters
$class : string|object
$prefix : string = ''
$short : bool = false

Use short names (class::method only)

Tags
throws
ReflectionException
Return values
array<string|int, mixed> —

[ rule => target ]

extractRuleNames()

Determine the parameter names of a route pattern.

public static extractRuleNames(string $rule) : array<string|int, string>
Parameters
$rule : string

Route pattern

Return values
array<string|int, string>

fillRuleValues()

Insert parameters into a route pattern.

public static fillRuleValues(string $rule, array<string, string> $parameters) : string
Parameters
$rule : string

Route pattern

$parameters : array<string, string>

Keyed array: name => value

Return values
string —

A regular string path

find()

Find a matching route.

public find(string $method, string $path) : null|Action
Parameters
$method : string
$path : string
Tags
inheritdoc
Return values
null|Action

getRoutes()

Get the currently loaded routes.

public getRoutes() : array<string, mixed>
Return values
array<string, mixed>

getRuleInspector()

Get the rule inspector function.

public getRuleInspector([bool $refresh = false ]) : callable
Parameters
$refresh : bool = false
Return values
callable

isCallable()

Is the 'target' callable?

public static isCallable(mixed $target) : bool

However, this doesn't mean that one can invoke the property directly.

For a non-static target [class, method] this will return true but it's not possible to call these (in PHP 8+) without first creating a class instance.

Parameters
$target : mixed
Return values
bool

load()

Load routes.

public load(array<string|int, mixed> $routes) : array<string, mixed>
Parameters
$routes : array<string|int, mixed>

[ rule => target ]

Tags
inheritdoc
Return values
array<string, mixed> —

[ rule => target ] diff of new routes

loadAttributes()

Load attribute routes from a class.

public loadAttributes(string|object $class[, string $prefix = '' ]) : void

This will extract routes regardless of the 'extract' config.

Parameters
$class : string|object
$prefix : string = ''

loadFrom()

Load magic routes from a class.

public loadFrom(string|object $class[, string $prefix = '' ][, bool $short = false ]) : void

This loads attributes and namespace routes regardless of the 'extract' config settings.

Parameters
$class : string|object
$prefix : string = ''
$short : bool = false

loadNamespaces()

Load namespace routes from a class.

public loadNamespaces(string|object $class[, string $prefix = '' ][, bool $short = false ]) : void

This will extract routes regardless of the 'extract' config.

Parameters
$class : string|object
$prefix : string = ''
$short : bool = false

Use short names (class::method only)

normalizeMatches()

Given an array of matches from `preg_match()` the named groups are duplicate entries. This will strip the numeric versions _and_ append non-named groups to the end of the array.

public static normalizeMatches(array<string|int, mixed> $matches) : array<string|int, mixed> 
// Where 'a' + 'b' are names groups, 'm2' is numeric
$matches = [
   'a' => 'm1',
   'm1',
   'm2',
   'b' => 'm3',
   'm3',
];
// Normalise
$args = [
   'a' => 'm1',
   'b' => 'm3',
   'm2',
];
Parameters
$matches : array<string|int, mixed>
Return values
array<string|int, mixed>

sortAttributes()

Sort attributes by priority.

public sortAttributes(array<string, mixed> &$rules[, bool $refresh = false ]) : void
Parameters
$rules : array<string, mixed>
$refresh : bool = false

Refresh the rule inspector

Tags
see
Router::EXTRACT_SORT_ATTRIBUTES

editNamespaceRule()

Call the user-configured edit namespace rule config.

protected editNamespaceRule(string $rule) : string
Parameters
$rule : string
Return values
string

extractAll()

Perform rule extractions, as appropriate.

protected extractAll(string|object $target, string $prefix) : array<string, mixed>
Parameters
$target : string|object
$prefix : string
Tags
throws
ReflectionException
Return values
array<string, mixed> —

routes

insertPrefix()

Insert a prefix.

protected static insertPrefix(string $rule, string $prefix) : string

This accounts for /rule and METHOD /path style rules.

Parameters
$rule : string
$prefix : string
Return values
string
On this page

Search results