Controller

Base class for Hazaar HTTP and CLI controllers.

class Controller implements \Hazaar\Controller\Interface\Controller

Implements: Hazaar\Controller\Interface\Controller

Provides shared controller lifecycle behavior, helper registration, middleware dispatch integration, action invocation, and response normalization across concrete controller implementations.

Properties

request

public Request $request

Type: Hazaar\Application\Request

name

Normalized controller name used for routing and caching keys.

protected string $name = 'controller'

Type: string

statusCode

HTTP status code to apply to generated responses.

protected int $statusCode

Type: int

basePath

Base path used when building controller-relative URLs.

protected string $basePath

Type: string

stream

Whether the current action is producing stream output.

protected bool $stream

Type: bool

responseType

Preferred response type inferred from request headers/runtime.

protected ResponseType $responseType = 'ResponseType'

Type: Hazaar\Controller\Enums\ResponseType

helpers

protected array $helpers

Type: array

middlewareDispatcher

Middleware dispatcher for action execution pipeline.

private Dispatcher $middlewareDispatcher

Type: Hazaar\Middleware\Dispatcher

cachedActions

private array $cachedActions

Type: array

cachedResponses

private array $cachedResponses

Type: array

responseCache

public Adapter $responseCache

Type: Hazaar\Cache\Adapter

Methods

__construct

Controller initialisation method.

public __construct(Request $request): void

This should be called by all extending controllers and is simply responsible for storing the calling request.

Parameters

Parameter	Type	Description
$request	Hazaar\Application\Request	the application request object

__toString

Convert the controller object into a string.

public __toString(): string

Returns: string

__get

Get the specified helper object.

public __get(string $helper): ?Helper

Returns: Hazaar\Controller\Interface\Helper

Parameters

Parameter	Type	Description
$helper	string	the name of the helper to retrieve

__isset

Reports whether a helper has been added, for isset($this->helperName) checks.

public __isset(string $helper): bool

Returns: bool

PHP only calls __isset() for properties that don't otherwise exist on the object; without it, isset() on a helper accessed purely through __get() (e.g. $this->session, which optional-auth routes may or may not populate) always evaluates to false — silently, with no error — regardless of whether the helper was actually added.

Parameters

Parameter	Type	Description
$helper	string	the name of the helper to check

initialize

Initialize the controller.

public initialize(mixed $args): ?Response

Returns: Hazaar\Controller\Response

Calls the init() method if it exists. This allows subclasses to provide custom initialization logic by defining an init() method.

Parameters

Parameter	Type	Description
$args	mixed

run

public run(?Route $route): Response

Returns: Hazaar\Controller\Response

Parameters

Parameter	Type	Description
$route	Hazaar\Application\Route

shutdown

public shutdown(Response $response): void

Returns: void

Parameters

Parameter	Type	Description
$response	Hazaar\Controller\Response

getName

Retrieves the name associated with this instance.

public getName(): string

Returns: string

setStatus

Sets the HTTP status code for the response.

public setStatus(?int $code): void

Returns: void

Parameters

Parameter	Type	Description
$code	int	The HTTP status code to set. If null, the status code will be unset.

getStatus

Retrieves the current HTTP status code.

public getStatus(): int

Returns: int

getBasePath

Retrieves the base path for the current controller.

public getBasePath(): string

Returns: string

setBasePath

Sets the base path for the controller.

public setBasePath(string $path): void

Returns: void

Parameters

Parameter	Type	Description
$path	string	the base path to set

isActive

Test if a URL is active, relative to the application base URL.

public isActive(): bool

Returns: bool

Parameters are simply a list of URL 'parts' that will be combined to test against the current URL to see if it is active. Essentially the argument list is the same as Hazaar\Application::url() except that parameter arrays are not supported.

Unlike Hazaar\Controller::active() this method tests if the path is active relative to the application base path. If you want to test if a particular controller is active, then it has to be the first argument.

• Example

$application->active('mycontroller');

hasHelper

Checks if a helper with the given name exists.

public hasHelper(string $name): bool

Returns: bool

Parameters

Parameter	Type	Description
$name	string	the name of the helper to check

addHelper

Adds a helper instance to the controller.

public addHelper(string $name, mixed $args): ?Helper

Returns: Hazaar\Controller\Interface\Helper

Searches for the helper class in predefined namespaces, allowing application-specific helpers to override built-in ones. Instantiates the helper with the provided arguments and stores it for later use.

Parameters

Parameter	Type	Description
$name	string	the name of the helper to add
$args	mixed

getHelper

Retrieves a helper instance by name.

protected getHelper(string $name): ?Helper

Returns: Hazaar\Controller\Interface\Helper

Converts the provided helper name to lowercase and checks if it exists in the helpers array. If found, returns the existing helper instance. Otherwise, attempts to add and return a new helper instance.

Parameters

Parameter	Type	Description
$name	string	the name of the helper to retrieve

cacheAction

Enable caching for a specific controller action.

protected cacheAction(string $actionName, int $timeout = 60, bool $private): bool

Returns: bool

This method marks an action as cacheable and sets the cache timeout and privacy options. When the action is executed, its response may be cached and reused for subsequent requests.

Parameters

Parameter	Type	Description
$actionName	string	the name of the action to cache
$timeout	int	the cache timeout in seconds (default: 60)
$private	bool	whether the cache should be private (default: false)

middleware

Creates and returns a new Middleware instance with the specified name.

protected middleware(string $name, mixed $args): Handler

Returns: Hazaar\Middleware\Handler

Parameters

Parameter	Type	Description
$name	string	the name of the middleware to instantiate
$args	mixed

runAction

Run an action method on a controller.

protected runAction(string $actionName, array $actionArgs, bool $namedActionArgs): Response

Returns: Hazaar\Controller\Response

This is the main controller action decision code and is where the controller will decide what to actually execute and whether to cache the response on not.

Parameters

Parameter	Type	Description
$actionName	string
$actionArgs	array	The arguments to pass to the action
$namedActionArgs	bool

stream

protected stream(array|string $value): bool

Returns: bool

Parameters

Parameter	Type	Description
$value	array	string

cacheResponse

Cache a response to the current action invocation.

private cacheResponse(Route $route, Response $response): bool

Returns: bool

This method stores the response for the given route in the cache if caching is enabled for the action.

Parameters

Parameter	Type	Description
$route	Hazaar\Application\Route	the route for which the response is being cached
$response	Hazaar\Controller\Response	the response object to cache

getCachedResponse

Retrieve a cached response for the given route, if available.

private getCachedResponse(Route $route): ?Response

Returns: Hazaar\Controller\Response

This method attempts to fetch a cached response from the response cache using the cache key generated from the controller name, action, and arguments. Returns the cached Response object if found, or null otherwise.

Parameters

Parameter	Type	Description
$route	Hazaar\Application\Route	the route for which to retrieve the cached response

getCacheKey

Get the cache key for the current action.

private getCacheKey(string $controller, string $action, ?array $actionArgs, ?string $cacheName): false|string

Returns: false|string

Parameters

Parameter	Type	Description
$controller	string	the controller name
$action	string	the action name
$actionArgs	array	the action arguments
$cacheName	string	the cache name

---

Generated by Hazaar API Doc Generator on Fri, 04 Sep 2026 23:32:16 +0000