RHJ4 Diagnostics

The following code values are supported:

enable [true|false<- default] Enables logging on this page.

disable [true|false<- default] Disables logging on this page.

threshold [0 | integer value] Sets diagnostic threshold level. Only messages with this threshold or lower will be logged.

save [true|false<- default] Used with Enable, Disable and Threshold to save settings
to database. To enable diagnostics for all pages:

[rhj4_diagnostics enable=true save=true]

show [true|false<- default] Displays current log file contents.

clear [true|false<- default] Deletes current log file.

options [true|false<- default] Displays current option values on page.

demo [true|false<- default] Shows a demonstration of many ways of using this plugin.

test [true|false<- default] Performs some diagnostic tests on the code.

options [true|false<- default] Shows the current option values.

verbose [true|false<- default] Echos diagnostic information on the page.

log [true|false<- default] Writes a diagnostic to the log. Requires message. For example:

    [rhj4_diagnostics log=true message='log this message']

message = is used with notify and log to define the message to be sent.

notify [true|false<- default] Displays a notification popup using RHJ4Notifications. Requires message and uses sticky and type.

    [rhj4_diagnostics notify=true message='show this message in popup' sticky=true, type=NOTIFICATION_TYPE_WARNING]

sticky [true|false<- default] is used with notify to indicate whether the notification message is “sticky”, i.e. will stay visible on the screen until a page turn or the message is deleted.

type = (NOTIFICATION_TYPE_CONFIRMATION<- default) indicates the type of notification to be generated.

Example:

    [rhj4_diagnostics enable=true show=true clear=true show_options=true]

Will produce:

Options

array (size=6)
'enabled' => int 1
'threshold' => int 10
'output' => string 'rhj4_log' (length=8)
'source' => string 'DIAG: ' (length=6)
'logfile' => string 'rhj4_diags.log' (length=14)
'level' => int 71
Logfile: D:\ApacheHtdocs\bhamwpdev/wp-content/rhj4_diags.log

09/14/14 04:56:09->DIAG: Page Name [] User [bob_jones]
09/14/14 04:56:55->DIAG: Page Name [diags] User [bob_jones]

rhj4_diags.log deleted

Example:

    [rhj4_diagnostics notify=true message="this is a notification" verbose=true]

Will generate a popup window containing the notification message.

NOTE: Use of the notify function requires the installation of the RHJ4 Notifications plugin.

DEMONSTRATION Page: Visit http://bellinghamwordpressdevelopers.com/diags for a demonstration of these shortcodes in action.

EXAMPLES

There are two basic ways to invoke this plugin:

1. Call rhj4_diagnostic and pass in the message and (optionally) any options

2. Acquire an instance of the plugin and work with that:

   $diags = RHJ4Diagnostics::instance();

   $diags holds an instance of the diagnostics object and can be used to invoke methods in the object.

These two lines are equivalent:

    $diags->diagnostic('message','SOURCE: ');
    $diags->diagnostic('message', array('source' => 'SOURCE: '));

Enable plugin for this page and print a message:

    $diags->diagnostic('message', 
        array('source' => 'SOURCE: ', 'enabled' => true));

This code:

    rhj4_diagnostic('this is a message');

Will produce this output in the current log file:

08/13/14 23:36:44->DIAGNOSTICS:this is a message

This example:

    $diags = RHJ4Diagnostics::instance();
    $diags = RHJ4Diagnostics::instance()->init(array (
        'enabled'   => true,
        'threshold' => 10,
        'output'    => 'rhj4_log',
        'source'    => 'DIAGNOSTICS:',
        'logfile'   => 'rhj4_diags.log',
        'level'     => E_ALL & ~E_DEPRECATED & ~E_NOTICE & ~E_STRICT
    ));

    $diags->diagnostic($diags->plugin_slug.' enabled');

Will:

• Enable the plugin.
• Set the message threshold to 10.
• Set the output logging function (‘rhj4_log).
• Identify the logging file (‘rhj4_diags.log’).
• Tell the plugin to report all PHP errors except E_DEPRECATED, E_NOTICE and E_STRICT.

• Write a line in the output file like this:

  08/13/14 23:36:42->DIAGNOSTICS:rhj4_diagnostics enabled

Demo Code

Add this line of code (or uncomment the line in the plugin source):

    add_action('init','rhj4_diagnostics_demo');

and the plugin will execute code in the function rhj4_diagnostics_demo:

Get an instance of this plugin:

    $diags = RHJ4Diagnostics::instance();

Reset option settings to their defaults. The reset values are remembered in wp_options:

    $diags->clear_log();
    $diags->reset();
    $options = $diags->options();
    var_dump($options);

After reset, plugin will not be enabled, so this next message won’t show:

    $message = rhj4_diagnostic('This message will NOT appear in the log.');    
    var_dump($message);

