Class PEAR_ErrorStack

Description

Error Stack Implementation

Usage:

  1. // global error stack
  2. $global_stack = &PEAR_ErrorStack::singleton('MyPackage');
  3. // local error stack
  4. $local_stack = new PEAR_ErrorStack('MyPackage');

Located in /maintenance/libraries/pear/PEAR/ErrorStack.php (line 152)


	
			
Variable Summary
 boolean $_compat
 false|string|array $_contextCallback
 false|string|array $_errorCallback
 array $_errorMsgs
 array $_errors
 false|Log $_logger
 false|string|array $_msgCallback
 string $_package
Method Summary
 PEAR_ErrorStack PEAR_ErrorStack (string $package, [callback $msgCallback = false], [callback $contextCallback = false], [boolean $throwPEAR_Error = false])
 string getErrorMessage (PEAR_ErrorStack &$stack, array $err, [string|false $template = false])
 string getErrorMessageTemplate (mixed $code)
 array getErrors ([boolean $purge = false], [string $level = false])
 array|false getFileLine (unused $code, integer $params, [array $backtrace = null])
 array|string|false getMessageCallback ()
 boolean hasErrors ([string|array $level = false])
 false|array pop ()
 array|string|false popCallback ()
 PEAR_Error|array|Exception push (int $code, [string $level = 'error'], [array $params = array()], [string $msg = false], [array $repackage = false], [array $backtrace = false])
 void pushCallback (string|array $cb)
 void setContextCallback (array|string|null $contextCallback)
 void setDefaultCallback ([array|string $callback = false], [string $package = false])
 void setDefaultLogger (Log &$log)
 string setErrorMessageTemplate (mixed $template)
 void setLogger (Log &$log)
 void setMessageCallback (array|string $msgCallback)
 PEAR_ErrorStack &singleton (string $package, [callback $msgCallback = false], [callback $contextCallback = false], [boolean $throwPEAR_Error = false], [string $stackClass = 'PEAR_ErrorStack'])
 array staticGetErrors ([boolean $purge = false], [string $level = false], [boolean $merge = false], [array $sortfunc = array('PEAR_ErrorStack', '_sortErrors')])
 boolean staticHasErrors ([string|false $package = false], [string $level = false])
 array|string|false staticPopCallback ()
 PEAR_Error|null|Exception staticPush (string $package, int $code, [string $level = 'error'], [array $params = array()], [string $msg = false], [array $repackage = false], [array $backtrace = false])
 void staticPushCallback (string|array $cb)
 void _handleError (mixed $err)
 void _log (array $err, [array $levels = array( 'exception' => PEAR_LOG_CRIT, 'alert' => PEAR_LOG_ALERT, 'critical' => PEAR_LOG_CRIT, 'error' => PEAR_LOG_ERR, 'warning' => PEAR_LOG_WARNING, 'notice' => PEAR_LOG_NOTICE, 'info' => PEAR_LOG_INFO, 'debug' => PEAR_LOG_DEBUG)])
 void _sortErrors (mixed $a, mixed $b)
Variables
boolean $_compat = false (line 185)

Determines whether a PEAR_Error is thrown upon every error addition

  • access: private
false|string|array $_contextCallback = false (line 205)

If set to a valid callback, this will be used to generate the error

context for an error. For PHP-related errors, this will be a file and line number as retrieved from debug_backtrace(), but can be customized for other purposes. The error might actually be in a separate configuration file, or in a database query.

  • access: protected
false|string|array $_errorCallback = array() (line 217)

If set to a valid callback, this will be called every time an error is pushed onto the stack. The return value will be used to determine whether to allow an error to be pushed or logged.

The return value must be one an PEAR_ERRORSTACK_* constant

array $_errorMsgs = array() (line 231)

Error messages - designed to be overridden

  • abstract:
array $_errors = array() (line 161)

Errors are stored in the order that they are pushed on the stack.

  • access: private
  • since: 0.4alpha Errors are no longer organized by error level. This renders pop() nearly unusable, and levels could be more easily handled in a callback anyway
array $_errorsByLevel = array() (line 171)

Storage of errors by level.

Allows easy retrieval and deletion of only errors from a particular level

  • access: private
  • since: PEAR 1.4.0dev
false|Log $_logger = false (line 224)

PEAR::Log object for logging errors

  • access: protected
false|string|array $_msgCallback = false (line 194)

If set to a valid callback, this will be used to generate the error

message from the error code, otherwise the message passed in will be used

  • access: private
string $_package (line 178)

Package name this error stack represents

  • access: protected
Methods
Constructor PEAR_ErrorStack (line 242)

Set up a new error stack

PEAR_ErrorStack PEAR_ErrorStack (string $package, [callback $msgCallback = false], [callback $contextCallback = false], [boolean $throwPEAR_Error = false])
  • string $package: name of the package this error stack represents
  • callback $msgCallback: callback used for error message generation
  • callback $contextCallback: callback used for context generation, defaults to getFileLine()
  • boolean $throwPEAR_Error
