Bob Jones

<p>RHJ4 Diagnostics captures diagnostic messages written in PHP and conditionally directs them to various different logging functions. The plugin can be enabled or disabled during page execution, and it can intercept and handle various classes of PHP errors, e.g. E_ERROR & ~E_NOTICE. The documentation includes numerous usage examples.</p>
<p>Diagnostics works closely with RHJ4 Notifications. Each uses functionality in the other plugin.</p>
<h3>Usage</h3>
<h3>The Problem</h3>
<p>Using trace statements is my preferred method of debugging when I am not<br />
exactly sure where the bug is coming from. A common method for implementing<br />
tracing is to use the PHP error_log function which writes a line of text<br />
into a specific file that is identified in the PHP.ini configuration file.</p>
<p>This method is simple and effective, but there are several problems that come<br />
along with it:</p>
<ol>
<li>You have to go back through your code later and remove the error_log calls<br />
or they will slow the program down and fill the error log with what are now<br />
useless messages.</li>
<li>The log may also contain undesired “noise” in the form of PHP messages and<br />
stack dumps. Many of these you can control using the error_reporting (level)<br />
function, but some of these messages simply won’t go away.</li>
<li>Depending on your configuration, you may not have access to PHP.ini and you<br />
may not be able to see the generated log because you don’t have access<br />
rights to the location the log was written to.</li>
</ol>
<h3>RHJ4Diagnostics</h3>
<p>Diagnostic problems can arise in the Javascript code executing in the browser<br />
or in PHP code executing in the server. In both cases, you want to be able to<br />
easily capture and report the condition.</p>
<p>RHJ4Diagnostics reports its messages in several places: on the Browser’s<br />
debugging console, in the PHP error_log, or to a function you specify.</p>
<p>Diagnostics can be turned on or off for an entire site or for a single section<br />
of code. Since the diagnostics are very lightweight, they don’t have to be<br />
removed from the code in order to be disabled.</p>
<h3>PHP API</h3>
<p>The PHP code is implemented as a class with the following functions:</p>
<ul>
<li>
<p>instance(): Return instance of plugin (does not initialize).</p>
</li>
<li>
<p>init($options = NULL): Initialize plugin</p>
</li>
<li>
<p>kill(): Kill current instance of plugin</p>
</li>
<li>
<p>options ($options = null): parse and set options for currently loaded page</p>
</li>
<li>
<p>set($options = NULL): parse and set options in wp_options table. NOTE: Multisite is supported. Options will be set in wp_$blog_id_options table.</p>
</li>
<li>
<p>reset(): reset all options to their defaults</p>
</li>
<li>
<p>diagnostic($message, $options = NULL): Capture a diagnostic message. NOTE: $if $options is a string, it will be treated as if it were: array(‘source’ -> ‘whatever:’).</p>
</li>
<li>
<p>set_error_reporting($level = null): Set PHP error_reporting_level</p>
</li>
<li>
<p>render_error_level($level): Translate integer error_level value to string</p>
</li>
</ul>
<h3>OPTIONS</h3>
<p>The following options may be used for all functions that accept $options:</p>
<ul>
<li><em>enabled</em> enables plugin (default: false). If not enabled, no diagnostic messages will be displayed.</li>
<li><em>threshold</em> sets a threshold that determines which messages will be logged. Messages with a threshold above the current threshold will not be written to the log file.</li>
<li><em>output</em> identifies output handler function (default: ‘rhj4_log’). Output may be a single function name or an array of function names. Function must exist to be set.</li>
<li><em>source</em> identifies the body of code that diagnostics will be coming from. This string will be prepended to each message.</li>
<li><em>logfile</em> identifies where output diagnostics will be saved (default: ‘rhj4_diags.log’).</li>
<li><em>level</em> PHP error reporting level for PHP diagnostics (default: 71 = 64 + 4 + 2 + 1 = ERROR, WARNING, PARSE, COMPILE ERROR). PHP errors will be reported if WP_DEBUG is TRUE. RHJ4Diagnostics will be reported if plugin is enabled.</li>
</ul>
<p>Option values are stored in the wp_options table using the key ‘rhj4_diagnostic_options’.</p>
<h3>SHORTCODES</h3>
<p>The shortcode format is:</p>
<pre><code>    [rhj4_diagnostics <code>=<value> [...]]
</code></pre>
<p>The following code values are supported:</p>
<p><strong>enable</strong> [true|false<- default] Enables logging on this page.</p>
<p><strong>disable</strong> [true|false<- default] Disables logging on this page.</p>
<p><strong>threshold</strong> [0 | integer value] Sets diagnostic threshold level. Only messages with this threshold or lower will be logged.</p>
<p><strong>save</strong> [true|false<- default] Used with Enable, Disable and Threshold to save settings<br />
to database. To enable diagnostics for all pages:</p>
<pre><code>[rhj4_diagnostics enable=true save=true]
</code></pre>
<p><strong>show</strong> [true|false<- default] Displays current log file contents.</p>
<p><strong>clear</strong> [true|false<- default] Deletes current log file.</p>
<p><strong>options</strong> [true|false<- default] Displays current option values on page.</p>
<p><strong>demo</strong> [true|false<- default] Shows a demonstration of many ways of using this plugin.</p>
<p><strong>test</strong> [true|false<- default] Performs some diagnostic tests on the code.</p>
<p><strong>options</strong> [true|false<- default] Shows the current option values.</p>
<p><strong>verbose</strong> [true|false<- default] Echos diagnostic information on the page.</p>
<p><strong>log</strong> [true|false<- default] Writes a diagnostic to the log. Requires message. For example:</p>
<pre><code>    [rhj4_diagnostics log=true message='log this message']
</code></pre>
<p><strong>message</strong> =  is used with notify and log to define the message to be sent.</p>
<p><strong>notify</strong> [true|false<- default] Displays a notification popup using RHJ4Notifications. Requires message and uses sticky and type.</p>
<pre><code>    [rhj4_diagnostics notify=true message='show this message in popup' sticky=true, type=NOTIFICATION_TYPE_WARNING]
</code></pre>
<p><strong>sticky</strong> [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.</p>
<p><strong>type</strong> =  (NOTIFICATION_TYPE_CONFIRMATION<- default) indicates the type of notification to be generated.</p>
<p>Example:</p>
<pre><code>    [rhj4_diagnostics enable=true show=true clear=true show_options=true]
</code></pre>
<p>Will produce:</p>
<h4>Options</h4>
<pre><code>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
</code></pre>
<p>Example:</p>
<pre><code>    [rhj4_diagnostics notify=true message="this is a notification" verbose=true]
</code></pre>
<p>Will generate a popup window containing the notification message.</p>
<p>NOTE: Use of the notify function requires the installation of the RHJ4 Notifications plugin.</p>
<p>DEMONSTRATION Page: Visit <a href="http://bellinghamwordpressdevelopers.com/diags" rel="nofollow ugc">http://bellinghamwordpressdevelopers.com/diags</a> for a demonstration of these shortcodes in action.</p>
<h3>EXAMPLES</h3>
<p>There are two basic ways to invoke this plugin:</p>
<ol>
<li>
<p>Call rhj4_diagnostic and pass in the message and (optionally) any options</p>
</li>
<li>
<p>Acquire an instance of the plugin and work with that:</p>
<p>$diags = RHJ4Diagnostics::instance();</p>
<p>$diags holds an instance of the diagnostics object and can be used to invoke methods in the object.</p>
</li>
</ol>
<p>These two lines are equivalent:</p>
<pre><code>    $diags->diagnostic('message','SOURCE: ');
    $diags->diagnostic('message', array('source' => 'SOURCE: '));
</code></pre>
<p>Enable plugin for this page and print a message:</p>
<pre><code>    $diags->diagnostic('message', 
        array('source' => 'SOURCE: ', 'enabled' => true));
</code></pre>
<p>This code:</p>
<pre><code>    rhj4_diagnostic('this is a message');
</code></pre>
<p>Will produce this output in the current log file:</p>
<pre><code>08/13/14 23:36:44->DIAGNOSTICS:this is a message
</code></pre>
<p>This example:</p>
<pre><code>    $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');
</code></pre>
<p>Will:</p>
<ul>
<li>Enable the plugin.</li>
<li>Set the message threshold to 10.</li>
<li>Set the output logging function (‘rhj4_log).</li>
<li>Identify the logging file (‘rhj4_diags.log’). </li>
<li>Tell the plugin to report all PHP errors except E_DEPRECATED, E_NOTICE and E_STRICT.</li>
<li>
<p>Write a line in the output file like this:</p>
<p>08/13/14 23:36:42->DIAGNOSTICS:rhj4_diagnostics enabled</p>
</li>
</ul>
<h4>Demo Code</h4>
<p>Add this line of code (or uncomment the line in the plugin source):</p>
<pre><code>    add_action('init','rhj4_diagnostics_demo');
</code></pre>
<p>and the plugin will execute code in the function rhj4_diagnostics_demo:</p>
<p>Get an instance of this plugin:</p>
<pre><code>    $diags = RHJ4Diagnostics::instance();
</code></pre>
<p>Reset option settings to their defaults. The reset values are remembered in wp_options:</p>
<pre><code>    $diags->clear_log();
    $diags->reset();
    $options = $diags->options();
    var_dump($options);
</code></pre>
<p>After reset, plugin will not be enabled, so this next message won’t show:</p>
<pre><code>    $message = rhj4_diagnostic('This message will NOT appear in the log.');    
    var_dump($message);
</code></pre>
<p>Enable plugin and change the source message:</p>
<pre><code>    $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: ');
</code></pre>
<h4>Custom Output Handlers</h4>
<p>You can write your own output handlers that will direct diagnostics to any file (or database table) that you want. Here is an example:</p>
<pre><code>    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);
    }
