Featuring Debug and Trace

The Trace utility is a PHP developer side tool. It acts as an output console for developers and can greatly aid in development and debugging of your plugins and themes.

To use the Trace utility, you can follow these steps:

1. Enable Trace and Debug

The Debug and Trace services are enabled via DesktopServer’s first option to “Stop or restart the web and database services”. Select this option and click on the “Next >” button.

On the next page, you can choose which Design Time plugins will be used for all of your sites running under DesktopServer. Here, be sure that the “Debug and Trace” plugin is checked so that it will be available for use.

then click on the “Next >” button to restart the services and load the Debug and Trace plugin.

2. Launch the Trace app

The Trace application is a separate application from DesktopServer. This tool shows a window viewable on your desktop that receives the trace information from your PHP code. To start this application, you need to launch it from it’s location within the DesktopServer install directory. This is located at /Application/XAMPP/Trace.app on Macintosh or C:\xampplite\Trace.exe on Windows. For convenience, you can create a shortcut to launch the application.

Once launched, the Trace application displays it’s window and outputs any data sent to it from the PHP and/or Javascript function (described below). The window also provides a “Clear” button that can be used to clear all of the contents of the Trade data currently in the window. This is helpful when running a test and you want to clear out any previous data, allowing you to view just the Trace output from the latest test run.

3. Add Trace code to your Plugin or Theme

Within PHP code, a new global function is available called trace(). You may invoke it like so:
trace( $msg, $skip_type = FALSE );

The trace() function takes two parameters. The first parameter is the data that is to be output. This can be an object, variable, or string literal and is designed to output contents to the Trace window with a timestamp. You should be aware that while you can send very large objects and arrays to the trace() function, the output of these arrays will be truncated at 2K of data. This is done in order to reduce the overhead of sending these large data objects to the Trace window. If your objects or arrays are larger than 2K, you can use PHP’s built-in function called array_slice() to break the data into smaller pieces.

The second parameter is a boolean and is used to direct the trace() function to output the type of data being output. If this value is not provided or is a FALSE (the default value), then the data type will be output within parenthesis before the contents of the first parameter. Any other value and the type will not be displayed.

A similar global function is made available for Javascript. The Javascript trace() function uses only one parameter: the data to be output to the Trace window. Like the PHP function, this data can be of any type, so you can send it an object, an Array, a Hash, a variable or a constant string.

The trace() function is commonly used for debugging in lieu of PHP’s echo statement or var_dump() function that outputs to the browser window, messing up any HTML output along the way. Also, because the trace() function does not output any data to the browser, it can be used to debug sections of code prior to output that might otherwise cause developer headache from a "Warning: Headers already sent" type error.

Because the trace() function is made available via a Design Time plugin, after deploying your site to a live host, it will not be available. This is because Design Time plugins are not included in the DesktopServer Deployment process. To avoid runtime errors in your code, you can create a utility function within your plugin or theme that checks for the availability of the trace() function. An example of this is as follows:


function my_trace( $msg, $j = FALSE ) {
    if ( function_exists( ′trace′ ))
        trace( $msg, $j );
}

With this, you can use the my_trace() function and it will check to ensure the trace() function is available. The ‘my_‘ prefix here is a placeholder/example. If you’re planning on using this in multiple themes or plugins, you should prefix your function with something that will be more unique in order to avoid function name collisions with other code.

Debug Output

Please note: When you activate the Debug and Trace Design Time plugin, part of what it does is enable the WP_DEBUG feature. This means that you could see several warning messages output onto the page – especially if you’re using older plugins or themes, or code that was not developed with debugging turned on. It is an unfortunate reality that not all WordPress developers write their code with debugging turned on. The result is that you may see some or even a lot of these warnings. For the most part, they are nothing to worry about and can be ignored. However, seeing a lot of errors could get in the way of using the site, even in a local test environment.

If you do see a lot of errors and warnings, we recommend that you notify the theme or plugin developers. Most of the time developers are willing to work with you to improve their code. If the developers are not so inclined, you can investigate alternative plugins for the features that you need. After all, if there are a lot of runtime warnings in the code, there may be other issues and you might be better off finding another solution. If this is not feasible, you can make a small change to the Debug and Trace plugin and remove or comment out the define( ′WP_DEBUG′, TRUE ); line found on line 4 in the prepend_0.php file. This is located in the /Applications/XAMPP/ds-plugins/debug-trace/ directory on Macintosh and the c:\xampplite\ds-plugins\debug-trace\ directory on Windows. This will turn off the WP_DEBUG setting (which is the normal state for WordPress) and you will no longer see the warning messages.

Feedback

The trace() function provides a very convenient method of displaying debug information without affecting the HTML output to the browser. The ability to output data in both PHP and Javascript provides you with additional tools to help in your development process. Try it out and see how it works for you. And give us your feedback. If you have suggestions for improving the tool or some new features you’d like to see we’d love to hear about them.

Being the Product Architect at ServerPress, LLC, Dave brings 35+ years of experience bridging traditional architecture with innovative Workflow solutions. Creator of WPSiteSync, among many other products, he loves pushing technology to the limit. His motto: No coffee. No code.

Leave a Reply

Your email address will not be published. Required fields are marked *