getErrorMessage (line 879)

Standard error message generation callback

This method may also be called by a custom error message generator to fill in template values from the params array, simply set the third parameter to the error message template string to use

The special variable %__msg% is reserved: use it only to specify where a message passed in by the user should be placed in the template, like so:

Error message: %msg% - internal error

If the message passed like so:

  1. $stack->push(ERROR_CODE, 'error', array(), 'server error 500');

The returned error message will be "Error message: server error 500 - internal error"

  • static:
string getErrorMessage (PEAR_ErrorStack &$stack, array $err, [string|false $template = false])
  • PEAR_ErrorStack &$stack
  • array $err
  • string|false $template: Pre-generated error message template
getErrorMessageTemplate (line 913)

Standard Error Message Template generator from code

string getErrorMessageTemplate (mixed $code)
getErrors (line 686)

Retrieve all errors since last purge

array getErrors ([boolean $purge = false], [string $level = false])
  • boolean $purge: set in order to empty the error stack
  • string $level: level name, to return only errors of a particular severity
getFileLine (line 804)

Standard file/line number/function/class context callback

This function uses a backtrace generated from http://www.php.net/debug_backtrace and so will not work at all in PHP < 4.3.0. The frame should reference the frame that contains the source of the error.

  • return: either array('file' => file, 'line' => line, 'function' => function name, 'class' => class name) or if this doesn't work, then false
  • static:
array|false getFileLine (unused $code, integer $params, [array $backtrace = null])
  • unused $code
  • integer $params: backtrace frame.
  • array $backtrace: Results of debug_backtrace()
getMessageCallback (line 348)

Get an error code => error message mapping callback

This method returns the current callback that can be used to generate error messages

  • return: Callback function/method or false if none
array|string|false getMessageCallback ()
hasErrors (line 671)

Determine whether there are any errors on the stack

boolean hasErrors ([string|array $level = false])
  • string|array $level: Level name. Use to determine if any errors of level (string), or levels (array) have been pushed
pop (line 660)

Pop an error off of the error stack

  • since: 0.4alpha it is no longer possible to specify a specific error level to return - the last error pushed will be returned, instead
false|array pop ()
popCallback (line 418)

Remove a callback from the error callback stack

array|string|false popCallback ()
push (line 504)

Add an error to the stack

If the message generator exists, it is called with 2 parameters.

  • the current Error Stack object
  • an array that is in the same format as an error. Available indices are 'code', 'package', 'time', 'params', 'level', and 'context'
Next, if the error should contain context information, this is handled by the context grabbing method. Finally, the error is pushed onto the proper error stack

  • return:

    if compatibility mode is on, a PEAR_Error is also thrown. If the class Exception exists, then one is returned to allow code like:

    1. throw ($stack->push(MY_ERROR_CODE, 'error', array('username' => 'grob')));

    The errorData property of the exception class will be set to the array that would normally be returned. If a PEAR_Error is returned, the userinfo property is set to the array

    Otherwise, an array is returned in this format:

    1. array(
    2. 'code' => $code,
    3. 'params' => $params,
    4. 'package' => $this->_package,
    5. 'level' => $level,
    6. 'time' => time(),
    7. 'context' => $context,
    8. 'message' => $msg,
    9. //['repackage' => $err] repackaged error array/Exception class
    10. );

PEAR_Error|array|Exception push (int $code, [string $level = 'error'], [array $params = array()], [string $msg = false], [array $repackage = false], [array $backtrace = false])
  • int $code: Package-specific error code
  • string $level: Error level. This is NOT spell-checked
  • array $params: associative array of error parameters
  • string $msg: Error message, or a portion of it if the message is to be generated
  • array $repackage: If this error re-packages an error pushed by another package, place the array returned from pop() in this parameter
  • array $backtrace: Protected parameter: use this to pass in the http://www.php.net/debug_backtrace that should be used to find error context
pushCallback (line 408)

Set an error Callback If set to a valid callback, this will be called every time an error is pushed onto the stack. The return value will be used to determine whether to allow an error to be pushed or logged.

The return value must be one of the ERRORSTACK_* constants.

This functionality can be used to emulate PEAR's pushErrorHandling, and the PEAR_ERROR_CALLBACK mode, without affecting the integrity of the error stack or logging

void pushCallback (string|array $cb)
  • string|array $cb
raiseError (line 946)

emulate PEAR::raiseError()

PEAR_Error raiseError ()
setContextCallback (line 379)

Set a callback that generates context information (location of error) for an error stack

This method sets the callback that can be used to generate context information for an error. Passing in NULL will disable context generation and remove the expensive call to debug_backtrace()

void setContextCallback (array|string|null $contextCallback)
  • array|string|null $contextCallback: Callback function/method
setDefaultCallback (line 362)

Sets a default callback to be used by all error stacks

