Class Nexista_Error

Description
Description | Vars | Methods (details)

The Nexista error system is Exception based and provides a method for calling custom handler for each error type.

The extension class Nexista_used by Nexista extends from the standard PHP5 Exception class Nexista_with added functionality. It aims to be self supporting meaning that try/catch blocks do not need to be called.

Each place where an error might happen has the directive:

  1. Error::init('message', ERROR_CODE, 'optional handler');
When the error handling receives this call, it will verify if a handler has been defined. If so, it will call the handler with the error and the code and let it handle it. If no handler is specified, it will then see if the ERROR_CODE is listed. The current standard error codes as NX_ERROR_FATAL (which halts the script), NX_ERROR_WARNING and NX_ERROR_NOTICE. If the error code does is not listed it will then throw the exception.

Each class Nexista_or functionality group can have it's own error codes and handlers. For example, a database class Nexista_might have:

  1.  if(!connectToDB())
  2.  {
  3.      Error::init('A DB connection could not be made', NX_ERROR_DB_CONNECT, 'errorHandler');
  4.  }
  5.  
  6.  function errorHandler($exception, $errorCode)
  7.  {
  8.      switch($errorCode)
  9.      {
  10.          case NX_ERROR_DB_CONNECT:
  11.              ...use alternate DB connection or retry
  12.              break;
  13.          default:
  14.              trow($e);
  15.              break;
  16.      }
  17. }
In the case above, the error code indicated will cause an attempt to restore the connection.

The error system does not log or display errors by default. Observers need to be setup in the prepend file in order to do so:

  1. Error::addObserver('display', 'observerDisplay');
  2.  
  3.  function observerDisplay($e)
  4.  {
  5.      //display the error
  6.      $e->toHtml();
  7.  
  8.      //do additional stuff such as log error, email webmaster, etc... as desired
  9.  }
Important! the Error::toHtml() method displays a lot of information that could treaten the security of the application. Be sure to employ proper security measures such as showing an error message with a link to a role secure popup page which calls the function.

Credits: This class Nexista_was inspired by the PEAR_Exception class

Located in /kernel/error.php (line 84) 

Exception
   |
   --Nexista_Error
Method Summary
Description | Vars | Methods (details)
static void addObserver (string $name, mixed $callback)
static void init (string $text, [int $code = null], [mixed $handler = null])
static void registerDefaultHandler (mixed $handler)
static void removeObserver (string $name)
Nexista_Error __construct ( $message, [ $code = null], [ $handler = null])
void disableObservers ([string $name = null])
void enableObservers ([string $name = null])
string getErrorClass ()
string getErrorMethod ()
array getTraceSafe ()
string outputXml ()
void processHandler ()
void toHtml ()
void toText ()
void triggerObservers ()
Variables
Description | Vars (details) | Methods (details)

Inherited Variables

Inherited from Exception (Internal Class)

$code
 $file
 $line
 $message
 $string
 $trace
Methods
Description | Vars Methods (details)
static addObserver (line 180)

Adds an observer function

All registered observers are called when an exception occurs and can be used to display,log, notify.

  • access: public
void addObserver (string $name, mixed $callback)
  • string $name: name of the observer.
  • mixed $callback: a valid php callback handler
static init (line 163)

Inits a new Exception with optional handler

This static method is called instead of a throw command. It instanciates a new execption and allows for an optional handler to be defined to handle the exception

  • access: public
void init (string $text, [int $code = null], [mixed $handler = null])
  • string $text: error message
  • int $code: error code
  • mixed $handler: a valid php callback handler
static registerDefaultHandler (line 410)

Registers a function to be called on error if no custom handlers are defined

This method allows a callable function to be called for standard errors (i.e. NX_ERROR_FATAL, NX_ERROR_WARNING) to override the default actions. Note that if a custome handler for an error is defined in the Error:init() arguments, this function will never be called. This function should accept 1 argument: a reference to the current Error object.

  • access: public
void registerDefaultHandler (mixed $handler)
  • mixed $handler: a function or an array of class=>method
static removeObserver (line 193)

Removes an observer

  • access: public
void removeObserver (string $name)
  • string $name: observer name
Constructor __construct (line 120)

Instantiates a new Nexista Exception

  • access: public
Nexista_Error __construct ( $message, [ $code = null], [ $handler = null])
  • $message
  • $code
  • $handler
Redefinition of:
Exception::constructor __construct ( [$message = ], [$code = ] )
disableObservers (line 223)

Disable all or one observer

When an external handler is used, it may be desirable not to call the observer(s). This method can be used to do so.

  • access: public
void disableObservers ([string $name = null])
  • string $name: (optional) observer name. If no name is given, then all observers will be disabled
enableObservers (line 238)

Enable previously disabled observer(s)

  • access: public
void enableObservers ([string $name = null])
  • string $name: (optional) observer name. If no name is given, then all observers will be enabled.
getErrorClass (line 290)

Returns class Nexista_where exception occured

  • return: error class
  • access: public
string getErrorClass ()
getErrorMethod (line 301)

Returns method where exception occured

  • return: error function
  • access: public
string getErrorMethod ()
getTraceSafe (line 273)

Returns error trace

  • return: error backtrace
  • access: public
array getTraceSafe ()
outputXml (line 313)

Outputs error as XML

  • return: XML error
  • access: public
string outputXml ()
processHandler (line 202)

Runs a user provided function to deal with this exception

  • access: protected
void processHandler ()
toHtml (line 365)

Transforms and outputs XML error with XSL

  • access: public
void toHtml ()
toText (line 392)

Outputs error as string

  • access: public
void toText ()
triggerObservers (line 255)

Activate observers

This method is triggered by the Error::init() method when no handlers are defined and will call all registered observers. It is up to the handler, if defined, to call this method.

  • access: public
void triggerObservers ()

Inherited Methods

Inherited From Exception (Internal Class)

constructor __construct ( [$message = ], [$code = ] )
getCode ( )
getFile ( )
getLine ( )
getMessage ( )
getTrace ( )
getTraceAsString ( )
__clone ( )
__toString ( )

Documentation generated on Tue, 11 Mar 2008 23:23:00 -0400 for Nexista 0.2.0