</code></pre>
<h4>Multiple Output Handlers</h4>
<pre><code>//
//  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')
        )));
</code></pre>
<h3>SUPPORT</h3>
<p>I will attempt to answer your email as quickly as I can, but cannot promise immediate response.</p>
<p>I will entertain ideas for enhancements, especially if I hear the same request from multiple people.</p>
<p>Donations will encourage my support… and my thanks.</p>
<h3>CONSULTING</h3>
<p>I make my living by helping WordPress developers. If I can help you, please contact me.</p>
<p>Bob Jones</p>
<p><a href="mailto:bob@rhj4.com" rel="nofollow ugc">bob@rhj4.com</a></p>
<p><a href="http://bellinghamwordpressdevelopers.com/" rel="nofollow ugc">http://bellinghamwordpressdevelopers.com/</a></p>


RHJ4 Diagnostics

RHJ4 Diagnostics supports program debugging by making it simple to write tracing information into several log files.

rhj4

<p>RHJ4 Notifications and its sibling, RHJ4 Diagnostics solve problems that have plagued programmers for years: How to communicate with users in a clean, clear and visually consistent fashion regardless of where in the program the message originates.</p>
<p>A notification message can be sent from jQuery code in the browser or from PHP code in the server. Either type of message can be displayed immediately or queued for display after the next page turn.</p>
<p>Notifications appear as popup messages on the bottom right corner of the screen and can stay on the screen until the user clicks on them or they can disappear after five seconds.</p>
<p>Using this plugin, a message can be sent easily from a single line of PHP code:</p>
<pre><code>    rhj4_notification('Warning! Danger, Will Robinson!', NOTIFICATION_TYPE_WARNING);
</code></pre>
<p>The same messsage can be sent from jQuery code running in the browser:</p>
<pre><code>    jQuery.notification('Warning! Danger, Will Robinson!',
    jQuery.notification.type('warning'));
