Router

About 8 min

Router

Central HTTP router for application request dispatch.

class Router implements \Hazaar\Application\Interface\Router

Implements: Hazaar\Application\Interface\Router

The router coordinates route registration, route loading, request matching, middleware execution, and final controller dispatch for the current application instance.

Core responsibilities:

Load route definitions through a pluggable loader (type in router config).
Provide static helpers for HTTP verb route registration (get, post, match, etc.).
Resolve requests in a deterministic order:
1. Internal controller shortcuts (self::$internal).
2. Loader-provided route match ($routeLoader->evaluateRequest()).
3. In-memory routes added at runtime ($this->routes).
4. Default controller/action fallback for the root path (/).
Build a middleware pipeline and execute the resolved controller action.
Emit structured request lifecycle logs for route match, dispatch, and completion.

Instance access:

The class supports static access through getInstance() and can also hold an explicit static instance (setInstance/clearInstance) for loader and helper integrations.

important now that Hazaar\Application\Router::getRoutes may trigger it lazily outside the normal bootstrap flow (for example from the OpenAPI generator), where re-running a file-type loader would re-include route.php and duplicate every route.

matchers

Registered custom parameter matchers, keyed by name.

private array $matchers

Type: array

Each matcher is either a PCRE pattern string or a \Closure that accepts the raw path segment and returns true when it matches. Matchers only validate a segment's format; they never transform the value.

builtinMatchers

Built-in matchers registered on every router instance.

private array $builtinMatchers = array (
  'uuid' => '/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i',
  'ulid' => '/^[0-7][0-9A-HJKMNP-TV-Z]{25}$/i',
  'slug' => '/^[a-z0-9]+(?:-[a-z0-9]+)*$/',
  'date' => '/^\\d{4}-\\d{2}-\\d{2}$/',
)

Type: array

These are seeded in the constructor and can be overridden by calling Hazaar\Application\Router::addMatcher with the same name.

instance

public self $instance

Type: self

Methods

__construct

public __construct(Options $config = 'new Options()', array $middlewareAliases): void

Parameter	Type	Description
`$config`	Hazaar\Application\Router\Options
`$middlewareAliases`	array

Parameter	Type	Description
`$name`	string	the matcher name, as referenced in route patterns
`$matcher`	Closure	string

Parameter	Type	Description
`$name`	string	the matcher name
`$value`	string	the raw path segment to validate

Parameter	Type	Description
`$path`	string	the URL path for the route
`$callable`	Closure	ReflectionMethod
`$actionArgs`	array	optional action arguments for the route

Parameter	Type	Description
`$path`	string	the URI path that the route will respond to
`$callable`	Closure	ReflectionMethod
`$actionArgs`	array	optional action arguments for the route

Parameter	Type	Description
`$path`	string	the URL path that the route should match
`$callable`	Closure	ReflectionMethod
`$actionArgs`	array	optional action arguments for the route

Parameter	Type	Description
`$path`	string	the URI path that the route will match
`$callable`	Closure	ReflectionMethod
`$actionArgs`	array	optional action arguments for the route

Parameter	Type	Description
`$path`	string	the URL path to match
`$callable`	Closure	ReflectionMethod
`$actionArgs`	array	optional action arguments for the route

Parameter	Type	Description
`$path`	string	the path pattern to match
`$callable`	Closure	ReflectionMethod
`$actionArgs`	array	optional action arguments for the route

Parameter	Type	Description
`$prefix`	string	the URL prefix for the grouped routes
`$callback`	Closure	a callback function that receives the Router instance

Parameter	Type	Description
`$methods`	array	string
`$path`	string	The path to match (e.g., '/user/{id}').
`$callable`	Closure	ReflectionMethod
`$actionArgs`	array	optional action arguments for the route