A proper debugging environment is always nice. But sometimes – particularly when it comes to WordPress websites – you don’t always have access to things like a shell, or even web server logs. In these limited-access situations, how do you debug a problem in your WordPress theme or plugin?

This tutorial introduces two techniques that will help in your WordPress debugging process. All you need for both is FTP/file access to the website directory, and the ability to modify website files. Shell access is not required, and you don’t need access to the web server logs either.

Technique #1: WordPress Debug Mode

By adding a few lines to the wp-config.php file of your WordPress installation, you can activate debug mode in WordPress. Activating this mode gives you visibility into PHP errors that may be occurring in your theme or plugin. It has the effect of setting the PHP reporting level to  E_ALL , which shows all PHP errors and warnings (except of level E_STRICT prior to PHP 5.4.0).

Debug mode shows the errors it detects in the HTML output of your WordPress posts and pages. It can also be configured to log errors to a file – or both.

Be Careful

It’s generally a bad idea to log errors directly to the HTML output of a live web application. It’s convenient, but it also exposes details of your website internals directly to visitors, which can present security risks. It’s a much better idea to log errors to a file, that you can then retrieve via FTP. The code in this tutorial illustrates the safer method.

Also – don’t forget to deactivate debug mode when you’re finished by removing the appropriate configuration directives from your wp-config.php file, and delete the log file at /wp-content/debug.log .

The Code

Navigate to the following section of your wp-config.php file and update it as follows to activate WordPress debug mode:

/**
 * For developers: WordPress debugging mode.
 *
 * Change this to true to enable the display of notices during development.
 * It is strongly recommended that plugin and theme developers use WP_DEBUG
 * in their development environments.
 *
 * For information on other constants that can be used for debugging,
 * visit the Codex.
 *
 * @link https://codex.wordpress.org/Debugging_in_WordPress
 */
define( 'WP_DEBUG', true );  // Activates debug mode
define( 'WP_DEBUG_DISPLAY', false ); // Prevents debug output to HTML
define( 'WP_DEBUG_LOG', true ); // Sends debug output to /wp-content/debug.log

With this configuration, all PHP errors will be logged to wp-content/debug.log .

Technique #2: Using var_dump()

Sometimes your problem doesn’t result in a PHP error. When debugging, it can be useful to be able to examine the state of objects, arrays and other variables.

Enter PHP’s var_dump() function. This function can show you the values in variables and even complex structures like objects like arrays.

Be Careful

var_dump() has the same risks as WordPress debug mode: outputting internal application details to the web page can introduce security concerns. Since var_dump() doesn’t work with logs, you have no choice but to include it in your HTML output. One way to reduce the risk of internal details leaking to site visitors is to enclose its output in a set of HTML comment tags. Then you’ll be able to see its output in the HTML source of your web page, but visitors won’t see it directly. The example below will show you how to do that.

The Code

<!--
<?php 
$my_var = array('Item1', 'Item2', 'Item3');
var_dump($my_var)
?>
-->

Outputs the following in the HTML of your page. Note that you’ll have to use “View Source” to see it, as the output is enclosed in HTML comments.

<!--
array(3) {
  [0]=>
  string(5) "Item1"
  [1]=>
  string(5) "Item2"
  [2]=>
  string(5) "Item3"
}
-->

Don’t forget to clean up any calls to var_dump() when you’re finished debugging!

Photo by Manlake Gabriel on Unsplash