Diviner libphutil Tech Docs PhutilErrorHandler

Contents
PhutilErrorHandler::initialize()## and forwards all debugging information

final class PhutilErrorHandler
libphutil Technical Documentation (Errors)

Improve PHP error logs and optionally route errors, exceptions and debugging information to a central listener.

This class takes over the PHP error and exception handlers when you call

PhutilErrorHandler::initialize()## and forwards all debugging information

to a listener you install with PhutilErrorHandler::setErrorListener().

To use PhutilErrorHandler, which will enhance the messages printed to the PHP error log, just initialize it:

PhutilErrorHandler::initialize();

To additionally install a custom listener which can print error information to some other file or console, register a listener:

PhutilErrorHandler::setErrorListener($some_callback);

For information on writing an error listener, see phutil_error_listener_example(). Providing a listener is optional, you will benefit from improved error logs even without one.

Phabricator uses this class to drive the DarkConsole "Error Log" plugin.

Tasks

Configuring Error Dispatch

public static function initialize() — Registers this class as the PHP error and exception handler. This will overwrite any previous handlers!
public static function setErrorListener($listener) — Provide an optional listener callback which will receive all errors, exceptions and debugging messages. It can then print them to a web console, for example.

Exception Utilities

public static function getPreviousException($ex) — Gets the previous exception of a nested exception. Prior to PHP 5.3 you can use @{class:PhutilProxyException} to nest exceptions; after PHP 5.3 all exceptions are nestable.
public static function getRootException($ex) — Find the most deeply nested exception from a possibly-nested exception.

Error Traps

public static function addErrorTrap($trap) — Adds an error trap. Normally you should not invoke this directly; @{class:PhutilErrorTrap} registers itself on construction.
public static function removeErrorTrap($trap) — Removes an error trap. Normally you should not invoke this directly; @{class:PhutilErrorTrap} deregisters itself on destruction.

Internals

public static function hasInitialized() — Determine if PhutilErrorHandler has been initialized.
public static function handleError($num, $str, $file, $line, $ctx) — Handles PHP errors and dispatches them forward. This is a callback for ##set_error_handler()##. You should not call this function directly; use @{function:phlog} to print debugging messages or ##trigger_error()## to trigger PHP errors.
public static function handleException($ex) — Handles PHP exceptions and dispatches them forward. This is a callback for ##set_exception_handler()##. You should not call this function directly; to print exceptions, pass the exception object to @{function:phlog}.
public static function outputStacktrace($trace) — Output a stacktrace to the PHP error log.
public static function formatStacktrace($trace) — Format a stacktrace for output.
public static function dispatchErrorMessage($event, $value, $metadata) — All different types of error messages come here before they are dispatched to the listener; this method also prints them to the PHP error log.

Other Methods

public function __get($name)
public function __set($name, $value)
public function current()
public function key()
public function next()
public function rewind()
public function valid()
private function throwOnAttemptedIteration()
public function getPhobjectClassConstant($key, $byte_limit) — Read the value of a class constant.
public static function adjustFilePath($path)
public static function getLibraryVersions()
public static function getExceptionTrace($ex) — Get a full trace across all proxied and aggregated exceptions.

Methods

public function __get($name)
Inherited

This method is not documented.

Parameters

$name

Return

wild

public function __set($name, $value)
Inherited

This method is not documented.

Parameters

	$name
	$value

Return

wild

public function current()
Inherited

This method is not documented.

Return

wild

public function key()
Inherited

This method is not documented.

Return

wild

public function next()
Inherited

This method is not documented.

Return

wild

public function rewind()
Inherited

This method is not documented.

Return

wild

public function valid()
Inherited

This method is not documented.

Return

wild

private function throwOnAttemptedIteration()
Inherited

This method is not documented.

Return

wild

public function getPhobjectClassConstant($key, $byte_limit)
Inherited

Phobject

Read the value of a class constant.

This is the same as just typing self::CONSTANTNAME, but throws a more useful message if the constant is not defined and allows the constant to be limited to a maximum length.

Parameters

string	$key	Name of the constant.
int\|null	$byte_limit	Maximum number of bytes permitted in the value.

Return

string

Value of the constant.

public static function initialize()

Registers this class as the PHP error and exception handler. This will overwrite any previous handlers!

Return

void

public static function setErrorListener($listener)

Provide an optional listener callback which will receive all errors, exceptions and debugging messages. It can then print them to a web console, for example.

See phutil_error_listener_example() for details about the callback parameters and operation.

Parameters

$listener

Return

void

public static function getPreviousException($ex)

Gets the previous exception of a nested exception. Prior to PHP 5.3 you can use PhutilProxyException to nest exceptions; after PHP 5.3 all exceptions are nestable.

Parameters

