Exception
└─SwatException
public class SwatException
extends Exception
| Field Summary | |
|---|---|
| protected mixed | |
| protected mixed | |
| protected static SwatExceptionDisplayer | |
| protected static SwatExceptionLogger | |
| Constructor Summary | |
|---|---|
SwatException(mixed message, mixed code) |
|
| Method Summary | |
|---|---|
| void | display() Displays this exception. |
| protected void | Displays style sheet required for XHMTL exception formatting. |
| protected string | formatSensitiveParam(string name, mixed value) Removes sensitive information from a parameter value and formats the parameter as a string. |
| protected string | formatValue(mixed value) Formats a parameter value for display in a stack trace. |
| protected string | getArguments(array args, string function, string class) Formats a method call's arguments. |
| string | getClass() Gets the name of the class this exception represents. |
| string | Gets a one-line short text summary of this exception. |
| static void | handle(Exception e) Handles an exception. |
| protected boolean | isSensitiveParameter(ReflectionFunctionAbstract method, string name) Detects whether or not a parameter is sensitive from the method-level documentation of the parameter's method. |
| void | log() Logs this exception. |
| void | process(boolean exit, boolean handled) Processes this exception. |
| static void | setDisplayer(SwatExceptionDisplayer displayer) Sets the object that displays SwatException objects when they are processed. |
| static void | setLogger(SwatExceptionLogger logger) Sets the object that logs SwatException objects when they are processed. |
| static void | setupHandler(string class) Set the PHP exception handler to use SwatException. |
| string | toString() Gets this exception as a nicely formatted text block. |
| string | toXHTML() Gets this exception as a nicely formatted XHTML fragment. |
| boolean | Gets whether or not this exception was manually handled. |
protected mixed $backtrace = null
protected mixed $class = null
protected static SwatExceptionDisplayer $displayer = null
protected static SwatExceptionLogger $logger = null
public SwatException(mixed message, mixed code)
public void display()
Displays this exception
This exception is displayed as either text or XHMTL depending on the current execution context. If there is a request URI, this exception is displayed as XHTML. Otherwise, this exception is displayed as text.
protected void displayStyleSheet()
Displays style sheet required for XHMTL exception formatting
This is purposly not in a separate file so that even if this exception causes problems including other files the exception styles will be displayed.
protected string formatSensitiveParam(string name, mixed value)
Removes sensitive information from a parameter value and formats the parameter as a string
This is used, for example, to filter credit/debit card numbers from stack traces. By default, a string of the form "[$name FILTERED]" is returned.
name - the name of the parameter.value - the sensitive value of the parameter.protected string formatValue(mixed value)
Formats a parameter value for display in a stack trace
value - the value of the parameter.protected string getArguments(array args, string function, string class)
Formats a method call's arguments
This method is also responsible for filtering sensitive parameters out of the final stack trace.
args - an array of arguments.function - optional. The current method or function.class - optional. The current class name.public string getClass()
Gets the name of the class this exception represents
This is usually, but not always, equivalent to get_class($this).
public string getSummary()
Gets a one-line short text summary of this exception
This summary is useful for log entries and error email titles.
public static void handle(Exception e)
Handles an exception
Wraps a generic exception in a SwatException object and process the SwatException object.
e - the exception to handle.protected boolean isSensitiveParameter(ReflectionFunctionAbstract method, string name)
Detects whether or not a parameter is sensitive from the method-level documentation of the parameter's method
Parameters with the following docblock tag are considered sensitive:
<?php
/**
* @sensitive $parameter_name
?>
method - the method the parameter to which the parameter belongs.name - the name of the parameter.public void log()
Logs this exception
The exception is logged to the webserver error log.
public void process(boolean exit, boolean handled)
Processes this exception
Processing involves displaying errors, logging errors and sending error message emails
exit - optional. Whether or not to exit after processing this exception. If unspecified, defaults to true.handled - optional. Whether or not this exception was manually handled. If unspecified defaults to true. Usually this parameter should be true if you catch an exception and manually call process on the exception.public static void setDisplayer(SwatExceptionDisplayer displayer)
Sets the object that displays SwatException objects when they are processed
For example:
<?php
SwatException::setDisplayer(new SilverorangeDisplayer());
?>
displayer - the object to use to display exceptions.public static void setLogger(SwatExceptionLogger logger)
Sets the object that logs SwatException objects when they are processed
For example:
<?php
SwatException::setLogger(new CustomLogger());
?>
logger - the object to use to log exceptions.public static void setupHandler(string class)
Set the PHP exception handler to use SwatException
class - the exception class containing a static handle() method.public string toString()
Gets this exception as a nicely formatted text block
This is useful for text-based logs and emails.
public string toXHTML()
Gets this exception as a nicely formatted XHTML fragment
This is nice for debugging errors on a staging server.
public boolean wasHandled()
Gets whether or not this exception was manually handled
An exception in Swat
Exceptions in Swat have handy methods for outputting nicely formed error messages. Call SwatException::setupHandler() to register SwatException as the PHP exception handler. The SwatException handler is able to handle all sub-classes of Exception by internally wrapping non-SwatExceptions in a new instance of a SwatException. This allows all exceptions to be nicely formatted and processed consistently.
Custom displaying and logging of SwatExceptions can be achieved through
SwatException::setLogger()andSwatException::setDisplayer().Filtering Sensitive Data out of Stack Traces:
By default, SwatException displays and logs stack traces that containing all calling information and passed parameters. Sometimes, a methods parameters may contain sensitive data. For exmaple, credit card numbers should not be displayed in stack traces. To filter sensitive data out of stack traces generated by SwatException, add the following documentation tag to the method-level documentation:
Any parameter having the @sensitive tag in its method-level documentation will be filtered out of stack traces. IMPORATNT: Each tag can only filter one parameter. Use multiple @sensitive documentation tags to filter multiple parameters in a single method.<?php
/**
* @sensitive $parameter_name
?>