WordPress Debugging: The Essential Guide

Spread the love

Regardless of what level of WordPress developer you are, there is one problem you’ll constantly face: bugs. Even the most seasoned developers cannot consistently code in a manner that doesn’t produce bugs. As a matter of fact, debugging WordPress actually can help you learn even more about the platform!

If you have prior programming experience, chances are that you’ve had errors upon compilation or runtime. Unless you threw in the towel and tossed the project, chances are you spent some time running through the code and tracking the problem down. The dynamic with WordPress is the same.

Unlike when you program in a common programming language, WordPress errors are not simply printed out on the page. This is because debug logs often contain sensitive information, like the credentials to databases. WordPress instead will drop those logs into files on your server not accessible to the public.

Fortunately, unlike the computers that weighed thirty tons developed by the US Army, you won’t have to literally remove dead bugs from your machine to accomplish this! Now that we have some context, let’s take a more technical look at what goes into the WordPress debug process.

WordPress Debug Explained

As you likely know, WordPress is developed using PHP. That means that the official WordPress guide on debugging, as well as the official PHP debugging guide will be excellent resources to help you along the way.

In order to debug at all, WordPress requires you to have a global PHP variable defined. We’ll go over exactly how to do that in the next section.

It’s important to distinguish between how the PHP debugging process is different from the WordPress debug process. With vanilla PHP, only two types of errors are shown by default.One is a “fatal error”, meaning it’s so severe that the page cannot even load. The other is simply showing the user a blank page if there’s a “sensitive fatal error”. In other words, PHP knows that printing out the full error message could pose a security risk. These settings can easily be modified in PHP itself.

WordPress, on the other hand, is a bit wordier when it comes to debugging. If you simply enable WordPress debugging and do not customize it, every level of error, warning, and even informative items for developers will be displayed. That means everything from fatal errors to a technical message about how you should optimize a section of JavaScript will be shown. While this is extremely helpful for developers, it’s probably not the best content to show to users.

Another unique feature is that you’ll be notified about WordPress-specific PHP functions that have become deprecated. Functions that have become deprecated are ones that may still work now, but support will be dropped for them in the future. This also typically means that there’s a better, faster way of accomplishing the same process.

We know that you probably aren’t excited about debugging WordPress, but it’s critical if you wish to maintain a functional blog or site. Before you begin editing files, though, be sure to use a trusted WordPress backup plugin first. This way, if you accidentally make your site inoperable, you can restore everything in just a few clicks!

Now, let’s take a look at how we can get rolling!

How Do I Enable Debugging in WordPress?

In order to start the WordPress debug process, we’ll need a couple of lines of PHP.

Fire up your favorite text editor (as long as your favorite text editor isn’t the Windows Notepad!). If you need to grab one, Notepad++ is a commonly used, open-source text editor that supports almost every programming language.

Next, download a copy of your wp-config.php file. Do not edit the original file! We’ll simply upload the modified version once we’ve finished.

Once you’ve opened up wp-config.php in your text editor, you’ll need to add the following line of code. First, search for it to ensure you don’t already have it; PHP becomes very unhappy if you define the same variable twice!

define( 'WP_DEBUG', true );

All this line of code does is set that global PHP variable called WP_DEBUG to the boolean value of true.

Likewise, if you wanted to turn the WordPress debug feature off, you’d just put in the opposite line of code:

define( 'WP_DEBUG', false );

This turns on debugging, but that isn’t too helpful if we don’t know how to find the information that’s output!

Where is the WordPress Debug Log?

There are technically two answers to this question, and the exact answer depends on your choice.

As we said, one way is to just drop in define( ‘WP_DEBUG’, true );. This uses the default WordPress debugging log settings, which automatically creates a file if it doesn’t exist (or appends to it if it does) in the location wp-content/debug.log.

However, there are several reasons you might want it in a different location. For example, you may wish to have it in a location where a third-party debugging tool can access it. In order to customize where the debugging log is put, you can enable debugging like this:

define( 'WP_DEBUG_LOG', '/best-wp-dev/errors.log' );

WordPress Debug Log Explained

The level of detail of information in your WordPress debug log depends on how you configure it. If you simply enable it without any additional modifications, you will log pretty much every event that causes an error, uses a deprecated function, or isn’t optimal.

