Diving into WordPress errors

I would say that the most uncertain aspect of Helthe has been if it could do an amazing job monitoring WordPress errors. In the past, finding out what a problem was in WordPress has been a very frustrating (even table-flipping) experience for myself and a lot of people I have asked about it. So I set out to test and work on this critical assumption.

Can we have good error monitoring in WordPress? Is it already available? Here are my findings after 2 weeks.

What can you get right now?

I started looking through the plugin directory, did some some searching on Google and asked around. The result was some old diagnostic plugins (like Core Control) that do not seem to be supported anymore, but I am pretty sure they still work though.

You also had some error handling libraries (like the one for raygun.io) that would do something with PHP errors/exceptions (like email them to you or send them to their API).

A good start, but hardly what I was looking for. For example, no plugins could tell you if you had no PHP image editing libraries on your server. WordPress won’t give you an error, but you won’t be able to edit images without it. Often requiring you to debug for a few hours locating the issue.

When WordPress has an error, does it make a sound?

WordPress has a very unique philosophy around errors. This isn’t documented anywhere per say, but, if you are interested in reading about it, Nacin and Otto discuss their view on it in this WordPress hacker thread. At the end of the day, everything is a WP_Error and errors are coded defensively.

You will find that no exception are used in the code and that WordPress either has a fatal error (known as the white screen of death) or will fail silently without you being aware of it. The only errors that generally surface are the ones that will impact the user (Access Denied, Could not delete tag, etc.).

Because WordPress uses WP_Errors for everything, you are left to filter which, as a developer, are relevant to you. I asked around if there was documented hooks or filters where important errors might show up. The answer was that no work had been done to document them so I went deep into the core code to check it out.

Diving for answers

I had a tough time getting that answer. There’s no documentation available so I had to go through the code to find all the error handling code myself. If you’re interested in the process, I looked at every is_wp_error call in WordPress (there’s over 300 in 3.6) and then looked at all the functions and objects that were tied to that error check. That’s a lot of core code, but I was able to get a solid grasp of what was going on because of it.

After that I looked at all the wp_die calls (450+ of them in 3.6), this is a bit more tedious, but the idea was to look at what WordPress considered important enough to terminate itself. Often, they were normal reasons, but the goal was to find the error terminations and their cause.

Finally, I did take a look for new WP_Errors, but they ended not as useful as I had hoped. Critical objects do not always handle errors simply returning a new WP_Error. So while I started with this, it ended up the less useful research path.

What does WordPress do with errors?

As Nacin accurately described, there’s roughly 3 informal classification for WP_Errors. After spending a good two weeks looking at all the error code, I would generally agree with the classification given. He doesn’t really explain what WordPress does with each type so I’ll go through them and explain since this is not documented anywhere.

User Notices

These are specific errors that will surface to the user. They are generally the only WP_Errors that make it to a filter. Their purpose is to alert the user and provide feedback when an error relevant to the user occurs. Plugins can hook in and add their own error message as well. However, these errors are superficial and don’t really alert you to problems going on inside WordPress.

Warnings

These are the devious ones. Warnings are errors that do not directly affect the user experience, but prevent non-critical WordPress features from working. Quick examples are failed HTTP requests with the HTTP API and unable to select an image editor, but there’s plenty of others.

The big issue with these errors is that they very rarely make it to a filter. WordPress will simply return from the function and deal with those internally or dismiss them. As a developer or support individual, they are usually the ones you are the most interested in so it’s a real shame you cannot hook into them.

Failures

Failures are errors that need to be dealt with immediate or WordPress will not function. Most of those are found around the update code (plugins, theme and core), you’ll find some around the database code as well. They will either require user intervention or some form of rollback.

So what about the filters and hooks?

Yeah! What about those!? Like I mentioned previously, I wanted to document useful hooks where errors might show up.

I had initially thought I could use the ‘all’ hook (This hook runs for every hook/filter) to check every hook/filter for WP_Errors. You can’t use it that way. Any function using the ‘all’ hook runs before any other hook/filter function regardless of the given priority so if a plugin returns a WP_Error, you would not know. Bummer.

Besides that, there aren’t a lot of hooks or filters that are relevant if you are looking to check for application errors. Like I mentioned previously, WordPress tends to deal with them internally before they even hit a filter.

Where does this leave us?

As a developer, I hope that you have found the information useful so far. It was incredibly useful for me in getting a better sense of what was going internally in WordPress.

So in the next post, I’ll be introducing the Helthe plugin that I have been working on for monitoring WordPress errors and how I dealt with the limitations I have been discussing today.

Feel free to leave a comment below or discuss on Hacker News.

P.S. If you’d like to keep up to date with my progress with Helthe, leave your email below!

[mailchimpsf_form]