W3cubDocs

/CakePHP 4.4

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).

Namespace: Cake\Error

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>

    Configuration options. Generally these will be defined in your config/app.php

  • $_eventClass protected
    string

    Default class name for new event objects.

  • $_eventManager protected
    Cake\Event\EventManagerInterface|null

    Instance of the Cake\Event\EventManager this object is using to dispatch inner events.

  • $callbacks protected
    arrayClosure>

    A list of handling callbacks.

  • $disabled protected
    bool

    Track if this trap was removed from the global handler.

  • $registeredTrap protected static
    Cake\Error\ExceptionTrap|null

    The currently registered global exception handler

Method Summary

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): 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

chooseRenderer() protected 

chooseRenderer(): class-stringCake\Error\ExceptionRendererInterface>

Choose an exception renderer based on config or the SAPI

Returns

class-stringCake\Error\ExceptionRendererInterface>

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

dispatchEvent() public 

dispatchEvent(string $name, array|null $data = null, object|null $subject = null): Cake\Event\EventInterface

Wrapper for creating and dispatching events.

Returns a dispatched event.

Parameters

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).

Returns

Cake\Event\EventInterface

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

getEventManager() public 

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.

Returns

Cake\Event\EventManagerInterface

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

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

handleFatalError() public 

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

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

void

handleShutdown() public 

handleShutdown(): void

Shutdown handler

Convert fatal errors into exceptions that we can render.

Returns

void

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

instance() public static 

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.

Returns

Cake\Error\ExceptionTrap|null

logException() public 

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.

Parameters

Throwable $exception

The exception to log

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

The optional request

Returns

void

logInternalError() public 

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.

Parameters

Throwable $exception

Exception to log

Returns

void

logger() public 

logger(): Cake\Error\ErrorLoggerInterface

Get an instance of the logger.

Returns

Cake\Error\ErrorLoggerInterface

register() public 

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.

Returns

void

renderer() public 

renderer(Throwable $exception, Psr\Http\Message\ServerRequestInterface|null $request = null): Cake\Error\ExceptionRendererInterface

Get 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\ExceptionRendererInterface

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.

setEventManager() public 

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.

Parameters

Cake\Event\EventManagerInterface $eventManager

the eventManager to set

Returns

$this

unregister() public 

unregister(): void

Remove this instance from the singleton

If this instance is not currently the registered singleton nothing happens.

Returns

void

Property Detail

$_config protected

Runtime config

Type

array<string, mixed>

$_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 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.

Type

array<string, mixed>

$_eventClass protected

Default class name for new event objects.

Type

string

$_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

arrayClosure>

$disabled protected

Track if this trap was removed from the global handler.

Type

bool

$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

© 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