Since WordPress is built on top of PHP, your log will show every PHP error and warning thrown. It also will contain the date, time, and IP address associated with each event. Unfortunately, you’ll also get to see PHP’s (very) verbose output about many things, like code styling it doesn’t like, data validation it feels should be strengthened, and more.

Especially for people just getting started debugging WordPress, looking at the log file can be quite overwhelming. However, you should remember that only a few items are necessary.

Debugging vs. Logging

Though they aim to accomplish the same goal, it’s important you understand the difference between debugging and logging. In other words, the line define( ‘WP_DEBUG’, true ); does something completely different from the line define( ‘WP_DEBUG_LOG’, true );.

In no event should you use define( ‘WP_DEBUG’, true ); on a site accessible to the public. This command, when used by itself, will simply print debugging messages out. This does not log anything, and it will output information that could be used to steal data from your site(s). Ensuring that this is not turned on, in conjunction with a solid WordPress security plugin, will thwart the vast majority of attempted cyberattacks.

Debugging WordPress Without Risking Security

Obviously, you will need to regularly debug your site. However, you probably don’t want to constantly add and remove lines of code from your wp-config.php file.

Thinking through the process, we will first need to enable debugging in general. Then, we’ll need to make sure we log errors to make fixing them possible. However, we do not want to show these errors to the general public. Remember that we need to suppress both standard PHP errors and WordPress-specific errors from being shown.

Sample Secure WordPress Debug Code

Using the process we outlined above, here are four lines of code that can get you started with safely debugging your site!

define( 'WP_DEBUG', true ); define( 'WP_DEBUG_LOG', true ); define( 'WP_DEBUG_DISPLAY', false ); @ini_set( 'display_errors', 0 );

The first three lines above are simply setting global PHP variables that WordPress pays attention to. We’re making it possible to debug, setting up our logging functionality, and then turning off WordPress-specific errors.

Chances are that the fourth line looks like it came out of left field! This line is to address PHP errors that aren’t handled by WordPress. It’s the last base to cover to ensure that malicious users don’t get access to sensitive site information.

How Do I Fix a WordPress Debugging Error?

Quite often, developers will use those four lines of code we went over. They’ll experience an error, such as a database connection failure, but there will be nothing in the debugging log about it. This is because WordPress has different global PHP variables for different methods of debugging.

Let’s look at a few scenarios where you’ll need to add a few more lines to your wp-config.php file in order to debug WordPress properly.

Debugging WordPress JavaScript

If you have a WordPress site, there is a very high chance it uses JavaScript. For newer developers, this is essentially the language that powers interactive elements of sites. JavaScript is notorious for being quite tedious to debug. This is because modern sites often use frameworks on top of JavaScript, further complicating warnings and error messages.

Unfortunately, that’s not the only thing that makes debugging WordPress JavaScript difficult. There are two basic forms of JavaScript: asynchronous or “AJAX”, and regular JavaScript. Regular JavaScript operates in a linear fashion; it won’t run one function until execution of the one before it has concluded. Though this may have worked out in the earlier days of the web, it doesn’t cut it for web applications.

AJAX, on the other hand, operates in the background on your WordPress site. It allows you to run JavaScript functions and wait for their output, but it doesn’t prevent other functions from running. It’s often necessary to prevent sites from locking up.

The reason WordPress has us use another PHP global variable to say we want to debug scripts is because this method of debugging outputs a huge amount of data.

The reason WordPress has us use another PHP global variable to say we want to debug scripts is because this method of debugging outputs a huge amount of data. It’s also because JavaScript and CSS run on the client side, while PHP runs on the server side. In order to output every error WordPress runs into due to JavaScript and CSS, just add this line:

define( 'SCRIPT_DEBUG', true);

This will show both JavaScript and CSS (stylesheet) errors. It can also help with those more complex AJAX operations.

Fixing Data Issues

Almost every website grabs information from a database. WordPress has several databases; some sites store databases on separate servers, and some keep them on the same server. Since all configurations are different, there’s always a chance of something going wrong in your database connection.

If you get an error message saying that WordPress couldn’t connect to a database, or you notice that data isn’t being pulled correctly, you probably will need to debug. Simply using the standard WordPress debug variables, you’d likely notice that nothing would be logged when you encountered a database-related error.