</code></pre>
<p>By default, notifications will disappear from the screen after five seconds; however, to make a notification “sticky”, add true as the third argument to either the PHP or jQuery functions:</p>
<pre><code>    jQuery.notification('Warning! Danger, Will Robinson!',
    jQuery.notification.type('warning'), true);
</code></pre>
<p>Notifications can be displayed immediately or queued in the wp_notifications table for display later. The wp_notifications table is created when the plugin is enabled. To “enable” this plugin, see Settings and click on the “Enable” checkbox.</p>
<p>RHJ4 Notifications supports 15 types of notifications</p>
<h3>Usage</h3>
<p>A notification consists of a:</p>
<ul>
<li><strong>Message</strong> – some text to be shown to the user.</li>
<li><strong>Notification Type</strong> – an integer in the range -1..13 that indicates the style of the notification.</li>
<li><strong>Sticky</strong> – a boolean that indicates whether the message should disappear after a few seconds or “stick” around.</li>
</ul>
<h3>Notification Types</h3>
<p>These constants are in the global name space:</p>
<ul>
<li>NOTIFICATION_TYPE_DIAGNOSTIC      = -1;</li>
<li>NOTIFICATION_TYPE_LOG             = 0;</li>
<li>NOTIFICATION_TYPE_SYSTEM          = 1;</li>
<li>NOTIFICATION_TYPE_ERROR           = 2;</li>
<li>NOTIFICATION_TYPE_WARNING         = 3;</li>
<li>NOTIFICATION_TYPE_CONFIRMATION    = 4;</li>
<li>NOTIFICATION_TYPE_MESSAGE         = 5;</li>
<li>NOTIFICATION_TYPE_TEST            = 6;</li>
<li>NOTIFICATION_TYPE_DATA            = 7;</li>
<li>NOTIFICATION_TYPE_COMMENT         = 8;</li>
<li>NOTIFICATION_TYPE_TIP             = 9;</li>
<li>NOTIFICATION_TYPE_REMINDER        = 10;</li>
<li>NOTIFICATION_TYPE_DATE            = 11;</li>
<li>NOTIFICATION_TYPE_VALIDATION      = 12;</li>
<li>NOTIFICATION_TYPE_TIMER           = 13;</li>
</ul>
<p>There are four different interfaces available in the Notifications plugin:</p>
<ul>
<li>Global Functions</li>
<li>Class Methods</li>
<li>jQuery plugin</li>
<li>Short Codes</li>
</ul>
<h3>PHP Global Functions</h3>
<h4>Generate a notification</h4>
<pre><code>rhj4_notification($message, $type = NOTIFICATION_TYPE_MESSAGE, $sticky = FALSE);
</code></pre>
<h3>PHP Class Methods</h3>
<h4>RHJ4Notifications::instance()</h4>
<p>Return an instance of this plugin. This usage allows code in multiple places to use the same instance without having to reinitialize the plugin every time.</p>
<p><em>Example:</em></p>
<pre><code>    $myInstance = RHJ4Notifications::instance()    
</code></pre>
<h4>init($args)</h4>
<p>Initialize plugin using any of the options defined in $args (see “options” for a list of supported options).</p>
<h4>kill()</h4>
<p>Kill the current instance.</p>
<h4>activate()</h4>
<p>Activate this plugin.</p>
<h4>deactivate()</h4>
<p>Deactivate this plugin.</p>
<h4>options ($options = null)</h4>
<p>Validate options and return valid array. The supported options are:</p>
<p>–<strong>enable</strong>: enable generation of diagnostic messages.</p>
<p>–<strong>log</strong> = {true|false}: enable log notifications</p>
<p>–<strong>system</strong> = {true|false}: enable system notifications</p>
<p>–<strong>error</strong> = {true|false}: enable error notifications</p>
<p>–<strong>warning</strong> = {true|false}: enable warning notifications</p>
<p>–<strong>confirmation</strong> = {true|false}: enable confirmation notifications</p>
<p>–<strong>message</strong> = {true|false}: enable message notifications</p>
<p>–<strong>test</strong> = {true|false}: enable test notifications</p>
<p>–<strong>data</strong> = {true|false}: enable data notifications</p>
<p>–<strong>comment</strong> = {true|false}: enable comment notifications</p>
<p>–<strong>tip</strong> = {true|false}: enable tip notifications</p>
<p>–<strong>reminder</strong> = {true|false}: enable reminder notifications</p>
<p>–<strong>date</strong> = {true|false}: enable date notifications</p>
<p>–<strong>validation</strong> = {true|false}: enable validation notifications</p>
<p>–<strong>timer</strong> = {true|false}: enable timer notifications</p>
<h4>set($options = NULL)</h4>
<p>Establish default options and save them in wp_options. See “options” for a list of supported options.</p>
<h4>reset()</h4>
<p>Reset options to their default values.</p>
<h4>enable()</h4>
<p>Enable this plugin. This function requires admin privileges and should only be called when setting up a site. It creates a database table (first deleting if if it exists) that stores queued notifications.</p>
<p>This function can be accessed from the settings panel or called directly in your code.</p>
<p>All notifications are stored (temporarily) in a common database table that is keyed by Session ID.</p>
<h4>save($message_text, $message_type = 1, $is_sticky = 0)</h4>
<p>Save a message for display on next page turn or explicit call from jQuery.</p>
<pre><code> @param int $message_type
 @param bool $is_sticky
 @param string $message_text
