Class Fault

Global error handling system for triggered errors and uncaught exceptions.

Handles triggered errors and uncaught exceptions, including fatal errors via a special shutdown handler. Each incident is reported via all configured reporters, defaulting to the 'stdout:' reporter. If all reporters fail, an integrated basic formatter will print out incident details to the standard output in either plain text for CLI applications or otherwise HTML.

Own error handling can be implemented by deriving an own fault handler from this class.

To identify a request, the fault instance UUID is generally used. This is useful to connect multiple reports together, or to present an identifier for a reported problem to the user.

Core\Object implements Core\Chainable

Core\Set implements Core\Accessor

Core\Fault implements Core\Chainable

Namespace: Core
Package: Core
Since: 3.0
Requires: PHP 5.3
Version: 2.0
Used by: xc_dump_bt()
Located at Fault.inc.php

Methods summary

`public static Core\Fault`	# `instance( )` Returns the singleton instance. The fault handler can be configured using the `Core\Configuration\FaultHandler` constant. Returns the singleton instance. The fault handler can be configured using the `Core\Configuration\FaultHandler` constant. Returns `Core\Fault` Singleton instance. See `Core\Configuration\FaultHandler` Since 3.0
`protected`	# `__construct( )` Configures environment for error handling. Configures environment for error handling. Since 3.0
`protected`	# `_format( Core\Fault\Incident $incident )` Formats and prints out an incident in case reporter drivers failed or an error occurred during handling an incident. No character sets are used, the output is simplified (i.e. no call arguments are being rendered) and only uses minimal HTML formatting in case no CLI app is being detected. Formats and prints out an incident in case reporter drivers failed or an error occurred during handling an incident. No character sets are used, the output is simplified (i.e. no call arguments are being rendered) and only uses minimal HTML formatting in case no CLI app is being detected. Parameters `$incident` Incident to render and output. Since 3.2
`protected string`	# `_formatMessage( $message )` Formats a message for direct output. The text is returned with a newline appended for CLI applications, otherwise formatted and encoded in HTML. Takes advantage of an already existing fault CSS. Formats a message for direct output. The text is returned with a newline appended for CLI applications, otherwise formatted and encoded in HTML. Takes advantage of an already existing fault CSS. Parameters `$message` to format. Returns string Formatted message for direct printout. Since 3.2
`protected boolean`	# `_handle( Core\Fault\Incident $incident )` Prints out error and stops script execution if error is fatal or error threshold was reached. Prints out error and stops script execution if error is fatal or error threshold was reached. Parameters `$incident` Incident to handle. Returns boolean `true`, if execution should resume (if possible), Since 3.0
`public integer\|boolean`	# `chain( Core\Chainable $object, array $flags = null )` Connects another object to the current object. Usage depends on the actual class implementation; common examples are lazy configuration completion or layer expansions. Allows setting additional reporter instances or replacing the current set of reporters. Alternatively, reporters can be added by directly appending a new reporter instance to the reporters property. Connects another object to the current object. Usage depends on the actual class implementation; common examples are lazy configuration completion or layer expansions. Allows setting additional reporter instances or replacing the current set of reporters. Alternatively, reporters can be added by directly appending a new reporter instance to the reporters property. Parameters `$object` Object to chain to instance. `$flags` Optional array of additional chain flags. Usage depends on the actual chain implementation. Returns integer\|boolean Returns a non-zero value on success, otherwise `false`. Throws `Core\Exception\InvalidArgument` Class of provided object is not supported. Since 3.2 Overrides `Core\Object::chain` Implementation of `Core\Chainable::chain()`
`public boolean`	# `handleError( integer $errorCode, string $message = null, string $filename = null, integer $line = null, mixed $context = null, boolean $silentError = null )` Handler for triggered errors. Handler for triggered errors. Parameters `$errorCode` Error code. `$message` Error message. `$filename` Name of file in which the error was triggered. `$line` Line number. `$context` Additional context information. `$silentError` `true`, if error output is suppressed using the at operator (`"@"`). Returns boolean `true`, if the standard PHP error handler should be bypassed. Since 3.0
`public`	# `handleException( Exception\|Error\|Throwable $exception )` Handler for uncaught exceptions. Processes exception and all chained previous exceptions (if any) and stops script execution. Handler for uncaught exceptions. Processes exception and all chained previous exceptions (if any) and stops script execution. Parameters `$exception` Uncaught exception instance. Since 3.0
`public`	# `handleShutdown( )` Handler on shutdown to catch fatal errors by checking the last error. Handler on shutdown to catch fatal errors by checking the last error. Since 3.0
`public integer`	# `levelThreshold( )` Returns the configured threshold for the maximum incident level after which execution is stopped to avoid recursion in error handling. The value if always read from the configured configuration instance and can be changed during runtime by adjusting the configuration accordingly. Returns the configured threshold for the maximum incident level after which execution is stopped to avoid recursion in error handling. The value if always read from the configured configuration instance and can be changed during runtime by adjusting the configuration accordingly. Returns integer Configured threshold of maximum incident level before stopping processing further incidents. Since 3.2
`public string`	# `reference( )` Returns the request reference identifier commonly used to connect reports together or give users a reference number on error pages. Returns the request reference identifier commonly used to connect reports together or give users a reference number on error pages. Requests should always be stored using the full UUID of the fault instance. The reference identifier is based on the UUID but only shows the last 48 bits per default for improved readability. In case a report has to be fetched based on the shorter reference, it is recommended to manually filter matches in the last 48 bits. Depending on the amount of requests and requirements on the format used, the reference can be configured for several transformations and different lengths. The length is configured in bits via the core.fault.reference.length configuration option. If a negative number is given, the bits are counted from the end (recommended), otherwise from the beginning. The default value is -48 and values are always rounded to the next multiple of 8 (full byte). Transformations are configured via the core.fault.reference.format configuration option: - `hex` Default format. Hexadecimal representation of reference. `hex-prefix` Same as the default hexadecimal format, but adds the prefix '0x'. `numeric`, `numeric-le` and `numeric-be` Formats the reference as an integer. This will truncate the maximum length to the maximum supported length depending on the version of PHP: For PHP version 5.6.3 and higher, the maximum supported length is 64 bits (on a 64-bit system), otherwise 32 bits. The variants stand for machine byte order, little-endian and big-endian. For lengths other than 32 bits and 64 bits it is recommended to use big-endian encoding if short numbers should be achieved. Encoder Driver URI Alternatively, an arbitrary encoder driver URI can be supplied. The encoder is instantiated during the constructor and will be used to encode the already truncated reference bytes. If an exception occurs while calling the encoder, the incident will be normally reported and the default reference format will be used. Returns string Request reference identifier. Since 3.2
`public integer`	# `threshold( )` Returns the configured threshold for incidents after which execution is stopped when the number of handled recoverable incidents exceeds the configured threshold. The value if always read from the configured configuration instance and can be changed during runtime by adjusting the configuration accordingly. Returns the configured threshold for incidents after which execution is stopped when the number of handled recoverable incidents exceeds the configured threshold. The value if always read from the configured configuration instance and can be changed during runtime by adjusting the configuration accordingly. Returns integer Configured threshold of maximum number of incidents to handle. Since 3.2
`public array[]`	# `trace( array $db = null, array $options = null )` Returns a pre-processed trace. Returns a pre-processed trace. Parameters `$db` PHP debug backtrace or native exception trace to process. If `null`, the current PHP debug backtrace is fetched instead. `$options` Associative array of special handling instructions for the trace: `incident` Incident the trace is created for. This will embed file context information into the returned trace. `skip` Shifts the given number of entries from the trace before filtering. This is useful to filter out error handler calls and retrieve a clean trace with only relevant information. Returns array[] Pre-processes backtrace. Each entry is an array with with the following fields: `file` Array with source file information of trace entry. Contains two fields `filename` and `line`. The fields are always present. A value is absent if it is `null`. `name` Formatted name of called function or method. `args` Array of call arguments. The value is always present and set to an empty array if the call has no arguments. `class` Name of class of a method call, otherwise `null`. `function` Name of the called function or method. `type` Call method used for method calls, otherwise `null`. `object` In case of a method call of an existing object and the source trace does include this information, the object is retained. Otherwise the value is `null`. Since 3.0

