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).
array<string, mixed>
Runtime config
bool
Whether the config property has already been configured with defaults
array<string, mixed>
Configuration options. Generally these will be defined in your config/app.php
string
Default class name for new event objects.
Cake\Event\EventManagerInterface|null
Instance of the Cake\Event\EventManager this object is using to dispatch inner events.
arrayClosure>
A list of handling callbacks.
bool
Track if this trap was removed from the global handler.
Cake\Error\ExceptionTrap|null
The currently registered global exception handler
Constructor
Deletes a single config key.
Reads a config key.
Writes a config key.
Choose an exception renderer based on config or the SAPI
Merge provided config with existing config. Unlike config()
which does a recursive merge for nested keys, this method does a simple merge.
Wrapper for creating and dispatching events.
Returns the config.
Returns the config for this specific key.
Returns the Cake\Event\EventManager manager instance for this object.
Handle uncaught exceptions.
Display/Log a fatal error.
Shutdown handler
Increases the PHP "memory_limit" ini setting by the specified amount in kilobytes
Get the registered global instance if set.
Log an exception.
Trigger an error that occurred during rendering an exception.
Get an instance of the logger.
Attach this ExceptionTrap to PHP's default exception handler.
Get an instance of the renderer.
Sets the config.
Returns the Cake\Event\EventManagerInterface instance for this object.
Remove this instance from the singleton
__construct(array<string, mixed> $options = [])
Constructor
array<string, mixed>
$options optional An options array. See $_defaultConfig.
_configDelete(string $key): void
Deletes a single config key.
string
$key Key to delete.
void
Cake\Core\Exception\CakeException
_configRead(string|null $key): mixed
Reads a config key.
string|null
$key Key to read.
mixed
_configWrite(array<string, mixed>|string $key, mixed $value, string|bool $merge = false): void
Writes a config key.
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.
void
Cake\Core\Exception\CakeException
chooseRenderer(): class-stringCake\Error\ExceptionRendererInterface>
Choose an exception renderer based on config or the SAPI
class-stringCake\Error\ExceptionRendererInterface>
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']);
array<string, mixed>|string
$key The key to set, or a complete array of configs.
mixed|null
$value optional The value to set.
$this
dispatchEvent(string $name, array|null $data = null, object|null $subject = null): Cake\Event\EventInterface
Wrapper for creating and dispatching events.
Returns a dispatched event.
string
$name Name of the event.
array|null
$data optional Any value you wish to be transported with this event to it can be read by listeners.
object|null
$subject optional The object that this event applies to ($this by default).
Cake\Event\EventInterface
getConfig(string|null $key = null, mixed $default = null): mixed
Returns the config.
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');
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.
mixed
getConfigOrFail(string $key): mixed
Returns the config for this specific key.
The config value for this key must exist, it can never be null.
string
$key The key to get.
mixed
InvalidArgumentException
getEventManager(): Cake\Event\EventManagerInterface
Returns 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.
Cake\Event\EventManagerInterface
handleException(Throwable $exception): void
Handle uncaught exceptions.
Uses a template method provided by subclasses to display errors in an environment appropriate way.
Throwable
$exception Exception instance.
void
Exception
handleFatalError(int $code, string $description, string $file, int $line): void
Display/Log a fatal error.
int
$code Code of error
string
$description Error description
string
$file File on which error occurred
int
$line Line that triggered the error
void
handleShutdown(): void
Shutdown handler
Convert fatal errors into exceptions that we can render.
void
increaseMemoryLimit(int $additionalKb): void
Increases the PHP "memory_limit" ini setting by the specified amount in kilobytes
int
$additionalKb Number in kilobytes
void
instance(): Cake\Error\ExceptionTrap|null
Get 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.
Cake\Error\ExceptionTrap|null
logException(Throwable $exception, Psr\Http\Message\ServerRequestInterface|null $request = null): void
Log 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.
Throwable
$exception The exception to log
Psr\Http\Message\ServerRequestInterface|null
$request optional The optional request
void
logInternalError(Throwable $exception): void
Trigger an error that occurred during rendering an exception.
By triggering an E_USER_ERROR we can end up in the default exception handling which will log the rendering failure, and hopefully render an error page.
Throwable
$exception Exception to log
void
logger(): Cake\Error\ErrorLoggerInterface
Get an instance of the logger.
Cake\Error\ErrorLoggerInterface
register(): void
Attach this ExceptionTrap to PHP's default exception handler.
This will replace the existing exception handler, and the previous exception handler will be discarded.
void
renderer(Throwable $exception, Psr\Http\Message\ServerRequestInterface|null $request = null): Cake\Error\ExceptionRendererInterface
Get an instance of the renderer.
Throwable
$exception Exception to render
Psr\Http\Message\ServerRequestInterface|null
$request optional The request if possible.
Cake\Error\ExceptionRendererInterface
setConfig(array<string, mixed>|string $key, mixed|null $value = null, bool $merge = true): $this
Sets the config.
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']);
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.
$this
Cake\Core\Exception\CakeException
setEventManager(Cake\Event\EventManagerInterface $eventManager): $this
Returns 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.
Cake\Event\EventManagerInterface
$eventManager the eventManager to set
$this
unregister(): void
Remove this instance from the singleton
If this instance is not currently the registered singleton nothing happens.
void
Runtime config
array<string, mixed>
Whether the config property has already been configured with defaults
bool
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 in src/Error
. Your exception renderer needs to implement the render()
method and return either a string or Http\Response.log
Set to false to disable logging.logger
- string - The class name of the error logger to use.trace
- boolean - Whether or not 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 logger
extraFatalErrorMemory
- 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.stderr
Used in console environments so that renderers have access to the current console output stream.array<string, mixed>
Default class name for new event objects.
string
Instance of the Cake\Event\EventManager this object is using to dispatch inner events.
Cake\Event\EventManagerInterface|null
A list of handling callbacks.
Callbacks are invoked for each error that is handled. Callbacks are invoked in the order they are attached.
arrayClosure>
Track if this trap was removed from the global handler.
bool
The currently registered global exception handler
This is best effort as we can't know if/when another exception handler is registered.
Cake\Error\ExceptionTrap|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.4/class-Cake.Error.ExceptionTrap.html