API: The Exceptable Interface

at\exceptable\Exceptable

An augmented interface for php exceptions. Exceptable extends the Throwable interface with a severity rating, various utility methods, and a specialized (but backwards compatible) constructor.

cautions on implementation:

• the implementing class must extend from a Throwable class (e.g., Exception).
• implementations cannot extend from PDOException, because it breaks the Throwable interface (its getCode() returns a string).

constants

• ERROR
  An Exceptable of high severity, comparable to E_ERROR or E_USER_ERROR.

• WARNING
  An Exceptable of medium severity, comparable to E_WARNING or E_USER_WARNING.

• NOTICE
  An Exceptable of low severity, comparable to E_NOTICE or E_USER_NOTICE.

• DEFAULT_CODE
  If no code is provided to an Exceptable, it defaults to 0.

• DEFAULT_MESSAGE
  If no message is provided to an Exceptable, it defaults to "" (empty string).

• DEFAULT_SEVERITY
  If no severity is provided to an Exceptable, it defaults to Exceptable::ERROR.

static methods

public static array get_info( int $code )

Gets information about an error case identified by the given code.

• parameters:
  • int $code
    The exceptable code to look up
• throws:
  • at\exceptable\ExceptableException
    If the code is not known to the implementation
• returns: array
  A map of info about the code, including (at a minimum) its "code", "severity", and "message"

public static bool has_info( int $code )

Checks whether there is an error case associated with the given code.

• parameters:
  • int $code The exceptable code to look up
• returns: bool
  True if the code identifies a known error case; false otherwise

instance methods

public __construct( ...$arguments )

The exceptable constructor.
Constructor arguments are the same as those on the Throwable interface — $message, $code, and $previous — with an additional argument $context which accepts an array of values you provide (typically, details for the exception message).

Constructor arguments are all optional; any or all may be omitted (but their order must be preserved; e.g., $previous may not appear before $message).

• parameters:
  • string $message
    The Exceptable message. If omitted, a default message will be set based on the Exceptable code.
  • int $code
    The Exceptable code. If omitted, a default code (defined by the implementing class) will be set.
  • Throwable $previous
    The previous Exception, if any.
  • array $context
    Contextual information about the Exceptable. Typically, used to provide details for the Exceptable message, but may include any information that should be available later (e.g., to loggers).
• throws:
  • at\exceptable\ExceptableException
    If constructor arguments are invalid and/or out of order.

public Exceptable addContext( array $context )

Adds contextual information to the Exceptable. This will be added to any information passed to the constructor.

• parameters:
  • array $context
    Key → value map of information to add. User-provided keys should not begin with a double underscore (__) as these are reserved for internal use.
• returns: at\exceptable\Exceptable
  The Exceptable instance.

public array getContext( void )

Gets contextual information about this Exceptable.

• returns: array
  A map of contextual information about the Exceptable. Keys will vary depending on what information was provided at runtime. At a minimum, will include "__severity__" (the Exceptable's severity) and "__rootMessage__" (if a previous exception exists).

public Throwable getRoot( void )

Traverses the chain of previous exception(s) and gets the root exception.

• returns: Throwable
  The root exception (which will be the Exceptable instance if no previous exception exists).

public int getSeverity( void )

Gets the Exceptable severity.

• returns: int
  One of Exceptable::ERROR, Exceptable::WARNING, or Exceptable::NOTICE.

public bool isError( void )

Checks the Exceptable severity.

• returns: bool
  True if the Exceptable severity is Exceptable::ERROR; false otherwise.

public bool isWarning( void )

Checks the Exceptable severity.

• returns: bool
  True if the Exceptable severity is Exceptable::WARNING; false otherwise.

public bool isNotice( void )

Checks the Exceptable severity.

• returns: bool
  True if the Exceptable severity is Exceptable::NOTICE; false otherwise.

public Exceptable setSeverity( int $severity )

Sets the Exceptable severity.

• params:
  • int $severity
    The severity to set. Must be one of Exceptable::ERROR, Exceptable::WARNING, or Exceptable::NOTICE.
• throws:
  • ExceptableException
    If the given severity is invalid.
• returns: at\exceptable\Exceptable
  The Exceptable instance.