Methods inherited from Core\Set

__get(), __isset()

Methods inherited from Core\Object

__autocreateFactory(), __call(), __processParameters(), __toString(), attachMethod(), getValueForKey(), getValueForKeyPath(), getValueForUndefinedKey(), hash(), issetValueForKey(), setValueForKey(), setValueForKeyPath(), setValueForUndefinedKey(), uuid()

Constants summary

`integer`	`DefaultThreshold` Default incidents threshold used if not defined in system configuration. Default incidents threshold used if not defined in system configuration. Since 3.2	# `5`
`integer`	`DefaultLevelThreshold` Default level threshold for incidents if not defined in system configuration to avoid recursively appearing incidents. Default level threshold for incidents if not defined in system configuration to avoid recursively appearing incidents. Since 3.2	# `2`
`string`	`DefaultFaultClass` Name of default fault handler class. Used, if either no fault handler class is found in the system configuration, or an exception occurred while parsing the system configuration. Name of default fault handler class. Used, if either no fault handler class is found in the system configuration, or an exception occurred while parsing the system configuration. Since 3.2	# `'core.fault'`
`string`	`UnknownSourceLabel` Replacement string used for unknown sources, i.e. missing filenames in incidents and traces. Replacement string used for unknown sources, i.e. missing filenames in incidents and traces. Since 3.2	# `'<unknown source>'`

