Class ErrorHandler

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.

Namespace: Cake\Error

Properties summary

  • $_config protected
    array

    Runtime config

  • bool

    Whether the config property has already been configured with defaults

  • $_defaultConfig protected
    array

    Options to use for the Error handling.

  • $_handled protected
    bool
  • $logger protected
    \Cake\Error\ErrorLoggerInterface|null

    Exception logger instance.

Method Summary

Method Detail

__construct() public

__construct(array $config)

Constructor

Parameters

array $config optional

The options for error handling.

_configDelete() protected

_configDelete(string $key)

Deletes a single config key.

Parameters

string $key

Key to delete.

Throws

Cake\Core\Exception\Exception
if attempting to clobber existing config

_configRead() protected

_configRead(?string $key)

Reads a config key.

Parameters

string|null $key

Key to read.

Returns

mixed

_configWrite() protected

_configWrite(mixed $key, mixed $value, mixed $merge)

Writes a config key.

Parameters

string|array $key

Key to write to.

mixed $value

Value to write.

bool|string $merge optional

True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.

Throws

Cake\Core\Exception\Exception
if attempting to clobber existing config

_displayError() protected

_displayError(array $error, bool $debug)

Display an error.

Template method of BaseErrorHandler.

Parameters

array $error

An array of error data.

bool $debug

Whether or not the app is in debug mode.

_displayException() protected

_displayException(\Throwable $exception)

Displays an exception response body.

Parameters

\Throwable $exception

The exception to display.

Throws

Exception
When the chosen exception renderer is invalid.

_logError() protected

_logError(mixed $level, array $data)

Log an error.

Parameters

int|string $level

The level name of the log.

array $data

Array of error data.

Returns

bool

_logInternalError() protected

_logInternalError(\Throwable $exception)

Log internal errors.

Parameters

\Throwable $exception

Exception.

_sendResponse() protected

_sendResponse(mixed $response)

Method that can be easily stubbed in testing.

Parameters

string|\Cake\Http\Response $response

Either the message or response object.

_stop() protected

_stop(int $code)

Stop the process.

Implemented in subclasses that need it.

Parameters

int $code

Exit code.

configShallow() public

configShallow(mixed $key, mixed $value)

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

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

string|array $key

The key to set, or a complete array of configs.

mixed|null $value optional

The value to set.

Returns

$this

getConfig() public

getConfig(?string $key, mixed $default)

Returns the config.

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

string|null $key optional

The key to get or null for the whole config.

mixed $default optional

The return value when the key does not exist.

Returns

mixed

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

getConfigOrFail() public

getConfigOrFail(string $key)

Returns the config for this specific key.

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

Parameters

string $key

The key to get.

Returns

mixed

Configuration data at the named key

Throws

InvalidArgumentException

getLogger() public

getLogger()

Get exception logger.

Returns

\Cake\Error\ErrorLoggerInterface

getRenderer() public

getRenderer(\Throwable $exception, ?\Psr\Http\Message\ServerRequestInterface $request)

Get a renderer instance.

Parameters

\Throwable $exception

The exception being rendered.

\Psr\Http\Message\ServerRequestInterface|null $request optional

The request.

Returns

\Cake\Error\ExceptionRendererInterface

The exception renderer.

Throws

RuntimeException
When the renderer class cannot be found.

handleError() public

handleError(int $code, string $description, ?string $file, ?int $line, ?array $context)

Set as the default error handler by CakePHP.

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

int $code

Code of error

string $description

Error description

string|null $file optional

File on which error occurred

int|null $line optional

Line that triggered the error

array|null $context optional

Context

Returns

bool

True if error was handled

handleException() public

handleException(\Throwable $exception)

Handle uncaught exceptions.

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

Parameters

\Throwable $exception

Exception instance.

Throws

Exception
When renderer class not found

See Also

https://secure.php.net/manual/en/function.set-exception-handler.php

handleFatalError() public

handleFatalError(int $code, string $description, string $file, int $line)

Display/Log a fatal error.

Parameters

int $code

Code of error

string $description

Error description

string $file

File on which error occurred

int $line

Line that triggered the error

Returns

bool

increaseMemoryLimit() public

increaseMemoryLimit(int $additionalKb)

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

Parameters

int $additionalKb

Number in kilobytes

logException() public

logException(\Throwable $exception, ?\Psr\Http\Message\ServerRequestInterface $request)

Log an error for the exception if applicable.

Parameters

\Throwable $exception

The exception to log a message for.

\Psr\Http\Message\ServerRequestInterface $request optional

The current request.

Returns

bool

mapErrorCode() public static

mapErrorCode(int $code)

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

Parameters

int $code

Error code to map

Returns

array

Array of error word, and log location.

register() public

register()

Register the error and exception handlers.

setConfig() public

setConfig(mixed $key, mixed $value, mixed $merge)

Sets the config.

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

string|array $key

The key to set, or a complete array of configs.

mixed|null $value optional

The value to set.

bool $merge optional

Whether to recursively merge or overwrite existing config, defaults to true.

Returns

$this

Throws

Cake\Core\Exception\Exception
When trying to set a key that is invalid.

wrapAndHandleException() public

wrapAndHandleException(\Throwable $exception)

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.

Parameters

\Throwable $exception

The exception to handle

Property Detail

$_config protected

Runtime config

Type

array

$_configInitialized protected

Whether the config property has already been configured with defaults

Type

bool

$_defaultConfig protected

Options to use for the Error handling.

Type

array

$_handled protected

Type

bool

$logger protected

Exception logger instance.

Type

\Cake\Error\ErrorLoggerInterface|null

© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.1/class-Cake.Error.ErrorHandler.html