Class ExceptionTrap
Entry point to CakePHP's exception handling.
Using the register() method you can attach an ExceptionTrap to PHP's default exception handler and register
a shutdown handler to handle fatal errors.
When exceptions are trapped the Exception.beforeRender event is triggered.
Then exceptions are logged (if enabled) and finally 'rendered' using the defined renderer.
Stopping the Exception.beforeRender event has no effect, as we always need to render
a response to an exception and custom renderers should be used if you want to replace or
skip rendering an exception.
If undefined, an ExceptionRenderer will be selected based on the current SAPI (CLI or Web).
Property Summary
-
$_config protected
array<string, mixed>Runtime config
-
$_configInitialized protected
boolWhether the config property has already been configured with defaults
-
$_defaultConfig protected
array<string, mixed>Configuration options. Generally these will be defined in your config/app.php
-
$_eventClass protected
stringDefault class name for new event objects.
-
$_eventManager protected
Cake\Event\EventManagerInterface|nullInstance of the Cake\Event\EventManager this object is using to dispatch inner events.
-
$callbacks protected
array<Closure>A list of handling callbacks.
-
$disabled protected
boolTrack if this trap was removed from the global handler.
-
$registeredTrap protected static
Cake\Error\ExceptionTrap|nullThe currently registered global exception handler
Method Summary
-
__construct() public
Constructor
-
_configDelete() protected
Deletes a single config key.
-
_configRead() protected
Reads a config key.
-
_configWrite() protected
Writes a config key.
-
chooseRenderer() protected
Choose an exception renderer based on config or the SAPI
-
configShallow() public
Merge provided config with existing config. Unlike
config()which does a recursive merge for nested keys, this method does a simple merge. -
dispatchEvent() public
Wrapper for creating and dispatching events.
-
getConfig() public
Returns the config.
-
getConfigOrFail() public
Returns the config for this specific key.
-
getEventManager() public
Returns the Cake\Event\EventManager manager instance for this object.
-
handleException() public
Handle uncaught exceptions.
-
handleFatalError() public
Display/Log a fatal error.
-
handleShutdown() public
Shutdown handler
-
increaseMemoryLimit() public
Increases the PHP "memory_limit" ini setting by the specified amount in kilobytes
-
instance() public static
Get the registered global instance if set.
-
logException() public
Log an exception.
-
logInternalError() public
Trigger an error that occurred during rendering an exception.
-
logger() public
Get an instance of the logger.
-
register() public
Attach this ExceptionTrap to PHP's default exception handler.
-
renderer() public
Get an instance of the renderer.
-
setConfig() public
Sets the config.
-
setEventManager() public
Returns the Cake\Event\EventManagerInterface instance for this object.
-
unregister() public
Remove this instance from the singleton
Method Detail
__construct() ¶ public
__construct(array<string, mixed> $options = [])Constructor
Parameters
-
array<string, mixed>$options optional An options array. See $_defaultConfig.
_configDelete() ¶ protected
_configDelete(string $key): voidDeletes a single config key.
Parameters
-
string$key Key to delete.
Returns
voidThrows
Cake\Core\Exception\CakeExceptionif attempting to clobber existing config
_configRead() ¶ protected
_configRead(string|null $key): mixedReads 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): voidWrites 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
voidThrows
Cake\Core\Exception\CakeExceptionif attempting to clobber existing config
chooseRenderer() ¶ protected
chooseRenderer(): class-string<Cake\Error\ExceptionRendererInterface>Choose an exception renderer based on config or the SAPI
Returns
class-string<Cake\Error\ExceptionRendererInterface>configShallow() ¶ public
configShallow(array<string, mixed>|string $key, mixed|null $value = null): $thisMerge 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
$thisdispatchEvent() ¶ public
dispatchEvent(string $name, array $data = [], TSubject|null $subject = null): Cake\Event\EventInterface<TSubject>Wrapper for creating and dispatching events.
Returns a dispatched event.
Parameters
-
string$name Name of the event.
-
array$data optional Any value you wish to be transported with this event to it can be read by listeners.
-
TSubject|null$subject optional The object that this event applies to ($this by default).
Returns
Cake\Event\EventInterface<TSubject>getConfig() ¶ public
getConfig(string|null $key = null, mixed $default = null): mixedReturns 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
mixedConfiguration data at the named key or null if the key does not exist.
getConfigOrFail() ¶ public
getConfigOrFail(string $key): mixedReturns 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
mixedConfiguration data at the named key
Throws
InvalidArgumentExceptiongetEventManager() ¶ public
getEventManager(): Cake\Event\EventManagerInterfaceReturns the Cake\Event\EventManager manager instance for this object.
You can use this instance to register any new listeners or callbacks to the object events, or create your own events and trigger them at will.
Returns
Cake\Event\EventManagerInterfacehandleException() ¶ public
handleException(Throwable $exception): voidHandle uncaught exceptions.
Uses a template method provided by subclasses to display errors in an environment appropriate way.
Parameters
-
Throwable$exception Exception instance.
Returns
voidThrows
ExceptionWhen renderer class not found
See Also
handleFatalError() ¶ public
handleFatalError(int $code, string $description, string $file, int $line): voidDisplay/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
voidhandleShutdown() ¶ public
handleShutdown(): voidShutdown handler
Convert fatal errors into exceptions that we can render.
Returns
voidincreaseMemoryLimit() ¶ public
increaseMemoryLimit(int $additionalKb): voidIncreases the PHP "memory_limit" ini setting by the specified amount in kilobytes
Parameters
-
int$additionalKb Number in kilobytes
Returns
voidinstance() ¶ public static
instance(): Cake\Error\ExceptionTrap|nullGet the registered global instance if set.
Keep in mind that the global state contained here is mutable and the object returned by this method could be a stale value.
Returns
Cake\Error\ExceptionTrap|nullThe global instance or null.
logException() ¶ public
logException(Throwable $exception, Psr\Http\Message\ServerRequestInterface|null $request = null): voidLog an exception.
Primarily a public function to ensure consistency between global exception handling
and the ErrorHandlerMiddleware. This method will apply the skipLog filter
skipping logging if the exception should not be logged.
After logging is attempted the Exception.beforeRender event is triggered.
Parameters
-
Throwable$exception The exception to log
-
Psr\Http\Message\ServerRequestInterface|null$request optional The optional request
Returns
voidlogInternalError() ¶ public
logInternalError(Throwable $exception): voidTrigger an error that occurred during rendering an exception.
By triggering an E_USER_WARNING we can end up in the default exception handling which will log the rendering failure, and hopefully render an error page.
Parameters
-
Throwable$exception Exception to log
Returns
voidlogger() ¶ public
logger(): Cake\Error\ErrorLoggerInterfaceGet an instance of the logger.
Returns
Cake\Error\ErrorLoggerInterfaceregister() ¶ public
register(): voidAttach this ExceptionTrap to PHP's default exception handler.
This will replace the existing exception handler, and the previous exception handler will be discarded.
Returns
voidrenderer() ¶ public
renderer(Throwable $exception, Psr\Http\Message\ServerRequestInterface|null $request = null): Cake\Error\ExceptionRendererInterfaceGet an instance of the renderer.
Parameters
-
Throwable$exception Exception to render
-
Psr\Http\Message\ServerRequestInterface|null$request optional The request if possible.
Returns
Cake\Error\ExceptionRendererInterfacesetConfig() ¶ public
setConfig(array<string, mixed>|string $key, mixed|null $value = null, bool $merge = true): $thisSets 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
$thisThrows
Cake\Core\Exception\CakeExceptionWhen trying to set a key that is invalid.
setEventManager() ¶ public
setEventManager(Cake\Event\EventManagerInterface $eventManager): $thisReturns the Cake\Event\EventManagerInterface instance for this object.
You can use this instance to register any new listeners or callbacks to the object events, or create your own events and trigger them at will.
Parameters
-
Cake\Event\EventManagerInterface$eventManager the eventManager to set
Returns
$thisunregister() ¶ public
unregister(): voidRemove this instance from the singleton
If this instance is not currently the registered singleton nothing happens.
Returns
voidProperty Detail
$_configInitialized ¶ protected
Whether the config property has already been configured with defaults
Type
bool$_defaultConfig ¶ protected
Configuration options. Generally these will be defined in your config/app.php
exceptionRenderer- string - The class responsible for rendering uncaught exceptions. The chosen class will be used for for both CLI and web environments. If you want different classes used in CLI and web environments you'll need to write that conditional logic as well. The conventional location for custom renderers is insrc/Error. Your exception renderer needs to implement therender()method and return either a string or Http\Response.logSet to false to disable logging.logger- string - The class name of the error logger to use.trace- boolean - Whether backtraces should be included in logged exceptions.skipLog- array - List of exceptions to skip for logging. Exceptions that extend one of the listed exceptions will also not be logged. E.g.:'skipLog' => ['Cake\Http\Exception\NotFoundException', 'Cake\Http\Exception\UnauthorizedException']This option is forwarded to the configured
loggerextraFatalErrorMemory- int - The number of megabytes to increase the memory limit by when a fatal error is encountered. This allows breathing room to complete logging or error handling.stderrUsed in console environments so that renderers have access to the current console output stream.
Type
array<string, mixed>$_eventManager ¶ protected
Instance of the Cake\Event\EventManager this object is using to dispatch inner events.
Type
Cake\Event\EventManagerInterface|null$callbacks ¶ protected
A list of handling callbacks.
Callbacks are invoked for each error that is handled. Callbacks are invoked in the order they are attached.
Type
array<Closure>$registeredTrap ¶ protected static
The currently registered global exception handler
This is best effort as we can't know if/when another exception handler is registered.
Type
Cake\Error\ExceptionTrap|null