<<css mode="next" class="sidebar"></css>> (((
- '''<a href="/docs/fCore">Class Documentation</a>''' - <a href="/api/fCore">API Reference</a> - <a href="https://github.com/flourishlib/flourish-classes/blob/master/fCore.php" target="_blank">Source Code</a>
<<toc></toc>> )))
The fCore class centralizes debugging, error and exception handling and more.
When maintaining production systems, knowing about errors and unhandled exceptions that have occurred is key. The fCore class provides two handy methods to simply this task.
The ::enableErrorHandling() and ::enableExceptionHandling() methods each take a first parameter that is the destination for errors and unhandled exceptions respectively. The options are an email address, a file, or the string `'html'` for output into the currently rendering page.
Since unhandled exceptions cause the page execution to stop immediately, ::enableExceptionHandling() takes a callback as a second parameter to allow you to cleanly finish HTML output. The optional third parameter is an array of parameters to send to the callback.
Both the error and exception handling provide full backtraces, allowing for an easy time finding bugs.
Multiple email addresses may be specified, separated by commas.
By default, error and exception output includes a dump of the state of a number of PHP superglobals including `$_GET`, `$_POST`, `$_FILES`, `$_COOKIE`, `$_SESSION` and `$_SERVER` to aid in debugging. It is possible to disable this functionality by calling ::disableContext().
By default, error and exception emails are sent using the `mail()` function. An SMTP server may be used by passing an instance of fSMTP and a `From` email address to ::configureSMTP().
While exceptions are fairly easy to use due to the way they bubble up to the closest matching `catch` block, errors in PHP are not as simple. Errors don't interrupt program flow and can only be captured by an error handler. ::startErrorCapture() and ::stopErrorCapture() provide functionality that allows capturing errors and returning them in an array for futher processing.
While a similar result can be accomplished by using the `error_reporting()` function and simplying lowering the error reporting level, this may not be available if it has been set via the `php_admin_value` Apache configuration directive.
In addition, turning down `error_reporting()` does not allow for acting upon errors, just silencing them. Since `stopErrorCapture()` returns an array of information about each error that occurred, the messages can be used to determine the next course of action or combined into an exception.
It is possible to capture only specific `$types` of errors by passing them as the first parameter to `startErrorCapture()`. The values are the same as those passed to `error_reporting()`, a bitmask of the desired error types. The captured messages can be further restricted by passing a PCRE `$regex` as the second parameter. Any errors that are not captured are passed on to the normal error handler.
Please note that all errors that match `$types` will be captured, even if they are excluded by the current `error_reporting()` setting.
It is also possible to capture all errors, but only return some from `stopErrorCapture()`. This is accomplished by by passing a PCRE `$regex` as the first parameter.
fCore provides a few useful functions when you are trying to debug code. The simplest way to debug is to use the ::expose() method to show the contents of a file. ::expose() creates output similar to `print_r()`, however it uses symbols to differentiate between ``, `NULL` and `FALSE`. Here is a usage example.
The above call to ::expose() would create the following HTML:
If you want to set your code up to conditionally display debugging information, you’ll want to use the ::debug() method. Content sent to ::debug() is displayed via ::expose() only if ::enableDebugging() has been passed `TRUE` or if the second parameter, `$force`, is `TRUE`.
If you wish to pass debug information to another debugging or logging system, a callback can be registered via the static method ::registerDebugCallback(). This method accepts a single parameter, the `$callback` to send all debug messages to. The `$callback` should accept a single parameter, a string debug message.
The ::backtrace() method provides a compact and nicely formatted version of `debug_backtrace()`. Below is an example of usage:
Which would produce the following HTML:
In some situations it is necessary to write code based on the version of PHP or the operating system the code is running on.
The static method ::checkVersion() will return `TRUE` if the currently running version of PHP is greater or equal to the version string passed in.
The static method ::checkOS() will return `TRUE` if the current operating system is one of the OSes passed in as a parameter. Valid operating system strings include:
- `'linux'` - `'bsd'` - `'osx'` - `'solaris'` - `'windows'`