Flourish PHP Unframework

fException

Class Resources

Static Methods

Methods

Used By

abstract class, v1.0.0b8

An exception that allows for easy l10n, printing, tracing and hooking

Changes:
1.0.0b8Added a missing line of backtrace to formatTrace() 6/28/09
1.0.0b7Updated __construct() to no longer require a message, like the Exception class, and allow for non-integer codes 6/26/09
1.0.0b6Fixed splitMessage() so that the original message is returned if no list items are found, added reorderMessage() 6/2/09
1.0.0b5Added splitMessage() to replace fCRUDremoveListItems() and fCRUD::reorderListItems() 5/8/09
1.0.0b4Added a check to __construct() to ensure that the $code parameter is numeric 5/4/09
1.0.0b3Fixed a bug with printMessage() messing up some HTML messages 3/27/09
1.0.0b2compose() more robustly handles $components passed as an array, __construct() now detects stray % characters 2/5/09
1.0.0bThe initial implementation 6/14/07

Genealogy

Class Tree

Exception
   |
   --fException

Child Classes

fExpectedException
An exception that should be handled by the display code
fUnexpectedException
An exception that should probably not be handled by the display code, fCore::enableExceptionHandler() is recommended

Inherited Variables

$code
$file
$line
$message
$previous
$string
$trace

Inherited Methods

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

Static Methods

::compose() protected

Composes text using fText if loaded

Signature

string compose( string $message, mixed $component [, ... ] )

Parameters

string $message The message to compose
mixed $component [, ... ] A string or number to insert into the message

Returns

The composed and possible translated message

::dump() protected

Creates a string representation of any variable using predefined strings for booleans, NULL and empty strings

The string output format of this method is very similar to the output of print_r() except that the following values are represented as special strings:

  • TRUE: '{true}'
  • FALSE: '{false}'
  • NULL: '{null}'
  • '': '{empty_string}'

Signature

string dump( mixed $data )

Parameters

mixed $data The value to dump

Returns

The string representation of the value

::registerCallback() public

Adds a callback for when certain types of exceptions are created

The callback will be called when any exception of this class, or any child class, specified is tossed. A single parameter will be passed to the callback, which will be the exception object.

Signature

void registerCallback( callback $callback, string $exception_type=NULL )

Parameters

callback $callback The callback
string $exception_type The type of exception to call the callback for

Methods

->__construct() public

Sets the message for the exception, allowing for string interpolation and internationalization

The $message can contain any number of formatting placeholders for string and number interpolation via sprintf(). Any % signs that do not appear to be part of a valid formatting placeholder will be automatically escaped with a second %.

The following aspects of valid sprintf() formatting codes are not accepted since they are redundant and restrict the non-formatting use of the % sign in exception messages:

  • % 2d: Using a literal space as a padding character - a space will be used if no padding character is specified
  • %'.d: Providing a padding character but no width - no padding will be applied without a width

Signature

fException __construct( string $message='', mixed $component [, ... ], mixed $code )

Parameters

string $message The message for the exception. This accepts a subset of sprintf() strings - see method description for more details.
mixed $component [, ... ] A string or number to insert into the message
mixed $code The exception code to set

Overridden By

fValidationException::__construct()
Sets the message for the exception, allowing for custom formatting beyond fException

Overrides

Exception::constructor __construct ( [$message = ], [$code = ], [$previous = ] )

->__get() internal public

Please note: this method is public, however it is primarily intended for internal use by Flourish and will normally not be useful in site/application code

All requests that hit this method should be requests for callbacks

Signature

callback __get( string $method )

Parameters

string $method The method to create a callback for

Returns

The callback for the method requested

->formatTrace() public

Gets the backtrace to currently called exception

Signature

string formatTrace( )

Returns

A nicely formatted backtrace to this exception

->getCSSClass() protected

Returns the CSS class name for printing information about the exception

Signature

void getCSSClass( )

->prepare() protected

Prepares content for output into HTML

Signature

string prepare( $content )

Parameters

$content

Returns

The prepared content

->printMessage() public

Prints the message inside of a div with the class being 'exception %THIS_EXCEPTION_CLASS_NAME%'

Signature

void printMessage( )

Overridden By

fUnexpectedException::printMessage()
Prints out a generic error message inside of a div with the class being 'exception {exception_class_name}'

->printTrace() public

Prints the backtrace to currently called exception inside of a pre tag with the class being 'exception %THIS_EXCEPTION_CLASS_NAME% trace'

Signature

void printTrace( )

->reorderMessage() public

Reorders list items in the message based on simple string matching

Signature

fException reorderMessage( string $match [, ... ] )

Parameters

string $match [, ... ] This should be a string to match to one of the list items - whatever the order this is in the parameter list will be the order of the list item in the adjusted message

Returns

The exception object, to allow for method chaining

->setMessage() public

Allows the message to be overwriten

Signature

void setMessage( string $new_message )

Parameters

string $new_message The new message for the exception

->splitMessage() public

Splits an exception with an HTML list into multiple strings each containing part of the original message

This method should be called with two or more parameters of arrays of string to match. If any of the provided strings are matching in a list item in the exception message, a new copy of the message will be created containing just the matching list items.

Here is an exception message to be split:

The following problems were found:


    
    
  • First Name: Please enter a value
    • 
    
  • Last Name: Please enter a value
    • 
    
  • Email: Please enter a value
    • 
    
  • Address: Please enter a value
    • 
    
  • City: Please enter a value
    • 
    
  • State: Please enter a value
    • 
    
  • Zip Code: Please enter a value
    •

The following PHP would split the exception into two messages:

list ($name_exception, $address_exception) = $exception->splitMessage(
    array('First Name', 'Last Name', 'Email'),
    array('Address', 'City', 'State', 'Zip Code')
);

The resulting messages would be:

The following problems were found:


    
    
  • First Name: Please enter a value
    • 
    
  • Last Name: Please enter a value
    • 
    
  • Email: Please enter a value
    •

and

The following problems were found:


    
    
  • Address: Please enter a value
    • 
    
  • City: Please enter a value
    • 
    
  • State: Please enter a value
    • 
    
  • Zip Code: Please enter a value
    •

If no list items match the strings in a parameter, the result will be an empty string, allowing for simple display:

fHTML::show($name_exception, 'error');

An empty string is returned when none of the list items matched the strings in the parameter. If no list items are found, the first value in the returned array will be the existing message and all other array values will be an empty string.

Signature

array splitMessage( array $list_item_matches [, ... ] )

Parameters

array $list_item_matches [, ... ] An array of strings to filter the list items by, list items will be ordered in the same order as this array

Returns

This will contain an array of strings corresponding to the parameters passed - see method description for details