Application

About 6 min

Application

The Application.

The main application class is the core of Hazaar and serves as the entry point to your application. It is responsible for routing actions to controllers based on an HTTP request. (CLI requests are handled by Hazaar\Console\Application.)

The Application will manage access to a Hazaar\Application\Request object that can be used to obtain information about the request. This request can be either a GET or POST request.

POST requests can optionally have a request body. In this case the Content-Type header will be checked to see how to decode the request body. multipart/form-data and application/json are currently accepted.

Example entry point usage:

$application = new Hazaar\Application();
$application->bootstrap()->run();

Constants

VERSION

public const VERSION = 'HAZAAR_VERSION'

Properties

config

public Config $config

loader

public Loader $loader

router

public Router $router

environment

public string $environment

path

public string $path

base

public string $base

timer

public Timer $timer

instance

private Application $instance

root

private string $root

runtime

private Runtime $runtime

eventDispatcher

private EventDispatcher $eventDispatcher

middlewareDispatcher

private Dispatcher $middlewareDispatcher

Methods

__construct

The main application constructor.

public __construct(string $env, ?string $path): void

The application is basically the center of the Hazaar universe. Everything hangs off of it and controllers are executed within the context of the application. The main constructor prepares the application to begin processing and is the first bit of code executed within the Hazaar environment.

The constructor is responsible for setting up the class loader, starting code execution profiling timers, loading the application configuration and setting up the router.

Parameters

Parameter	Type	Description
`$env`	`string`	The application environment name. eg: 'development' or 'production'
`$path`	`string`	The path to the application directory. If null it will be auto-detected.

shutdown

Shuts down the application, performing cleanup and metrics recording.

public shutdown(): void

If the application configuration is not set, the method returns immediately.
Attempts to include a shutdown script if it exists, as specified in the configuration (app.files.shutdown), defaulting to 'shutdown.php'.
If application metrics are enabled (app.metrics), it initializes or updates a metrics file:
- Creates a new Metric instance if the metrics file does not exist, adding data sources and archives for tracking hits, execution time, and memory usage over various time periods.
- Sets the current values for hits, execution time (in milliseconds since application start), and peak memory usage.

getConfigOverridePaths

Returns an array of configuration override paths based on the current server environment.

public getConfigOverridePaths(): void

The paths are determined by server name, HTTP host, and a local override. If the script is running from the command line interface (CLI), an additional 'cli' path is appended.

getDefaultConfig

Returns the default configuration array for the application.

public getDefaultConfig(): void

This method constructs a default configuration array containing settings for the application, error handling, routing, and various path mappings. It also determines the application's base URL based on the current server environment.

configure

Configures the application using the provided configuration object.

public configure(): void

This method sets up various application parameters, including response type, URL aliases, root directory, PHP ini settings, load average protection, loader search paths, and initialises configured modules.

getInstance

Get the current application instance.

public getInstance(): ?Application

This static function can be used to get a reference to the current application instance from anywhere.

setRoot

Sets the root directory path for the application.

public setRoot(string $value): void

This method normalizes the given path by replacing backslashes with forward slashes, trimming any trailing slashes, and ensuring a single trailing slash at the end.

Parameters

Parameter	Type	Description
`$value`	`string`	the path to set as the application root directory

getRoot

Retrieves the root directory of the application.

public getRoot(): string

getRuntimePath

Returns the application runtime directory.

public getRuntimePath(): string

The runtime directory is a place where Hazaar will keep files that it needs to create during normal operation. For example, socket files for background scheduler communication, cached views, and backend applications.

getFilePath

Return the requested path in the current application.

public getFilePath(?string $path, bool $forceRealpath = true): string

This method allows access to the raw URL path part, relative to the current application request.

Parameters

Parameter	Type	Description
`$path`	`string`	path suffix to append to the application path
`$forceRealpath`	`bool`	Return the real path to a file. If the file does not exist, this will return false.

getRequestedController

Get the currently requested controller name.

public getRequestedController(): string

getAppPath

Get the real path to the application on the local filesystem resolving links.

public getAppPath(NULL $suffix): string

Parameters

Parameter	Type	Description
`$suffix`	`NULL`	application path suffix

getBasePath

Get the base path.

public getBasePath(NULL $suffix): string

The base path is the root your application which contains the application, library and public directories

Parameters

Parameter	Type	Description
`$suffix`	`NULL`	application base path suffix