</code></pre>
<h4>delete_user_notifications ($user_id = null)</h4>
<p>Delete all notifications for $user_id.</p>
<h4>delete_session_notifications ()</h4>
<p>Remove all notifications for the current session.</p>
<h4>delete_all_notifications ()</h4>
<p>Clear notifications table of all pending notifications.</p>
<h4>user_queue_size()</h4>
<h4>list_user_notifications($delete = TRUE)</h4>
<p>Return list of all notifications pending for $user_id.</p>
<h4>session_queue_size()</h4>
<h4>list_session_notifications($delete = TRUE)</h4>
<p>Return a list of all pending notifications for the current session.</p>
<h4>list_all_notifications($delete = TRUE)</h4>
<p>Return a list of all notifications.</p>
<h3>jQuery Plugin API</h3>
<p>The jQuery code included in this plugin is implemented as a jQuery plugin with the class name of “jQuery.notification”.</p>
<p>The functions supported by this class are:</p>
<h4>notification(message, type, isSticky, pluginurl)</h4>
<p>–<strong>message</strong> (required) may be a string or an object.</p>
<p>If it is a string, the string is the notification text to be displayed.<br />
If it is an object, the object may contain properties corresponding to any of the options supported by the jQuery.options method.</p>
<p>_<strong>type</strong> (optional) indicates the notification type as either a string or an integer. If missing, type will use the current option.type value.</p>
<p>_<strong>isSticky</strong> (optional) indicates whether the notification is sticky. If missing, isSticky will use the value from msgType.</p>
<p>_<strong>pluginurl</strong> (optional) indicates the url to be called by this function to communicate with the server. If missing, the code will search for a hidden field named #hid_plugin_url.</p>
<p>Examples:</p>
<pre><code>    jQuery.notification('This is a notification',3,true);

    jQuery.notification({ notification: 'This is a notification', 
            type: "data", 
            sticky: true, 
            queue: false });
