Fr3nch13/CakePHP Utilities

ErrorHandler extends BaseErrorHandler
in package

Application

Error Handler provides basic error and exception handling for your application. It captures and handles all unhandled exceptions and errors. Displays helpful framework errors when debug mode is on.

Uncaught exceptions

When debug mode is off a ExceptionRenderer will render 404 or 500 errors. If an uncaught exception is thrown and it is a type that ExceptionRenderer does not know about it will be treated as a 500 error.

Implementing application specific exception handling

You can implement application specific exception handling in one of a few ways. Each approach gives you different amounts of control over the exception handling process.

Modify config/error.php and setup custom exception handling.
Use the exceptionRenderer option to inject an Exception renderer. This will let you keep the existing handling logic but override the rendering logic.

Create your own Exception handler

This gives you full control over the exception handling process. The class you choose should be loaded in your config/error.php and registered as the default exception handler.

Using a custom renderer with `exceptionRenderer`

If you don't want to take control of the exception handling, but want to change how exceptions are rendered you can use exceptionRenderer option to choose a class to render exception pages. By default Cake\Error\ExceptionRenderer is used. Your custom exception renderer class should be placed in src/Error.

Your custom renderer should expect an exception in its constructor, and implement a render method. Failing to do so will cause additional errors.

Logging exceptions

Using the built-in exception handling, you can log all the exceptions that are dealt with by ErrorHandler by setting log option to true in your config/error.php. Enabling this will log every exception to Log and the configured loggers.

PHP errors

Error handler also provides the built in features for handling php errors (trigger_error). While in debug mode, errors will be output to the screen using debugger. While in production mode, errors will be logged to Log. You can control which errors are logged by setting errorLevel option in config/error.php.

Logging errors

When ErrorHandler is used for handling errors, you can enable error logging by setting the log option to true. This will log all errors to the configured log handlers.

Controlling what errors are logged/displayed

You can control which errors are logged / displayed by ErrorHandler by setting errorLevel. Setting this to one or a combination of a few of the E_* constants will only enable the specified errors:

$options['errorLevel'] = E_ALL & ~E_NOTICE;

Would enable handling for all non Notice errors.

Properties

$_config : array<string, mixed>: Runtime config
$_configInitialized : bool: Whether the config property has already been configured with defaults
$_defaultConfig : array<string, mixed>: Options to use for the Error handling.
$_handled : bool
$logger : ErrorLoggerInterface|null: Exception logger instance.

Methods

__construct() : mixed: Constructor
configShallow() : $this: Merge provided config with existing config. Unlike `config()` which does a recursive merge for nested keys, this method does a simple merge.
getConfig() : mixed: Returns the config.
getConfigOrFail() : mixed: Returns the config for this specific key.
getLogger() : ErrorLoggerInterface: Get exception logger.
getRenderer() : ExceptionRendererInterface: Get a renderer instance.
handleError() : bool: Set as the default error handler by CakePHP.
handleException() : void: Handle uncaught exceptions.
handleFatalError() : bool: Display/Log a fatal error.
increaseMemoryLimit() : void: Increases the PHP "memory_limit" ini setting by the specified amount in kilobytes
logException() : bool: Log an error for the exception if applicable.
mapErrorCode() : array<string|int, mixed>: Map an error code into an Error word, and log location.
register() : void: Register the error and exception handlers.
setConfig() : $this: Sets the config.
wrapAndHandleException() : void: Checks the passed exception type. If it is an instance of `Error` then, it wraps the passed object inside another Exception object for backwards compatibility purposes.
_configDelete() : void: Deletes a single config key.
_configRead() : mixed: Reads a config key.
_configWrite() : void: Writes a config key.
_displayError() : void: Display an error.
_displayException() : void: Displays an exception response body.
_logError() : bool: Log an error.
_logInternalError() : void: Log internal errors.
_sendResponse() : void: Method that can be easily stubbed in testing.
_stop() : void: Stop the process.

$_config

Runtime config


    protected
        array<string, mixed>
    $_config
     = []

$_configInitialized

Whether the config property has already been configured with defaults


    protected
        bool
    $_configInitialized
     = false

$_defaultConfig

