fCorestatic classv1.0.0b17
Provides low-level debugging, error and exception functionality
| 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 occured as the heading 2/15/09 |
| 1.0.0b2 | Added registerDebugCallback() 2/7/09 |
| 1.0.0b | The initial implementation 9/25/07 |
Static Methods
::backtrace() public
Creates a nicely formatted backtrace to the the point where this method is called
Signature
string backtrace( integer $remove_lines=0, array $backtrace=NULL )
Parameters
| 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 |
Returns
The formatted backtrace
::call() public
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));
Signature
mixed call( callback $callback, array $parameters=array() )
Parameters
| callback | $callback | The function or method to call |
| array | $parameters | The parameters to pass to the function/method |
Returns
The return value of the called function/method
::callback() public
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
Signature
array callback( callback $callback )
Parameters
| callback | $callback | The callback to translate |
Returns
The translated callback
::checkOS() public
Returns is the current OS is one of the OSes passed as a parameter
Valid OS strings are:
- 'linux'
- 'bsd'
- 'osx'
- 'solaris'
- 'windows'
Signatures
boolean checkOS( string $os )
boolean checkOS( string .. )
Parameters
| string | $os | The operating system to check - see method description for valid OSes |
| string | .. | ... |
Returns
If the current OS is included in the list of OSes passed as parameters
::checkVersion() public
Checks to see if the running version of PHP is greater or equal to the version passed
Signature
boolean checkVersion( $version )
Parameters
| $version |
Returns
If the running version of PHP is greater or equal to the version passed
::configureSMTP() public
Sets an fSMTP object to be used for sending error and exception emails
Signature
void configureSMTP( fSMTP $smtp, string $from_email )
Parameters
| fSMTP | $smtp | The SMTP connection to send emails over |
| string | $from_email | The email address to use in the From: header |
::debug() public
Prints a debugging message if global or code-specific debugging is enabled
Signature
void debug( string $message, boolean $force=FALSE )
Parameters
| string | $message | The debug message |
| boolean | $force | If debugging should be forced even when global debugging is off |
::detectOpcodeCache() public
Detects if a PHP opcode cache is installed
The following opcode caches are currently detected:
Signature
boolean detectOpcodeCache( )
Returns
If a PHP opcode cache is loaded
::disableContext() public
Disables including the context information with exception and error messages
The context information includes the following superglobals:
- $_SERVER
- $_POST
- $_GET
- $_SESSION
- $_FILES
- $_COOKIE
Signature
void disableContext( )
::dump() public
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
::enableDebugging() public
Enables debug messages globally, i.e. they will be shown for any call to debug()
Signature
void enableDebugging( boolean $flag )
Parameters
| boolean | $flag | If debugging messages should be shown |
::enableDynamicConstants() public
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.
Signature
void enableDynamicConstants( )
::enableErrorHandling() public
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:
- $_SERVER
- $_POST
- $_GET
- $_SESSION
- $_FILES
- $_COOKIE
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.
Signature
void enableErrorHandling( string $destination )
Parameters
| string | $destination | The destination for the errors and context information - an email address, a file path or the string 'html' |
::enableExceptionHandling() public
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:
- $_SERVER
- $_POST
- $_GET
- $_SESSION
- $_FILES
- $_COOKIE
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.
Signature
void enableExceptionHandling( string $destination, callback $closing_code=NULL, array $parameters=array() )
Parameters
| 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 |
::expose() public
Prints the dump() of a value in a pre tag with the class exposed
Signature
void expose( mixed $data )
Parameters
| mixed | $data | The value to show |
::getDebug() public
If debugging is enabled
Signature
boolean getDebug( boolean $force=FALSE )
Parameters
| boolean | $force | If debugging is forced |
Returns
If debugging is enabled
::handleError() 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
Handles an error, creating the necessary context information and sending it to the specified destination
Signature
void handleError( integer $error_number, string $error_string, string $error_file=NULL, integer $error_line=NULL, array $error_context=NULL )
Parameters
| integer | $error_number | The error type |
| string | $error_string | The message for the error |
| string | $error_file | The file the error occured in |
| integer | $error_line | The line the error occured on |
| array | $error_context | A references to all variables in scope at the occurence of the error |
::handleException() 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
Handles an uncaught exception, creating the necessary context information, sending it to the specified destination and finally executing the closing callback
Signature
void handleException( object $exception )
Parameters
| object | $exception | The uncaught exception to handle |
::registerDebugCallback() public
Registers a callback to handle debug messages instead of the default action of calling expose() on the message
Signature
void registerDebugCallback( callback $callback )
Parameters
| callback | $callback | A callback that accepts a single parameter, the string debug message to handle |
::reset() 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
Resets the configuration of the class
Signature
void reset( )
::sendMessagesOnShutdown() 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
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.
Signature
void sendMessagesOnShutdown( )
::startErrorCapture() public
Temporarily enables capturing error messages
Signature
void startErrorCapture( integer $types=NULL, string $regex=NULL )
Parameters
| 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 |
::stopErrorCapture() public
Stops capturing error messages, returning all that have been captured
Signature
array stopErrorCapture( string $regex=NULL )
Parameters
| string | $regex | A PCRE regex to filter messages by |
Returns
The captured error messages
