Provides low-level debugging, error and exception functionality
1.0.0b24 | Backwards Compatibility Break - moved detectOpcodeCache() to fLoader::hasOpcodeCache() 8/26/11 |
---|---|
1.0.0b23 | Backwards Compatibility Break - changed the email subject of error/exception emails to include relevant file info, instead of the timestamp, for better email message threading 6/20/11 |
1.0.0b22 | Fixed a bug with dumping arrays containing integers 5/26/11 |
1.0.0b21 | Changed startErrorCapture() to allow "stacking" it via multiple calls, fixed a couple of bugs with dump() mangling strings in the form int(1), fixed mispelling of occurred 5/9/11 |
1.0.0b20 | Backwards Compatibility Break - Updated expose() to not wrap the data in HTML when running via CLI, and instead just append a newline 2/24/11 |
1.0.0b19 | Added detection of AIX to checkOS() 1/19/11 |
1.0.0b18 | Updated expose() to be able to accept multiple parameters 1/10/11 |
1.0.0b17 | Fixed a bug with backtrace() triggering notices when an argument is not UTF-8 8/17/10 |
1.0.0b16 | Added the $types and $regex parameters to startErrorCapture() and the $regex parameter to stopErrorCapture() 8/9/10 |
1.0.0b15 | Added startErrorCapture() and stopErrorCapture() 7/5/10 |
1.0.0b14 | Changed enableExceptionHandling() to only call fException::printMessage() when the destination is not html and no callback has been defined, added configureSMTP() to allow using fSMTP for error and exception emails 6/4/10 |
1.0.0b13 | Added the $backtrace parameter to backtrace() 3/5/10 |
1.0.0b12 | Added getDebug() to check for the global debugging flag, added more specific BSD checks to checkOS() 3/2/10 |
1.0.0b11 | Added detectOpcodeCache() 10/6/09 |
1.0.0b10 | Fixed expose() to properly display when output includes non-UTF-8 binary data 6/29/09 |
1.0.0b9 | Added disableContext() to remove context info for exception/error handling, tweaked output for exceptions/errors 6/28/09 |
1.0.0b8 | enableErrorHandling() and enableExceptionHandling() now accept multiple email addresses, and a much wider range of emails 6/1/09 |
1.0.0b7 | backtrace() now properly replaces document root with {doc_root} on Windows 5/2/09 |
1.0.0b6 | Fixed a bug with getting the server name for error messages when running on the command line 3/11/09 |
1.0.0b5 | Fixed a bug with checking the error/exception destination when a log file is specified 3/7/09 |
1.0.0b4 | Backwards compatibility break - getOS() and getPHPVersion() removed, replaced with checkOS() and checkVersion() 2/16/09 |
1.0.0b3 | handleError() now displays what kind of error occurred as the heading 2/15/09 |
1.0.0b2 | Added registerDebugCallback() 2/7/09 |
1.0.0b | The initial implementation 9/25/07 |
Creates a nicely formatted backtrace to the the point where this method is called
string backtrace( integer $remove_lines=0, array $backtrace=NULL )
integer | $remove_lines | The number of trailing lines to remove from the backtrace |
array | $backtrace | A backtrace from debug_backtrace() to format - this is not usually required or desired |
The formatted backtrace
Performs a call_user_func(), while translating PHP 5.2 static callback syntax for PHP 5.1 and 5.0
Parameters can be passed either as a single array of parameters or as multiple parameters.
// Passing multiple parameters in a normal fashion
fCore::call('Class::method', TRUE, 0, 'test');
// Passing multiple parameters in a parameters array
fCore::call('Class::method', array(TRUE, 0, 'test'));
To pass parameters by reference they must be assigned to an array by reference and the function/method being called must accept those parameters by reference. If either condition is not met, the parameter will be passed by value.
// Passing parameters by reference
fCore::call('Class::method', array(&$var1, &$var2));
mixed call( callback $callback, array $parameters=array() )
callback | $callback | The function or method to call |
array | $parameters | The parameters to pass to the function/method |
The return value of the called function/method
Translates a Class::method style static method callback to array style for compatibility with PHP 5.0 and 5.1 and built-in PHP functions
array callback( callback $callback )
callback | $callback | The callback to translate |
The translated callback
Returns is the current OS is one of the OSes passed as a parameter
Valid OS strings are:
boolean checkOS( string $os [, ... ] )
string | $os [, ... ] | The operating system to check - see method description for valid OSes |
If the current OS is included in the list of OSes passed as parameters
Checks to see if the running version of PHP is greater or equal to the version passed
boolean checkVersion( $version )
$version |
If the running version of PHP is greater or equal to the version passed
Sets an fSMTP object to be used for sending error and exception emails
void configureSMTP( fSMTP $smtp, string $from_email )
fSMTP | $smtp | The SMTP connection to send emails over |
string | $from_email | The email address to use in the From: header |
Prints a debugging message if global or code-specific debugging is enabled
void debug( string $message, boolean $force=FALSE )
string | $message | The debug message |
boolean | $force | If debugging should be forced even when global debugging is off |
Disables including the context information with exception and error messages
The context information includes the following superglobals:
void disableContext( )
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:
string dump( mixed $data )
mixed | $data | The value to dump |
The string representation of the value
Enables debug messages globally, i.e. they will be shown for any call to debug()
void enableDebugging( boolean $flag )
boolean | $flag | If debugging messages should be shown |
Turns on a feature where undefined constants are automatically created with the string value equivalent to the name
This functionality only works if enableErrorHandling() has been called first. This functionality may have a very slight performance impact since a E_STRICT error message must be captured and then a call to define() is made.
void enableDynamicConstants( )
Turns on developer-friendly error handling that includes context information including a backtrace and superglobal dumps
All errors that match the current error_reporting() level will be redirected to the destination and will include a full backtrace. In addition, dumps of the following superglobals will be made to aid in debugging:
The superglobal dumps are only done once per page, however a backtrace in included for each error.
If an email address is specified for the destination, only one email will be sent per script execution. If both error and exception handling are set to the same email address, the email will contain both errors and exceptions.
void enableErrorHandling( string $destination )
string | $destination | The destination for the errors and context information - an email address, a file path or the string 'html' |
Turns on developer-friendly uncaught exception handling that includes context information including a backtrace and superglobal dumps
Any uncaught exception will be redirected to the destination specified, and the page will execute the $closing_code callback before exiting. The destination will receive a message with the exception messaage, a full backtrace and dumps of the following superglobals to aid in debugging:
The superglobal dumps are only done once per page, however a backtrace in included for each error.
If an email address is specified for the destination, only one email will be sent per script execution.
If an email address is specified for the destination, only one email will be sent per script execution. If both exception and error handling are set to the same email address, the email will contain both exceptions and errors.
void enableExceptionHandling( string $destination, callback $closing_code=NULL, array $parameters=array() )
string | $destination | The destination for the exception and context information - an email address, a file path or the string 'html' |
callback | $closing_code | This callback will happen after the exception is handled and before page execution stops. Good for printing a footer. If no callback is provided and the exception extends fException, fException::printMessage() will be called. |
array | $parameters | The parameters to send to $closing_code |
Prints the dump() of a value
The dump will be printed in a <pre> tag with the class exposed if PHP is running anywhere but via the command line (cli). If PHP is running via the cli, the data will be printed, followed by a single line break (\n).
If multiple parameters are passed, they are exposed as an array.
void expose( mixed $data [, ... ] )
mixed | $data [, ... ] | The value to show |
If debugging is enabled
boolean getDebug( boolean $force=FALSE )
boolean | $force | If debugging is forced |
If debugging is enabled
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
Handles an error, creating the necessary context information and sending it to the specified destination
void handleError( integer $error_number, string $error_string, string $error_file=NULL, integer $error_line=NULL, array $error_context=NULL )
integer | $error_number | The error type |
string | $error_string | The message for the error |
string | $error_file | The file the error occurred in |
integer | $error_line | The line the error occurred on |
array | $error_context | A references to all variables in scope at the occurence of the error |
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
Handles an uncaught exception, creating the necessary context information, sending it to the specified destination and finally executing the closing callback
void handleException( object $exception )
object | $exception | The uncaught exception to handle |
Registers a callback to handle debug messages instead of the default action of calling expose() on the message
void registerDebugCallback( callback $callback )
callback | $callback | A callback that accepts a single parameter, the string debug message to handle |
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
Resets the configuration of the class
void reset( )
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
Sends an email or writes a file with messages generated during the page execution
This method prevents multiple emails from being sent or a log file from being written multiple times for one script execution.
void sendMessagesOnShutdown( )
Temporarily enables capturing error messages
void startErrorCapture( integer $types=NULL, string $regex=NULL )
integer | $types | The error types to capture - this should be as specific as possible - defaults to all (E_ALL | E_STRICT) |
string | $regex | A PCRE regex to match against the error message |
Stops capturing error messages, returning all that have been captured
array stopErrorCapture( string $regex=NULL )
string | $regex | A PCRE regex to filter messages by |
The captured error messages