Software Engineering in WordPress and Musings on the Deep Life

Ajax in WordPress: A Strategy For Error Codes

If you're reading this post in an RSS reader, don't forget to click on the "gist" link to see the code for the post.

In the previous post, I talked through the basics of setting of Ajax in WordPress on both the server-side and the client-side and how we can echo statements back to the client-side and why this is useful.

Ajax in WordPress: Error Codes

What I didn’t cover, though, was why this is important and how we can take advantage of it for gracefully handling any errors that occur throughout our code.

Whenever you’re dealing with a number of different variables such as user input, values of input fields, talking to the database, and network connections, there are a number of places in which the request and/or the response can fail.

And in those cases, we need to be able to make sure our project handles the situation well so we’re able to diagnose the problem and so our users aren’t left wondering what went wrong.

Handling Error with Ajax in WordPress

When it comes to handling errors that occur with Ajax in WordPress, I’m assuming you have the normal safeguards in place.

That is, I’m assuming you’re making sure all of the user interface elements are set so, say, the user can only submit after they’ve provided all of the valid data (as valid as you can asset on the client-side, anyway).

The primary area in which I’m focused in this particular post has to do with what happens after the user has submitted the data and the server is working with said information to attempt to work with the data and send a response back to the user.

Here’s the thing: Coming up with an example that will demonstrate what to do in every case is impossible. As such, I’m going to be using a single concrete example.

That doesn’t mean, though, there aren’t principles applicable to a wider scope of projects.

My Strategy For Error Codes

Before I show any source code, I thought it would be worth discussing what it is I do to in order to evaluate if a request was successful or not.

  1. I come up with a set of error codes I will use to send back to the server.
  2. For each error code, I will document what each code means in a PHP DocBlock.
  3. Each error code will be appropriately handled on the client-side.
  4. Information may be written to a log file a user can send to help pinpoint their problem.

It’s basic, isn’t it? Then again, why does it need to be anything complicated? Why do we – as programmers – use extraordinarily convoluted error messages and exceptions to catch whenever something goes wrong in a program?

I know, I know – sometimes it has to do with the library in which the code is contained, sometimes it has to do with a stack trace, and sometimes it has to do with something that’s outside of our control.

But when when it’s within our control, why not make it easy as possible on ourselves and our other programmers?

Defining Error Codes

Let’s say I have some server-side code is called via the web browser. And in this code, it’s responsible for taking a set of information – let’s say it requires a Post ID, a value from a form, and whether or not a user has already voted (as discussed in the previous post) – before it can do any work.

This means there are a number of places it can already fail:

  1. It needs the post ID I’ll creatively refer to as `post_id`
  2. It needs the current user ID which I’ll aptly refer to as `user_id`
  3. And it needs to be able to retrieve a value from the database to determine if the user has voted which I’ll refer to as `has_voted`

If any of these values are missing, then we can’t proceed with our work. If, on the other hand, we can continue to go about doing our work and then we can send the requested information back to the user.

Here’s the neat thing about the list of requirements above: Each of them are numbered. That is, we have values that are 1, 2, and 3. Can these be the error codes?

Sure.

But whenever something goes wrong, I usually like to indicate that as a negative value and something going write as a positive value. So let’s say we take the values above and simply negate them.

Thus, our error codes code out to be -1, -2, -3.

Error Codes On The Server-Side

To implement this in the Ajax in WordPress system, we’ll need to setup some conditionals especially if it’s expecting three pieces of information. Furthermore, we’ll need to echo the error code, call wp_die() so the code halts, and make sure our DocBlock is clear as to what’s happening.

So when we tie all of the above together, what might the code look like? Perhaps like this:

Will yours look like this? Maybe. Maybe not. It depends on how you choose to architect it. If you require more information, it’s probably wise to setup a separate set of functions (or even an object) to handle the situation. But when we’re working with three things, then I think a few conditionals are fine.

Anyway, from the code above, you can see we’ve done all we set out to do:

  1. Defined the error codes
  2. Explained them in the DocBlock
  3. Sent a value back to the client

Now we need to do something with the client-side.

Error Codes On The Client-Side

This is where we take the information that’s returned from the server-side and handle it on the client-side. In the code I’m going to show, I’m leaving implementation details up to you.

The key here is to notice how the error codes are handled in the response:

Since I only have three potential error codes and a single success path, then using a switch/case is fine for me; however, if there were a greater number of error codes and/or failure points then I would definitely use a separate object for handling these errors.