bootstrap

Initialise the application ready for execution.

public bootstrap(): Application

Bootstrap is the first step in running an application. The process will set up error handling, register the configure locale and timezone, initialise the Hazaar\Application\Router and load any predefined routes (see: Routing).

Lastly it will then execute the application bootstrap.php script within the context of the application. Once that step succeeds the requested (or the default) controller will be loaded and initialised so that it is ready for execution by the application.

run

Executes the application.

public run(?Controller $controller): int

Once the application has been bootstrapped it is ready to run. A Hazaar\Controller object can be passed as an argument or if omited the Hazaar\Application\Router will be used to evaluate the Hazaar\Application\Request to determine the controller to load and execute.

The requested controller will be executed and the application will check that it returns a valid Hazaar\Controller\Response object. If a valid response is not returned an exception will be raised.

Once a valid response object is returned it will be used to write output back to the web server to be returned to the user.

This method also has protection against error loops. If an exception is thrown while processing a Hazaar\Controller\Error controller object then a new exception will be thrown outside the application context and will display basic fall-back error output.

Parameters

Parameter	Type	Description
`$controller`	`Controller`

getControllerResponse

Handles the incoming HTTP request and returns a Response object.

public getControllerResponse(Request $request): Response

If a Controller instance is provided, it initializes and runs the controller to generate the response. Otherwise, it uses the router to handle the request, passing it through the middleware dispatcher.

Parameters

Parameter	Type	Description
`$request`	`Request`	the HTTP request to handle

getPath

Return the requested path in the current application.

public getPath(?string $path): string

This method allows access to the raw URL path part, relative to the current application request.

Parameters

Parameter	Type	Description
`$path`	`string`

getURL

Generate a URL relative to the application.

public getURL(): URL

This is the base method for generating URLs in your application. URLs generated directly from here are relative to the application base path. For URLs that are relative to the current controller see Controller::url()

Parameters are dynamic and depend on what you are trying to generate.

For examples see: Generating URLs

getVersion

Return the current Hazaar framework version.

public getVersion(): string

addMiddleware

Adds a middleware to the middleware dispatcher.

public addMiddleware(Middleware $middleware): void

Parameters

Parameter	Type	Description
`$middleware`	`Middleware`	the middleware instance to add

shutdownHandler

Handles application shutdown by checking for the last occurred error.

public shutdownHandler(): void

If a fatal error is detected, it cleans the output buffer (if necessary) and delegates error handling to the Shutdown::exitWithError method. This ensures that fatal errors are properly managed and displayed according to the application's error handling configuration.

errorHandler

Custom error handler function.

public errorHandler(int $errno, string $errstr, ?string $errfile, ?int $errline): bool

This function is responsible for handling PHP errors and displaying appropriate error messages.

Parameters

Parameter	Type	Description
`$errno`	`int`	the error number
`$errstr`	`string`	the error message
`$errfile`	`string`	the file where the error occurred
`$errline`	`int`	the line number where the error occurred

exceptionHandler

Exception handler function.

public exceptionHandler(\Throwable $e): void

This function is responsible for handling exceptions thrown in the application. If the exception code is greater than or equal to 500, it logs the error message along with the code, line number, and file name. Then it calls the exitWithError() function to handle the error further.

Parameters

Parameter	Type	Description
`$e`	`\Throwable`

getBase

Retrieves the base path or URL of the application.

public getBase(): string

findAppPath

Attempts to locate the application path by searching for an 'app' directory

public findAppPath(?string $searchPath): ?string

containing a 'configs' subdirectory, starting from the provided search path or the current working directory. The search ascends up to 16 directory levels. If the 'APPLICATION_PATH' environment variable is set, its value is used.

Parameters

Parameter	Type	Description
`$searchPath`	`string`	Optional starting directory for the search. Defaults to current working directory.

updateMetrics

public updateMetrics(MetricsEvent $event): void

Parameters

Parameter	Type	Description
`$event`	`MetricsEvent`

getRuntimeNotices

Returns an array of parsed runtime notices from the output buffer.

public getRuntimeNotices(): void

initializeModules

Initialise any configured modules.

private initializeModules(): void

These modules may setup things to run in the background or make certain functions availble and this is where we can start them up if they have valid configuration.

Generated by Hazaar API Doc Generator on Sun, 01 Mar 2026 09:22:26 +0000