Enable plugin and change the source message:

    $message = $diags->diagnostic('This message WILL appear in log', array(
       'enabled'    => true,
   'source'     => 'DEMO: '
    ));

    $options = $diags->options();
    var_dump($message);
    var_dump($options);

    $message = $diags->diagnostic('Turn on reporting of PHP Errors', array(
        'level' => E_ALL ));

    $options = $diags->options();
    var_dump($message);
    var_dump($options);

    rhj4_diagnostic('End of demo','THE END: ');

Custom Output Handlers

You can write your own output handlers that will direct diagnostics to any file (or database table) that you want. Here is an example:

    function my_diagnostic_test_output($message, $logfile = 'rhj4_diags_test.log') {
        $timestamp = date('m/d/y H:i:s',time());
        $file = fopen($logfile,"a+");
        fwrite($file, $timestamp.'->'.$message."\n");
        fclose($file);
    }

Multiple Output Handlers

//
//  This example writes the output to two log files 
//
    rhj4_diagnostic('more complex message', array(
        'source' =>'MULTIPLE FUNCTIONS: ',
        'output' => array(
            array(  'function' => 'my_diagnostic_test_output', 
                    'logfile' => 'rhj4_diags_test.log'),
            array(  'function' => 'rhj4_log', 
                    'logfile' => 'rhj4_diags.log')
        )));

SUPPORT

I will attempt to answer your email as quickly as I can, but cannot promise immediate response.

I will entertain ideas for enhancements, especially if I hear the same request from multiple people.

Donations will encourage my support… and my thanks.

CONSULTING

I make my living by helping WordPress developers. If I can help you, please contact me.

Bob Jones

[email protected]

http://bellinghamwordpressdevelopers.com/

Why do I need this plugin?

There are only three commonly used methods to debug code:

1. Iteratively alter the code until you get the desired effect.
   This is useful for fine-tuning screen layouts, but not for code bugs.

2. Use diagnostic trace statements to capture critical flow information.

3. Use a debugger with breakpoints so you can stop and examine code and
   variables.

This plugin makes it simple to write diagnostic information into files on the
server and onto the browser’s console log. Diagnostics on the server can be
written to multiple files simultaneously. PHP error diagnostics can be included
or excluded, and diagnostics can be enabled at specific points in your code
and disabled elsewhere.

What makes this plugin better than simply invoking error_log?

1. The error log file’s location is defined in php.ini and, depending on your configuration, may not be visible to you.
2. You can easily enable and disable logging at various places in your code.
3. Diagnostic statements can be written into a variety of files or even databases.
4. You can add the shortcode [rhj4_diagnostics show=true] to any page and see the entire contents of the current logfile.
5. The shortcode [rhj4_diagnostics clear=true] will delete the logfile.

Can I enable and disable logging without having to delete all my trace statements?

RHJ4Diagnostics::instance(‘enabled’=>true|false);

Can I selectively enable or disable PHP error messages?

$diags->option(array (‘level’ => E_ALL & ~E_DEPRECATED & ~E_NOTICE & ~E_STRICT);

Will it capture All PHP diagnostics except NOTICE and STRICT messages?

$diags->option(array (‘level’ => 0);

Will it disable capture of PHP diagnostics?

Can I label various messages so I can tell where they came from?

$diags = RHJ4Diagnostics::instance();
$diags->diagnostic(‘Message # 1’, ‘FUNCTION A: ‘);
…
$diags->diagnostic(‘Message # 2’, ‘FUNCTION B: ‘);
…
$diags->diagnostic(‘Message # 3’, ‘FUNCTION C: ‘);

Can I write some output into various different log files?

$diags->diagnostic(‘Message text’, array(‘output’=> array(
‘function’ => ‘my_diagnostic_test_output’, ‘logfile’ => ‘demo.log’)));

Can I selectively enable some diagnostic messages and disable others?

Yes. The “threshold” option determines which messages will be displayed.
If the current threshold value is 10 and the message’s threshold value is greater than 10, the message will not be logged. If the message threshold is 10 or less, it will be logged.

    $diags = RHJ4Diagnostics::instance();
    $diags->options(array('enabled' => true, 'threshold' => 6);
    $diags->diagnostic('This message will not be logged',array('threshold'=>7));
    $diags->diagnostic('This message will be logged',array('threshold'=>5));

Can my settings be remembered across pages?

Yes. On the first page establish your settings like this:

    $diags = RHJ4Diagnostics::instance();
    $diags->set(array('enabled' => true, 'threshold' => 6);

Enhanced demo considerably.

Added jQuery support for save, clear and show functions. It can now save a diagnostic generated in jQuery or PHP.

Added rhj4_diagnostics_save, rhj4_diagnostics_show and rhj4_diagnostics_clear AJAX functions to support jQuery calls.

1.1

Added substantial shortcode support.
Added threshold option.