In fact, I may even consider throwing an exception depending on how this code was invoked. But that’s beyond the point of what’s being shown here. Instead, I’m trying to show the relationship between what’s thrown on the server-side being caught on the client-side and then how it can be handled.

Notice in the default case, everything checks out and we’re ready to do whatever’s necessary to continue working in the program.

What About Logging?

The one thing I didn’t mention in the content above is about writing an error log. Sure, you can choose to write the information to file, you can choose to write the information to the database, or you can choose to send the information to an email address.

Whatever it is you opt to do, make sure the user is aware information is being captured and can be potentially sent to you. Furthermore, be clear as to what information is captured.

All of the above is outside of the scope of what I’m trying to demonstrate with this post, but whenever it comes to sending information about something has happened on a user’s computer, I’m always very careful to detail exactly what’s sent (and even show them, if possible).

That’s All (For Now)

That’s all I have to share about this particular issue. It’s nothing terribly complicated, but I think it’s something we should all be doing in order to make our code more robust.

There’s no need to make the code as convoluted as some of the things we, as programmers, are used to seeing, but we still need to treat the issues with a level of significance that can detail exactly what a user experienced, try to fix it, and then try to resolve the problem in an elegant fashion.

With that said, I also know what I’ve been doing could be amateur. Or maybe it’s missing something. Or maybe there’s simply room or improvement.

Whatever the case, I’m interested to hear your feedback in the comments. And as I continue to work with these types of projects, I’ll continue to write about the things I’ve learned and why I have (or haven’t) changed my approach.

8 Comments

  1. Richard sweeney

    What about wp_send_json_success|error() ? I get it’s handy to have some error codes but you could still wrap it all up in a nice response from WP.

    • Tom

      What about wp_send_json_success|error() ? I get it’s handy to have some error codes but you could still wrap it all up in a nice response from WP.

      TBH, I honestly wasn’t familiar with this function. I love trying to stick with the native APIs so it’s one I’m definitely going to explore more. My biggest concern though has to do with how much of a response can I send along with true and/or false.

      I like to try to have more details just either a binary “it worked” or “it didn’t,” you know?

      • Timothy Jacobs

        Tom, what I usually do when using those functions is pass along either an error code, usually accompanied by an error message ( its easier than passing a translated message to wp_localize_script() ) in the data parameter.

        • Tom

          Thanks for sharing this – it’s good stuff (and you’re right in that it can be easier than handling i18n. That’s a topic I wasn’t even trying to touch with this post. ;)

  2. Ronald Huereca

    Great post Tom.

    For Ajax, I prefer a WP error class object and I use error slugs to read in the messages, and then pass those back to the user. Makes it a bit easier to organize and a bit more readable/translatable.

    • Tom

      For Ajax, I prefer a WP error class object and I use error slugs to read in the messages, and then pass those back to the user. Makes it a bit easier to organize and a bit more readable/translatable.

      This is actually a fantastic idea. I feel lame for not even thinking about it in the context of Ajax.

      I’ve used it often when building plugins and handling things on the server-side, but combining it with the server and the client, for whatever reason, simply isn’t something I’ve considered.

      I chalk it up to experience in other languages, but great idea. Thanks for sharing this.

  3. Firdaus Zahari

    Hi Tom,

    I would usually do wp_send_json_error as Richard sweeney suggests. It has automatic detection of WP_Error class (https://developer.wordpress.org/reference/functions/wp_send_json_error/#source-code), as well as calling the native wp_send_json function, which is extremely useful so that the response is sent with a proper content type.

    The in the js file, you can always check for the response.success value, if it’s false, the error messages is contained in the response.data key already.

    So, your code can be simplified by having all the errors on the server side, and your public facing js only needs to echo out the errors if necessary.

    • Tom

      I would usually do wp_send_json_error as Richard sweeney suggests.

      Agreed. Unfortunately, I didn’t know much about this until this post (so thanks to everyone who’s commented :). Sometimes digging through the Codex for this kind of stuff can yield less than stellar results.

      The in the js file, you can always check for the response.success value, if it’s false, the error messages is contained in the response.data key already.

      This is true – it requires a little more work on the JavaScript side in order to make the code as clean and readable as possible (like asking if success has an error? :), but I’m just being picky at this point.

      So, your code can be simplified by having all the errors on the server side, and your public facing js only needs to echo out the errors if necessary.

      I like this – there are going to be some changes I make to the code in this post. If this one doesn’t make it, don’t think I don’t like it. I only have so much time per day to allot to making changes to things like this ;).

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

© 2023 Tom McFarlin

Theme by Anders NorenUp ↑