This is because WordPress partitions database-related errors away from all other errors. Database error messages often contain sensitive information, and the developers of WordPress wanted to make sure you don’t accidentally divulge private information to the public!

In order to start debugging WordPress database problems, you will need to add yet another line to your wp-config.php file:

define( 'SAVEQUERIES', true );

Diving Into Database Debugging

Unlike our other global WordPress debug variables, we need to pay special attention to this one. “SAVEQUERIES” tells WordPress that we want to see every query run and its results returned. This will substantially harm sitewide performance! Be careful to not run this on your server at peak times, and turn it off as soon as you don’t need it.

It also stores its output a bit differently. WordPress uses a PHP array of strings that you will need to access to see database debugging information. It’s located in the PHP global variable called $wpdb and in the member array called queries. You can reach it by printing the contents of $wpdb->queries

Debugging WordPress Plugins

One prime advantage of WordPress over other platforms is its rich library of plugins that can do just about anything. You might be reading this and already getting a headache thinking about the logistics of needing to constantly change file contents. Thankfully, some plugins can help us with debugging WordPress! There are two particularly popular ones that make it a breeze.

WP Debugging

Located at the WordPress site, this is one of the best-known WordPress debug plugins. It essentially automates the processes we talked about already. With a few clicks from your dashboard, you can turn all of these PHP global variables on and off on your site.

When you install this plugin, you also install a series of plugins on which it depends. As a whole, they let you log and help you interpret errors you come across.

This tool is great for enabling the debugging process, but in order to debug your own plugins and to easily look at database-related WordPress debug information, you’ll need another plugin, too.

The Debug Bar

As its name suggests, the Debug Bar is simply a bar on the admin panel of your WordPress site. It can be used in conjunction with the WP Debugging tool.

It has tools for more advanced developers, allowing them to view the cache, queries that have been output, the results of queries, and more advanced information. Like we mentioned, WordPress drops all database debugging information into a PHP global variable.

In order to actually view that information, you would need to iterate through that array in a custom PHP file. This plugin gives you an easy alternative. It prints all of this information out for you in a format that’s quite easy to read and understand. It even gives you some tips on how to optimize your database calls!

Get the bonus content: 10 Features to Choosing a WordPress Backup Plugin

Debugging WordPress Themes

Debugging WordPress themes typically involves enabling the PHP global variable regarding scripts. This is because themes utilize client-side JavaScript and CSS.

First, ensure that it’s a theme that you authored. If it’s a third-party theme that’s experiencing problems, you’ll need to reach out to the author of that theme. It’d be pretty much trying to find a needle in a haystack to do it yourself!

If it’s your own theme, just ensure you followed the steps we discussed to enable debugging. Perform whatever action causes you to notice the bug. You can also enable the Developer Console within your web browser by pressing F12. This shows more client-level error messages that can help in the process.

After performing actions on your theme that lead to errors, consult the log. There should be detailed information there on what’s causing the errors. Chances are that it’ll just take a few JavaScript and/or CSS tweaks to get everything back to normal again!

Debugging WordPress Critical Error

If a plugin, theme, or other custom content generates an error causing your WordPress site to fail, your site should send you an email regarding the failure. Especially for newer webmasters, this can be distressing.

There’s no need to worry, as you can just follow this chain of steps to get the issue resolved in very little time!

  1. Make sure that you have turned on WordPress debug mode.
  2. Access your error log. It should have detailed information about the fatal error. If so, search for the exact error code online.
  3. Check your version of PHP. If it isn’t what WordPress currently requires, simply updating the PHP version your server uses could fix the issue.
  4. If you still have no luck, go through your plugins. Turn all of them off. If the site works, that means a plugin caused the issue. Go through them one-by-one until you find the problem plugin. Contact whoever wrote it and ask them to fix it.
  5. If you still haven’t found the problem, it could be a theme-related issue. Try reverting your current theme to the default WordPress one. If your site works, you’ll need to temporarily change themes until the author resolves the issue.
  6. No dice? Put your error up on the WordPress developers’ forum. There are plenty of users who would be happy to help you.

Wrapping Up

Debugging WordPress can help you solve a number of issues you encounter. It can tell you what plugins have issues or what issue you might have with a theme. As a WordPress Developer debugging helps you not only be a better developer but also helps you produce clean, quality code.

Posted by News Monkey