Exception|Throwable

$ex

Exception to unnest.

Return

Exception|Throwable|null

Previous exception, if one exists.

public static function getRootException($ex)

Find the most deeply nested exception from a possibly-nested exception.

Parameters

Exception|Throwable

$ex

A possibly-nested exception.

Return

Exception|Throwable

Deepest exception in the nest.

public static function addErrorTrap($trap)

Adds an error trap. Normally you should not invoke this directly; PhutilErrorTrap registers itself on construction.

Parameters

PhutilErrorTrap

$trap

Trap to add.

Return

void

public static function removeErrorTrap($trap)

Removes an error trap. Normally you should not invoke this directly; PhutilErrorTrap deregisters itself on destruction.

Parameters

PhutilErrorTrap

$trap

Trap to remove.

Return

void

public static function hasInitialized()

Determine if PhutilErrorHandler has been initialized.

Return

bool	True if initialized.

public static function handleError($num, $str, $file, $line, $ctx)

Handles PHP errors and dispatches them forward. This is a callback for

set_error_handler()##. You should not call this function directly; use

phlog() to print debugging messages or trigger_error() to trigger PHP errors.

This handler converts E_RECOVERABLE_ERROR messages from violated typehints into InvalidArgumentExceptions.

This handler converts other E_RECOVERABLE_ERRORs into RuntimeExceptions.

This handler converts E_NOTICE messages from uses of undefined variables into RuntimeExceptions.

Parameters

int	$num	Error code.
string	$str	Error message.
string	$file	File where the error occurred.
int	$line	Line on which the error occurred.
wild	$ctx	Error context information.

Return

void

public static function handleException($ex)

Handles PHP exceptions and dispatches them forward. This is a callback for

set_exception_handler()##. You should not call this function directly;

to print exceptions, pass the exception object to phlog().

Parameters

Exception|Throwable

$ex

Uncaught exception object.

Return

void

public static function outputStacktrace($trace)

Output a stacktrace to the PHP error log.

Parameters

trace

$trace

A stacktrace, e.g. from debug_backtrace();

Return

void

public static function formatStacktrace($trace)

Format a stacktrace for output.

Parameters

trace

$trace

A stacktrace, e.g. from debug_backtrace();

Return

string

Human-readable trace.

public static function dispatchErrorMessage($event, $value, $metadata)

All different types of error messages come here before they are dispatched to the listener; this method also prints them to the PHP error log.

Parameters

const	$event	Event type constant.
wild	$value	Event value.
dict	$metadata	Event metadata.

Return

void

public static function adjustFilePath($path)

This method is not documented.

Parameters

$path

Return

wild

public static function getLibraryVersions()

This method is not documented.

Return

wild

public static function getExceptionTrace($ex)

Get a full trace across all proxied and aggregated exceptions.

This attempts to build a set of stack frames which completely represent all of the places an exception came from, even if it came from multiple origins and has been aggregated or proxied.

Parameters

Exception|Throwable

$ex

Exception to retrieve a trace for.

Return

list<wild>

List of stack frames.

Defined: src/error/PhutilErrorHandler.php:32
Extends: Phobject

final class PhutilErrorHandlerlibphutil Technical Documentation (Errors)

PhutilErrorHandler::initialize()## and forwards all debugging information

Tasks

Configuring Error Dispatch

Exception Utilities

Error Traps

Internals

Other Methods

Methods

public function __get($name)Inherited

public function __set($name, $value)Inherited

public function current()Inherited

public function key()Inherited

public function next()Inherited

public function rewind()Inherited

public function valid()Inherited

private function throwOnAttemptedIteration()Inherited

public function getPhobjectClassConstant($key, $byte_limit)Inherited

public static function initialize()

public static function setErrorListener($listener)

public static function getPreviousException($ex)

public static function getRootException($ex)

public static function addErrorTrap($trap)

public static function removeErrorTrap($trap)

public static function hasInitialized()

public static function handleError($num, $str, $file, $line, $ctx)

set_error_handler()##. You should not call this function directly; use

public static function handleException($ex)

set_exception_handler()##. You should not call this function directly;

public static function outputStacktrace($trace)

public static function formatStacktrace($trace)

public static function dispatchErrorMessage($event, $value, $metadata)

public static function adjustFilePath($path)

public static function getLibraryVersions()

public static function getExceptionTrace($ex)

final class PhutilErrorHandler
libphutil Technical Documentation (Errors)

public function __get($name)
Inherited

public function __set($name, $value)
Inherited

public function current()
Inherited

public function key()
Inherited

public function next()
Inherited

public function rewind()
Inherited

public function valid()
Inherited

private function throwOnAttemptedIteration()
Inherited

public function getPhobjectClassConstant($key, $byte_limit)
Inherited