This method sets the callback that can be used to generate error messages for a singleton

  • static:
void setDefaultCallback ([array|string $callback = false], [string $package = false])
  • array|string $callback: Callback function/method
  • string $package: Package name, or false for all packages
setDefaultLogger (line 309)

Set up a PEAR::Log object for all error stacks that don't have one

  • static:
void setDefaultLogger (Log &$log)
setErrorMessageTemplate (line 935)

Set the Error Message Template array

The array format must be:

 array(error code => 'message template',...)

Error message parameters passed into push() will be used as input for the error message. If the template is 'message %foo% was %bar%', and the parameters are array('foo' => 'one', 'bar' => 'six'), the error message returned will be 'message one was six'

string setErrorMessageTemplate (mixed $template)
setLogger (line 318)

Set up a PEAR::Log object for this error stack

void setLogger (Log &$log)
setMessageCallback (line 330)

Set an error code => error message mapping callback

This method sets the callback that can be used to generate error messages for any instance

void setMessageCallback (array|string $msgCallback)
  • array|string $msgCallback: Callback function/method
singleton (line 265)

Return a single error stack for this package.

Note that all parameters are ignored if the stack for package $package has already been instantiated

  • static:
PEAR_ErrorStack &singleton (string $package, [callback $msgCallback = false], [callback $contextCallback = false], [boolean $throwPEAR_Error = false], [string $stackClass = 'PEAR_ErrorStack'])
  • string $package: name of the package this error stack represents
  • callback $msgCallback: callback used for error message generation
  • callback $contextCallback: callback used for context generation, defaults to getFileLine()
  • boolean $throwPEAR_Error
  • string $stackClass: class to instantiate
staticGetErrors (line 753)

Get a list of all errors since last purge, organized by package

  • static:
  • since: PEAR 1.4.0dev BC break! $level is now in the place $merge used to be
array staticGetErrors ([boolean $purge = false], [string $level = false], [boolean $merge = false], [array $sortfunc = array('PEAR_ErrorStack', '_sortErrors')])
  • boolean $purge: Set to purge the error stack of existing errors
  • string $level: Set to a level name in order to retrieve only errors of a particular level
  • boolean $merge: Set to return a flat array, not organized by package
  • array $sortfunc: Function used to sort a merged array - default sorts by time, and should be good for most cases
staticHasErrors (line 726)

Determine whether there are any errors on a single error stack, or on any error stack

The optional parameter can be used to test the existence of any errors without the need of singleton instantiation

  • static:
boolean staticHasErrors ([string|false $package = false], [string $level = false])
  • string|false $package: Package name to check for errors
  • string $level: Level name to check for a particular severity
staticPopCallback (line 447)

Remove a temporary overriding error callback

array|string|false staticPopCallback ()
staticPush (line 610)

Static version of push()

  • return: if compatibility mode is on, a PEAR_Error is also thrown. If the class Exception exists, then one is returned to allow code like:
    1. throw ($stack->push(MY_ERROR_CODE, 'error', array('username' => 'grob')));
  • static:
PEAR_Error|null|Exception staticPush (string $package, int $code, [string $level = 'error'], [array $params = array()], [string $msg = false], [array $repackage = false], [array $backtrace = false])
  • string $package: Package name this error belongs to
  • int $code: Package-specific error code
  • string $level: Error level. This is NOT spell-checked
  • array $params: associative array of error parameters
  • string $msg: Error message, or a portion of it if the message is to be generated
  • array $repackage: If this error re-packages an error pushed by another package, place the array returned from pop() in this parameter
  • array $backtrace: Protected parameter: use this to pass in the http://www.php.net/debug_backtrace that should be used to find error context
staticPushCallback (line 436)

Set a temporary overriding error callback for every package error stack

Use this to temporarily disable all existing callbacks (can be used to emulate the @ operator, for instance)

void staticPushCallback (string|array $cb)
  • string|array $cb
_handleError (line 290)

Internal error handler for PEAR_ErrorStack class

Dies if the error is an exception (and would have died anyway)

  • access: private
void _handleError (mixed $err)
_log (line 630)

Log an error using PEAR::Log

  • access: protected
void _log (array $err, [array $levels = array( 'exception' => PEAR_LOG_CRIT, 'alert' => PEAR_LOG_ALERT, 'critical' => PEAR_LOG_CRIT, 'error' => PEAR_LOG_ERR, 'warning' => PEAR_LOG_WARNING, 'notice' => PEAR_LOG_NOTICE, 'info' => PEAR_LOG_INFO, 'debug' => PEAR_LOG_DEBUG)])
  • array $err: Error array
  • array $levels: Error level => Log constant map
_sortErrors (line 779)

Error sorting function, sorts by time

  • access: private
void _sortErrors (mixed $a, mixed $b)

Documentation generated on Fri, 11 Feb 2005 18:13:03 +0000 by phpDocumentor 1.3.0RC3