Options to use for the Error handling.


    protected
        array<string, mixed>
    $_defaultConfig
     = ['log' => true, 'trace' => false, 'skipLog' => [], 'errorLogger' => \Cake\Error\ErrorLogger::class]

$_handled


    protected
        bool
    $_handled
     = false

$logger

Exception logger instance.


    protected
        ErrorLoggerInterface|null
    $logger

__construct()

Constructor


    public
                    __construct([array<string, mixed> $config = [] ]) : mixed

Parameters

$config : array<string, mixed> = []: The options for error handling.

configShallow()

Merge provided config with existing config. Unlike `config()` which does a recursive merge for nested keys, this method does a simple merge.


    public
                    configShallow(array<string, mixed>|string $key[, mixed|null $value = null ]) : $this

Setting a specific value:

$this->configShallow('key', $value);

Setting a nested value:

$this->configShallow('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->configShallow(['one' => 'value', 'another' => 'value']);

Parameters

$key : array<string, mixed>|string: The key to set, or a complete array of configs.
$value : mixed|null = null: The value to set.

Return values

$this

getConfig()

Returns the config.


    public
                    getConfig([string|null $key = null ][, mixed $default = null ]) : mixed

Usage

Reading the whole config:

$this->getConfig();

Reading a specific value:

$this->getConfig('key');

Reading a nested value:

$this->getConfig('some.nested.key');

Reading with default value:

$this->getConfig('some-key', 'default-value');

Parameters

$key : string|null = null: The key to get or null for the whole config.
$default : mixed = null: The return value when the key does not exist.

Return values

mixed —

Configuration data at the named key or null if the key does not exist.

getConfigOrFail()

Returns the config for this specific key.


    public
                    getConfigOrFail(string $key) : mixed

The config value for this key must exist, it can never be null.

Parameters

$key : string: The key to get.

Return values

mixed —

Configuration data at the named key

getLogger()

Get exception logger.


    public
                    getLogger() : ErrorLoggerInterface

Return values

ErrorLoggerInterface

getRenderer()

Get a renderer instance.


    public
                    getRenderer(Throwable $exception[, ServerRequestInterface|null $request = null ]) : ExceptionRendererInterface

Parameters

$exception : Throwable: The exception being rendered.
$request : ServerRequestInterface|null = null: The request.

Return values

ExceptionRendererInterface —

The exception renderer.

handleError()

Set as the default error handler by CakePHP.


    public
                    handleError(int $code, string $description[, string|null $file = null ][, int|null $line = null ][, array<string, mixed>|null $context = null ]) : bool

Use config/error.php to customize or replace this error handler. This function will use Debugger to display errors when debug mode is on. And will log errors to Log, when debug mode is off.

You can use the 'errorLevel' option to set what type of errors will be handled. Stack traces for errors can be enabled with the 'trace' option.

Parameters

$code : int: Code of error
$description : string: Error description
$file : string|null = null: File on which error occurred
$line : int|null = null: Line that triggered the error
$context : array<string, mixed>|null = null: Context

Return values

bool —

True if error was handled

handleException()

Handle uncaught exceptions.


    public
                    handleException(Throwable $exception) : void

Uses a template method provided by subclasses to display errors in an environment appropriate way.

Parameters

$exception : Throwable: Exception instance.

handleFatalError()

Display/Log a fatal error.


    public
                    handleFatalError(int $code, string $description, string $file, int $line) : bool

Parameters

$code : int: Code of error
$description : string: Error description
$file : string: File on which error occurred
$line : int: Line that triggered the error

Return values

bool

increaseMemoryLimit()

Increases the PHP "memory_limit" ini setting by the specified amount in kilobytes


    public
                    increaseMemoryLimit(int $additionalKb) : void

Parameters

$additionalKb : int: Number in kilobytes

logException()

Log an error for the exception if applicable.


    public
                    logException(Throwable $exception[, ServerRequestInterface|null $request = null ]) : bool

Parameters

$exception : Throwable: The exception to log a message for.
$request : ServerRequestInterface|null = null: The current request.

Return values

bool

mapErrorCode()

Map an error code into an Error word, and log location.


    public
            static        mapErrorCode(int $code) : array<string|int, mixed>

Parameters

$code : int: Error code to map

Return values

array<string|int, mixed> —

Array of error word, and log location.

register()


    public
                    register() : void

setConfig()

Sets the config.


    public
                    setConfig(array<string, mixed>|string $key[, mixed|null $value = null ][, bool $merge = true ]) : $this

Usage

Setting a specific value:

$this->setConfig('key', $value);

Setting a nested value:

$this->setConfig('some.nested.key', $value);

Updating multiple config settings at the same time:

$this->setConfig(['one' => 'value', 'another' => 'value']);

Parameters

$key : array<string, mixed>|string: The key to set, or a complete array of configs.
$value : mixed|null = null: The value to set.
$merge : bool = true: Whether to recursively merge or overwrite existing config, defaults to true.

Return values

$this

wrapAndHandleException()

Checks the passed exception type. If it is an instance of `Error` then, it wraps the passed object inside another Exception object for backwards compatibility purposes.


    public
                    wrapAndHandleException(Throwable $exception) : void

Unused method will be removed in 5.0

Parameters

$exception : Throwable: The exception to handle

_configDelete()

Deletes a single config key.


    protected
                    _configDelete(string $key) : void

Parameters

$key : string: Key to delete.

_configRead()

Reads a config key.


    protected
                    _configRead(string|null $key) : mixed

Parameters

$key : string|null: Key to read.

_configWrite()

Writes a config key.


    protected
                    _configWrite(array<string, mixed>|string $key, mixed $value[, string|bool $merge = false ]) : void

Parameters

$key : array<string, mixed>|string: Key to write to.
$value : mixed: Value to write.
$merge : string|bool = false: True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.

_displayError()

Display an error.


    protected
                    _displayError(array<string|int, mixed> $error, bool $debug) : void

Template method of BaseErrorHandler.

Parameters

$error : array<string|int, mixed>: An array of error data.
$debug : bool: Whether the app is in debug mode.

_displayException()

Displays an exception response body.


    protected
                    _displayException(Throwable $exception) : void

Parameters

$exception : Throwable: The exception to display.

_logError()

Log an error.


    protected
                    _logError(string|int $level, array<string|int, mixed> $data) : bool

Parameters

$level : string|int: The level name of the log.
$data : array<string|int, mixed>: Array of error data.

Return values

bool

_logInternalError()

Log internal errors.


    protected
                    _logInternalError(Throwable $exception) : void

Parameters

$exception : Throwable: Exception.

_sendResponse()

Method that can be easily stubbed in testing.


    protected
                    _sendResponse(ResponseInterface|string $response) : void

Parameters

$response : ResponseInterface|string: Either the message or response object.

_stop()

Stop the process.


    protected
                    _stop(int $code) : void

Implemented in subclasses that need it.

Parameters

$code : int: Exit code.

ErrorHandler extends BaseErrorHandler in package Application

Uncaught exceptions

Implementing application specific exception handling

Create your own Exception handler

Using a custom renderer with exceptionRenderer

Logging exceptions

PHP errors

Logging errors

Controlling what errors are logged/displayed

Tags

Table of Contents

Properties

Methods

Properties

$_config

$_configInitialized

$_defaultConfig

$_handled

$logger

Methods

__construct()

Parameters

configShallow()

Parameters

Return values

getConfig()

Usage

Parameters

Return values

getConfigOrFail()

Parameters

Tags

Return values

getLogger()

Return values

getRenderer()

Parameters

Tags

Return values

handleError()

Parameters

Return values

handleException()

Parameters

Tags

handleFatalError()

Parameters

Return values

increaseMemoryLimit()

Parameters

logException()

Parameters

Return values

mapErrorCode()

Parameters

Return values

register()

setConfig()

Usage

Parameters

Tags

Return values

wrapAndHandleException()

Parameters

_configDelete()

Parameters

Tags

_configRead()

Parameters

_configWrite()

Parameters

Tags

_displayError()

Parameters

_displayException()

Parameters

Tags

_logError()

Parameters

Return values

ErrorHandler extends BaseErrorHandler
in package

Application

Using a custom renderer with `exceptionRenderer`