Handler

Middleware registration and execution handler.

class Handler

This class wraps middleware metadata, including constructor arguments and route/method matching constraints, and provides execution orchestration for middleware instances.

A middleware passed as an instance is kept on its own handler, so differently configured instances of the same class stay separate. A middleware registered by class name or alias is constructed once and shared through a per-class cache. Each middleware is dispatched through its handle() method with the active request and downstream callable.

Properties

name

Name of the middleware.

public string $name

Type: string

args

Arguments passed to the middleware.

public array $args

Type: array

methods

Array of methods this middleware applies to.

private array $methods

Type: array

exceptMethods

Array of methods this middleware does not apply to.

private array $exceptMethods

Type: array

instance

public Middleware $instance

Type: Hazaar\Middleware\Interface\Middleware

middlewareInstances

Shared instances of middleware registered by class name or alias.

private array $middlewareInstances

Type: array

This avoids constructing the same middleware class on every request. Explicitly passed instances are never stored here, because they may carry per-route config.

Methods

__construct

Constructor to initialize the middleware handler.

public __construct(Middleware|string $middleware, array $args): void

Parameters

Parameter	Type	Description
$middleware	Hazaar\Middleware\Interface\Middleware	string
$args	array	Arguments for the middleware

run

Executes the middleware by either reusing an existing instance or creating a new one,

public run(Request $request, callable $next): Response

Returns: Hazaar\Controller\Response

then calls its 'handle' method with the provided request, next callable, and any additional arguments.

A handler registered with an instance always runs that instance.

Parameters

Parameter	Type	Description
$request	Hazaar\Application\Request	the current HTTP request object
$next	callable	the next middleware or handler to be executed

shutdown

Invokes Hazaar\Middleware\Interface\Terminable::shutdown on the underlying middleware instance,

public shutdown(Request $request, ?Response $response): void

Returns: void

if it implements that interface. A no-op for middleware that don't need post-response cleanup.

Looks the instance up the same way Hazaar\Middleware\Handler::run does (by $this->name, not by iterating the whole static instance cache) — that cache is shared across every Handler, for every middleware class in the app, so iterating it here would call shutdown() on unrelated middleware that had nothing to do with this handler's request.

Parameters

Parameter	Type	Description
$request	Hazaar\Application\Request
$response	Hazaar\Controller\Response	the response that was sent, or null if the pipeline threw before one could be produced

only

Specifies that this middleware should only apply to the given HTTP method.

public only(string $method): self

Returns: self

Parameters

Parameter	Type	Description
$method	string	The HTTP method (e.g., 'GET', 'POST') to which the middleware should be restricted.

except

Excludes the specified HTTP method from being processed by this middleware.

public except(string $method): self

Returns: self

Parameters

Parameter	Type	Description
$method	string	The HTTP method to exclude (e.g., 'GET', 'POST').

Determines if the given action name matches the middleware's method rules.

public (string $actionName): bool

Returns: bool

Checks if the provided action name is included in the allowed methods and not in the excepted methods. If no specific methods are set, only checks against the excepted methods.

Parameters

Parameter	Type	Description
$actionName	string	the name of the action to check

getName

public getName(): string

Returns: string

getInstance

Get the middleware instance for this handler.

private getInstance(bool $create): ?Middleware

Returns: Hazaar\Middleware\Interface\Middleware

Parameters

Parameter	Type	Description
$create	bool	construct and cache the class if it has no shared instance yet

---

Generated by Hazaar API Doc Generator on Thu, 22 Oct 2026 05:05:29 +0000