</code></pre>
<h4>defaults</h4>
<p>Returns an object containing the default values of all options used by this plugin:</p>
<pre><code>    version: version,   //  code version
    type: 'log',        //  default message type
    sticky: true,       //  if true, don't clear the message automatically
    queue: false,       //  If true, queue the message for later display
    class: '',          //  jGrowl class that styles this message
    clear: true,        //  Delete saved messages after showing them
    showOnConsole: true,//  Show a copy of the message on the console.log
    glue: 'after',      //  jGrowl property that controls order of displaying messages
    sleep:,             //  sleep in milliseconds before displaying message 
    closeTemplate:      //  image to use in close template
    header:             //  '<span class="icon"></span>',
    notification: ''    //  Message can be included with options
</code></pre>
<h4>sleep()</h4>
<p>Set notification sleep delay in milliseconds. This value will be remembered by all subsequent calls to $.Notification.</p>
<h4>option (key, value)</h4>
<p>Get/Set single option:</p>
<p>-version: (read only)<br />
-type: notification type (string or number)<br />
-sticky: boolean<br />
-queue: boolean – save messages in database until explicit request to drain queue<br />
-clear: boolean – clear queue</p>
<h4>save (message, code, sticky, handler)</h4>
<p>-message: the notification text</p>
<p>-code: notification type</p>
<p>-sticky: stick around for awhile or scram</p>
<p>-handler: (optional) custom function to handle displaying the notification.</p>
<h4>messageType (code)</h4>
<p>Returns array of messageType objects.</p>
<h4>type (type)</h4>
<p>Validate notification type value</p>
<h4>getSessionId()</h4>
<p>Get current session id.</p>
<h4>getPluginURL()</h4>
<p>Return URL of AJAX handler function.</p>
<h4>queue (handler)</h4>
<p>Return count of notifications awaiting delivery.</p>
<h4>show (clear)</h4>
<p>Show all messages in the queue. If clear===true, delete all messages just just retrieved.</p>
<h4>erase()</h4>
<p>Close any open notification messages on screen.</p>
<h4>clear()</h4>
<p>Delete all messages to the current session.</p>
<h4>showUser (userId)</h4>
<p>Notifications can be sent to a specific userId. The messages will be held until that user logs in.</p>
<h4>clearUser (userId)</h4>
<p>Delete all user notifications from database.</p>
<h3>Short Codes</h3>
<ul>
<li>
<p><em>enable=1,3,6</em> will enable notification types 1,3 and 6.</p>
</li>
<li>
<p><em>notify</em> message= type= sticky={true|false}</p>
</li>
<li>
<p><em>verbose</em> will cause actions to be echoed on the page.</p>
</li>
<li>
<p><em>demo</em> will display a demonstration of using the Notifications plugin.</p>
</li>
</ul>
<h3>SUPPORT</h3>
<p>I will attempt to answer your email as quickly as I can, but cannot promise immediate response.</p>
<p>I will entertain ideas for enhancements, especially if I hear the same request from multiple people.</p>
<p>Donations will encourage my support… and my thanks.</p>
<h3>CONSULTING</h3>
<p>I make my living by helping WordPress developers. If I can help you, please contact me.</p>
<p>Bob Jones</p>
<p><a href="mailto:bob@rhj4.com" rel="nofollow ugc">bob@rhj4.com</a></p>
<p><a href="http://bellinghamwordpressdevelopers.com/" rel="nofollow ugc">http://bellinghamwordpressdevelopers.com/</a></p>


RHJ4 Notifications

Generate many different types of popup notifications to users from PHP or jQuery with only a single line of code.

RHJ4 Diagnostics vs RHJ4 Notifications