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.
See: \Cake\Error\ExceptionRenderer for more information on how to customize exception rendering.
Property Summary
-
$_config protected
array<string, mixed>
Runtime config
-
$_configInitialized protected
bool
Whether the config property has already been configured with defaults
-
$_defaultConfig protected
array<string, mixed>
Options to use for the Error handling.
-
$_handled protected
bool
-
$logger protected
Cake\Error\ErrorLoggerInterface|null
Exception logger instance.
Method Summary
-
__construct() public
Constructor
-
_configDelete() protected
Deletes a single config key.
-
_configRead() protected
Reads a config key.
-
_configWrite() protected
Writes a config key.
-
_displayError() protected
Display an error.
-
_displayException() protected
Displays an exception response body.
-
_logError() protected
Log an error.
-
_logInternalError() protected
Log internal errors.
-
_sendResponse() protected
Method that can be easily stubbed in testing.
-
_stop() protected
Stop the process.
-
configShallow() public
Merge provided config with existing config. Unlike
config()
which does a recursive merge for nested keys, this method does a simple merge. -
getConfig() public
Returns the config.
-
getConfigOrFail() public
Returns the config for this specific key.
-
getLogger() public
Get exception logger.
-
getRenderer() public
Get a renderer instance.
-
handleError() public
Set as the default error handler by CakePHP.
-
handleException() public
Handle uncaught exceptions.
-
handleFatalError() public
Display/Log a fatal error.
-
increaseMemoryLimit() public
Increases the PHP "memory_limit" ini setting by the specified amount in kilobytes
-
logException() public
Log an error for the exception if applicable.
-
mapErrorCode() public static
Map an error code into an Error word, and log location.
-
register() public
Register the error and exception handlers.
-
setConfig() public
Sets the config.
-
wrapAndHandleException() public deprecated
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.
Method Detail
__construct() ¶ public
__construct(array<string, mixed> $config = [])
Constructor
Parameters
-
array<string, mixed>
$config optional The options for error handling.
_configDelete() ¶ protected
_configDelete(string $key): void
Deletes a single config key.
Parameters
-
string
$key Key to delete.
Returns
void
Throws
Cake\Core\Exception\CakeException
if attempting to clobber existing config
_configRead() ¶ protected
_configRead(string|null $key): mixed
Reads a config key.
Parameters
-
string|null
$key Key to read.
Returns
mixed
_configWrite() ¶ protected
_configWrite(array<string, mixed>|string $key, mixed $value, string|bool $merge = false): void
Writes a config key.
Parameters
-
array<string, mixed>|string
$key Key to write to.
-
mixed
$value Value to write.
-
string|bool
$merge optional True to merge recursively, 'shallow' for simple merge, false to overwrite, defaults to false.
Returns
void
Throws
Cake\Core\Exception\CakeException
if attempting to clobber existing config
_displayError() ¶ protected
_displayError(array $error, bool $debug): void
Display an error.
Template method of BaseErrorHandler.
Parameters
-
array
$error An array of error data.
-
bool
$debug Whether the app is in debug mode.
Returns
void
_displayException() ¶ protected
_displayException(Throwable $exception): void
Displays an exception response body.
Subclasses should implement this method to display an uncaught exception as desired for the runtime they operate in.
Parameters
-
Throwable
$exception The exception to display.
Returns
void
Throws
Exception
When the chosen exception renderer is invalid.
_logError() ¶ protected
_logError(string|int $level, array $data): bool
Log an error.
Parameters
-
string|int
$level The level name of the log.
-
array
$data Array of error data.
Returns
bool
_logInternalError() ¶ protected
_logInternalError(Throwable $exception): void
Log internal errors.
Parameters
-
Throwable
$exception Exception.
Returns
void
_sendResponse() ¶ protected
_sendResponse(Psr\Http\Message\ResponseInterface|string $response): void
Method that can be easily stubbed in testing.
Parameters
-
Psr\Http\Message\ResponseInterface|string
$response Either the message or response object.
Returns
void
_stop() ¶ protected
_stop(int $code): void
Stop the process.
Implemented in subclasses that need it.
Parameters
-
int
$code Exit code.
Returns
void
configShallow() ¶ public
configShallow(array<string, mixed>|string $key, mixed|null $value = null): $this
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
-
array<string, mixed>|string
$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|null $key = null, mixed $default = null): mixed
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
getConfigOrFail() ¶ public
getConfigOrFail(string $key): mixed
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
Throws
InvalidArgumentException
getLogger() ¶ public
getLogger(): Cake\Error\ErrorLoggerInterface
Get exception logger.
Returns
Cake\Error\ErrorLoggerInterface
getRenderer() ¶ public
getRenderer(Throwable $exception, Psr\Http\Message\ServerRequestInterface|null $request = null): Cake\Error\ExceptionRendererInterface
Get a renderer instance.
Parameters
-
Throwable
$exception The exception being rendered.
-
Psr\Http\Message\ServerRequestInterface|null
$request optional The request.
Returns
Cake\Error\ExceptionRendererInterface
Throws
RuntimeException
When the renderer class cannot be found.
handleError() ¶ public
handleError(int $code, string $description, string|null $file = null, int|null $line = null, array<string, mixed>|null $context = null): bool
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<string, mixed>|null
$context optional Context
Returns
bool
handleException() ¶ public
handleException(Throwable $exception): void
Handle uncaught exceptions.
Uses a template method provided by subclasses to display errors in an environment appropriate way.
Parameters
-
Throwable
$exception Exception instance.
Returns
void
Throws
Exception
When renderer class not found
See Also
handleFatalError() ¶ public
handleFatalError(int $code, string $description, string $file, int $line): bool
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): void
Increases the PHP "memory_limit" ini setting by the specified amount in kilobytes
Parameters
-
int
$additionalKb Number in kilobytes
Returns
void
logException() ¶ public
logException(Throwable $exception, Psr\Http\Message\ServerRequestInterface|null $request = null): bool
Log an error for the exception if applicable.
Parameters
-
Throwable
$exception The exception to log a message for.
-
Psr\Http\Message\ServerRequestInterface|null
$request optional The current request.
Returns
bool
mapErrorCode() ¶ public static
mapErrorCode(int $code): array
Map an error code into an Error word, and log location.
Parameters
-
int
$code Error code to map
Returns
array
setConfig() ¶ public
setConfig(array<string, mixed>|string $key, mixed|null $value = null, bool $merge = true): $this
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
-
array<string, mixed>|string
$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\CakeException
When trying to set a key that is invalid.
wrapAndHandleException() ¶ public
wrapAndHandleException(Throwable $exception): 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.
Parameters
-
Throwable
$exception The exception to handle
Returns
void
Property Detail
$_configInitialized ¶ protected
Whether the config property has already been configured with defaults
Type
bool