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>\n\n
Diagnostics works closely with RHJ4 Notifications. Each uses functionality in the other plugin.<\/p>\n\n
Using trace statements is my preferred method of debugging when I am not \nexactly sure where the bug is coming from. A common method for implementing \ntracing is to use the PHP error_log function which writes a line of text \ninto a specific file that is identified in the PHP.ini configuration file.<\/p>\n\n
This method is simple and effective, but there are several problems that come\nalong with it:<\/p>\n\n
Diagnostic problems can arise in the Javascript code executing in the browser\nor in PHP code executing in the server. In both cases, you want to be able to\neasily capture and report the condition.<\/p>\n\n
RHJ4Diagnostics reports its messages in several places: on the Browser's \ndebugging console, in the PHP error_log, or to a function you specify.<\/p>\n\n
Diagnostics can be turned on or off for an entire site or for a single section\nof code. Since the diagnostics are very lightweight, they don't have to be \nremoved from the code in order to be disabled.<\/p>\n\n
The PHP code is implemented as a class with the following functions:<\/p>\n\n
instance(): Return instance of plugin (does not initialize).<\/p><\/li>\n
init($options = NULL): Initialize plugin<\/p><\/li>\n
kill(): Kill current instance of plugin<\/p><\/li>\n
options ($options = null): parse and set options for currently loaded page<\/p><\/li>\n
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>\n
reset(): reset all options to their defaults<\/p><\/li>\n
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>\n
set_error_reporting($level = null): Set PHP error_reporting_level<\/p><\/li>\n
render_error_level($level): Translate integer error_level value to string<\/p><\/li>\n<\/ul>\n\n
The following options may be used for all functions that accept $options:<\/p>\n\n
Option values are stored in the wp_options table using the key 'rhj4_diagnostic_options'.<\/p>\n\n
The shortcode format is:<\/p>\n\n
[rhj4_diagnostics <code>=<value> [...]]\n<\/code><\/pre>\n\nThe following code values are supported:<\/p>\n\n
enable<\/strong> [true|false<- default] Enables logging on this page.<\/p>\n\ndisable<\/strong> [true|false<- default] Disables logging on this page.<\/p>\n\nthreshold<\/strong> [0 | integer value] Sets diagnostic threshold level. Only messages with this threshold or lower will be logged.<\/p>\n\nsave<\/strong> [true|false<- default] Used with Enable, Disable and Threshold to save settings\nto database. To enable diagnostics for all pages:<\/p>\n\n[rhj4_diagnostics enable=true save=true]\n<\/code><\/pre>\n\nshow<\/strong> [true|false<- default] Displays current log file contents.<\/p>\n\nclear<\/strong> [true|false<- default] Deletes current log file.<\/p>\n\noptions<\/strong> [true|false<- default] Displays current option values on page.<\/p>\n\ndemo<\/strong> [true|false<- default] Shows a demonstration of many ways of using this plugin.<\/p>\n\ntest<\/strong> [true|false<- default] Performs some diagnostic tests on the code.<\/p>\n\noptions<\/strong> [true|false<- default] Shows the current option values.<\/p>\n\nverbose<\/strong> [true|false<- default] Echos diagnostic information on the page.<\/p>\n\nlog<\/strong> [true|false<- default] Writes a diagnostic to the log. Requires message. For example:<\/p>\n\n [rhj4_diagnostics log=true message='log this message']\n<\/code><\/pre>\n\nmessage<\/strong> = is used with notify and log to define the message to be sent.<\/p>\n\nnotify<\/strong> [true|false<- default] Displays a notification popup using RHJ4Notifications. Requires message and uses sticky and type.<\/p>\n\n [rhj4_diagnostics notify=true message='show this message in popup' sticky=true, type=NOTIFICATION_TYPE_WARNING]\n<\/code><\/pre>\n\nsticky<\/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>\n\ntype<\/strong> = (NOTIFICATION_TYPE_CONFIRMATION<- default) indicates the type of notification to be generated.<\/p>\n\nExample:<\/p>\n\n
[rhj4_diagnostics enable=true show=true clear=true show_options=true]\n<\/code><\/pre>\n\nWill produce:<\/p>\n\n
Options<\/h4>\n\narray (size=6)\n'enabled' => int 1\n'threshold' => int 10\n'output' => string 'rhj4_log' (length=8)\n'source' => string 'DIAG: ' (length=6)\n'logfile' => string 'rhj4_diags.log' (length=14)\n'level' => int 71\nLogfile: D:\\ApacheHtdocs\\bhamwpdev\/wp-content\/rhj4_diags.log\n\n09\/14\/14 04:56:09->DIAG: Page Name [] User [bob_jones]\n09\/14\/14 04:56:55->DIAG: Page Name [diags] User [bob_jones]\n\nrhj4_diags.log deleted\n<\/code><\/pre>\n\nExample:<\/p>\n\n
[rhj4_diagnostics notify=true message=\"this is a notification\" verbose=true]\n<\/code><\/pre>\n\nWill generate a popup window containing the notification message.<\/p>\n\n
NOTE: Use of the notify function requires the installation of the RHJ4 Notifications plugin.<\/p>\n\n
DEMONSTRATION Page: Visit http:\/\/bellinghamwordpressdevelopers.com\/diags<\/a> for a demonstration of these shortcodes in action.<\/p>\n\nEXAMPLES<\/h3>\n\n
There are two basic ways to invoke this plugin:<\/p>\n\n
\nCall rhj4_diagnostic and pass in the message and (optionally) any options<\/p><\/li>\n
Acquire an instance of the plugin and work with that:<\/p>\n\n
$diags = RHJ4Diagnostics::instance();<\/p>\n\n
$diags holds an instance of the diagnostics object and can be used to invoke methods in the object.<\/p><\/li>\n<\/ol>\n\n
These two lines are equivalent:<\/p>\n\n
$diags->diagnostic('message','SOURCE: ');\n $diags->diagnostic('message', array('source' => 'SOURCE: '));\n<\/code><\/pre>\n\nEnable plugin for this page and print a message:<\/p>\n\n
$diags->diagnostic('message', \n array('source' => 'SOURCE: ', 'enabled' => true));\n<\/code><\/pre>\n\nThis code:<\/p>\n\n
rhj4_diagnostic('this is a message');\n<\/code><\/pre>\n\nWill produce this output in the current log file:<\/p>\n\n
08\/13\/14 23:36:44->DIAGNOSTICS:this is a message\n<\/code><\/pre>\n\nThis example:<\/p>\n\n
$diags = RHJ4Diagnostics::instance();\n $diags = RHJ4Diagnostics::instance()->init(array (\n 'enabled' => true,\n 'threshold' => 10,\n 'output' => 'rhj4_log',\n 'source' => 'DIAGNOSTICS:',\n 'logfile' => 'rhj4_diags.log',\n 'level' => E_ALL & ~E_DEPRECATED & ~E_NOTICE & ~E_STRICT\n ));\n\n $diags->diagnostic($diags->plugin_slug.' enabled');\n<\/code><\/pre>\n\nWill:<\/p>\n\n
\n- Enable the plugin.<\/li>\n
- Set the message threshold to 10.<\/li>\n
- Set the output logging function ('rhj4_log).<\/li>\n
- Identify the logging file ('rhj4_diags.log'). <\/li>\n
- Tell the plugin to report all PHP errors except E_DEPRECATED, E_NOTICE and E_STRICT.<\/li>\n
Write a line in the output file like this:<\/p>\n\n
08\/13\/14 23:36:42->DIAGNOSTICS:rhj4_diagnostics enabled<\/p><\/li>\n<\/ul>\n\n
Demo Code<\/h4>\n\n
Add this line of code (or uncomment the line in the plugin source):<\/p>\n\n
add_action('init','rhj4_diagnostics_demo');\n<\/code><\/pre>\n\nand the plugin will execute code in the function rhj4_diagnostics_demo:<\/p>\n\n
Get an instance of this plugin:<\/p>\n\n
$diags = RHJ4Diagnostics::instance();\n<\/code><\/pre>\n\nReset option settings to their defaults. The reset values are remembered in wp_options:<\/p>\n\n
$diags->clear_log();\n $diags->reset();\n $options = $diags->options();\n var_dump($options);\n<\/code><\/pre>\n\nAfter reset, plugin will not be enabled, so this next message won't show:<\/p>\n\n
$message = rhj4_diagnostic('This message will NOT appear in the log.'); \n var_dump($message);\n<\/code><\/pre>\n\nEnable plugin and change the source message:<\/p>\n\n
$message = $diags->diagnostic('This message WILL appear in log', array(\n 'enabled' => true,\n 'source' => 'DEMO: '\n ));\n\n $options = $diags->options();\n var_dump($message);\n var_dump($options);\n\n $message = $diags->diagnostic('Turn on reporting of PHP Errors', array(\n 'level' => E_ALL ));\n\n $options = $diags->options();\n var_dump($message);\n var_dump($options);\n\n rhj4_diagnostic('End of demo','THE END: ');\n<\/code><\/pre>\n\nCustom Output Handlers<\/h4>\n\n
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>\n\n
function my_diagnostic_test_output($message, $logfile = 'rhj4_diags_test.log') {\n $timestamp = date('m\/d\/y H:i:s',time());\n $file = fopen($logfile,\"a+\");\n fwrite($file, $timestamp.'->'.$message.\"\\n\");\n fclose($file);\n }\n<\/code><\/pre>\n\nMultiple Output Handlers<\/h4>\n\n\/\/\n\/\/ This example writes the output to two log files \n\/\/\n rhj4_diagnostic('more complex message', array(\n 'source' =>'MULTIPLE FUNCTIONS: ',\n 'output' => array(\n array( 'function' => 'my_diagnostic_test_output', \n 'logfile' => 'rhj4_diags_test.log'),\n array( 'function' => 'rhj4_log', \n 'logfile' => 'rhj4_diags.log')\n )));\n<\/code><\/pre>\n\nSUPPORT<\/h3>\n\n
I will attempt to answer your email as quickly as I can, but cannot promise immediate response.<\/p>\n\n
I will entertain ideas for enhancements, especially if I hear the same request from multiple people.<\/p>\n\n
Donations will encourage my support... and my thanks.<\/p>\n\n
CONSULTING<\/h3>\n\n
I make my living by helping WordPress developers. If I can help you, please contact me.<\/p>\n\n
Bob Jones<\/p>\n\n