fCorestatic classv1.0.0b13

Provides low-level debugging, error and exception functionality

Changes:
1.0.0b13Added the $backtrace parameter to backtrace() 3/5/10
1.0.0b12Added getDebug() to check for the global debugging flag, added more specific BSD checks to checkOS() 3/2/10
1.0.0b11Added detectOpcodeCache() 10/6/09
1.0.0b10Fixed expose() to properly display when output includes non-UTF-8 binary data 6/29/09
1.0.0b9Added disableContext() to remove context info for exception/error handling, tweaked output for exceptions/errors 6/28/09
1.0.0b8enableErrorHandling() and enableExceptionHandling() now accept multiple email addresses, and a much wider range of emails 6/1/09
1.0.0b7backtrace() now properly replaces document root with {doc_root} on Windows 5/2/09
1.0.0b6Fixed a bug with getting the server name for error messages when running on the command line 3/11/09
1.0.0b5Fixed a bug with checking the error/exception destination when a log file is specified 3/7/09
1.0.0b4Backwards compatibility break - getOS() and getPHPVersion() removed, replaced with checkOS() and checkVersion() 2/16/09
1.0.0b3handleError() now displays what kind of error occured as the heading 2/15/09
1.0.0b2Added registerDebugCallback() 2/7/09
1.0.0bThe 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'

Signature

boolean checkOS( string $os )

Parameters

string $os [, ... ] The operating system to check - see method description for valid OSes

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

::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.
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( )