Constants inherited from Core\Object

AnyParameterType, AutochainParameterType, AutocreateParameterType, BooleanParameterType, CharParameterType, EnumParameterType, IntegerParameterType, RealParameterType, StringParameterType, UserParameterType

Properties summary

`protected integer`	`$_v_incidentLevel` Current incident processing level. If >0, then an incident is currently being processed by the fault handler. If >1, an incident was raised during the execution of the fault handler. Current incident processing level. If >0, then an incident is currently being processed by the fault handler. If >1, an incident was raised during the execution of the fault handler. Since 3.2	# `0`
`protected integer`	`$_v_incidents` Number of encountered incidents since start of script execution. Number of encountered incidents since start of script execution. Since 3.2	# `0`
`protected string\|Core\Encoder`	`$_v_referenceFormat` Request reference identifier format or encoder instance, depending on configuration. Request reference identifier format or encoder instance, depending on configuration. Since 3.2	#
`protected integer`	`$_v_referenceLength` Request reference identifier length in bits. If negative, the reference is based on the given number of bits from the end of the UUID. Request reference identifier length in bits. If negative, the reference is based on the given number of bits from the end of the UUID. Since 3.2	#
`protected Core\Fault\Reporter[]`	`$_v_reporters` Array object of registered reporter instances. Array object of registered reporter instances.	#
`protected static Core\Fault`	`$_instance` Singleton instance. Singleton instance. Since 3.0	#

Magic properties

`public read-only integer`	`$incidentLevel` Current incident processing level.
`public read-only integer`	`$incidents` Number of encountered incidents since start of script execution.
`public read-only integer`	`$levelThreshold` Configured incident level threshold value.
`public read-only string`	`$reference` Formatted request reference identifier.
`public read-only string\|Core\Encoder`	`$referenceFormat` Configured transformation for request reference identifiers. Can be an encoder instance, depending on configuration.
`public read-only integer`	`$referenceLength` Length in bits of request reference identifiers. If negative, the reference is based on the given number of bits from the end of the UUID.
`public read-only integer`	`$threshold` Configured incidents threshold value.
`public read-only array`	`$trace` Retrieves the current call trace (including KVC property access calls).

Magic properties inherited from Core\Object

$hash, $uuid

Namespaces

Classes

Interfaces

Exceptions

Constants

Class Fault

Methods summary

Returns

See

Since

Since

Parameters

Since

Parameters

Returns

Since

Parameters

Returns

Since

Parameters

Returns

Throws

Since

Overrides

Implementation of

Parameters

Returns

Since

Parameters

Since

Since

Returns

Since

Returns

Since

Returns

Since

Parameters

Returns

Since

Methods inherited from Core\Set

Methods inherited from Core\Object

Constants summary

Since

Since

Since

Since

Constants inherited from Core\Object

Properties summary

Since

Since

Since

Since

Since

Magic properties

Magic properties inherited from Core\Object