Flourish PHP Unframework

fCore

static class, v1.0.0b24

Provides low-level debugging, error and exception functionality

Changes:
1.0.0b24Backwards Compatibility Break - moved detectOpcodeCache() to fLoader::hasOpcodeCache() 8/26/11
1.0.0b23Backwards 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.0b22Fixed a bug with dumping arrays containing integers 5/26/11
1.0.0b21Changed 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.0b20Backwards 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.0b19Added detection of AIX to checkOS() 1/19/11
1.0.0b18Updated expose() to be able to accept multiple parameters 1/10/11
1.0.0b17Fixed a bug with backtrace() triggering notices when an argument is not UTF-8 8/17/10
1.0.0b16Added the $types and $regex parameters to startErrorCapture() and the $regex parameter to stopErrorCapture() 8/9/10
1.0.0b15Added startErrorCapture() and stopErrorCapture() 7/5/10
1.0.0b14Changed 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.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 occurred 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'
  • 'aix'
  • 'bsd'
  • 'freebsd'
  • 'netbsd'
  • 'openbsd'
  • '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

::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

::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

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.

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 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

::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