how to determine failure in ajax request - php

Question

I'm working with Mootools to develop a simple ajax-y page that does some manipulation with db records using PHP as the backend.
I'm submitting the ajax request to a PHP page that calls a function and returns TRUE or FALSE if the record was able to be updated/deleted or not.
However, it seems like the mootools onSuccess event is fired anytime the server returns a 200 status, regardless of the value returned (eg. FALSE is still assumed to be a success).
How do I use onSuccess in a meaningful way, short of returning a 40x error code or something?

Answer 1

All answers given by #dombenoit and #Marc are technically correct.
However, I totally differ from #Marc's vision: to me, using HTTP status codes is both efficient and common for webservices. I use them all the times and much favor them over outputting text, mainly for the following reasons:
they give a free standard for handling incorrect values, instead of making you output text and parsing it clientside, meaning semantical repetition;
they make all tools understand something went wrong, as the question itself outlines;
they feel right in a REST architecture.
To support this vision, here's a question: what's the goal of your call? Is it to update or delete a record? Then if this goal is not reached, something went wrong. It failed, and the application should know it at application-level, not through first saying 200/OK and then precising in the textual response it did not! To me, it feels like using "undefined" instead of undefined.
So, here, I would make PHP send an HTTP error status code, that is one in the 4xx-5xx ranges.
Then, the good question is: which code to use? This is a design decision that totally depends on your application and the degree of specificity you want to get to.
If the goal of the call is to update / delete, and the fact that it does not happen is extremely unlikely and is an unexpected, serious error (for example: the DB is inconsistent because there's no way the call could reference an entity that does not exist), then you should use 500 / Internal Server Error.
If it could be possible that the targeted entity does not exist at the time of the call without it being a critical error (example: your app provides several ways to delete an item, so another one could have been used instead of this call), then I'd advise 410 / Gone: you get a clear, expressive error handling, for free! And you can still use 500 for actual errors (DB connexion exceptions…).
Then, you could get even more specific about update errors only, for example with 409 / Conflict if that's the kind of errors you're trying to foresee with updates…
I always give a look at the HTTP status codes reference when I'm designing a webapp.
Just for the sake of completion, that's how you send headers in PHP (without framework at least — check for specificities):
header("HTTP/1.0 404 Not Found");
UPDATE: since it seems you decided to go with the answer that suggested to use JSON to encode success or failure, I have to add the following points about resilience.
Not relying on status codes and only on application-level data makes your code very fragile. Indeed, there are situations where you get actually unexpected errors. Not the application-level “exception” that you raised yourself, but something wrong on a lower level (server unavailable, bad config that makes the server crash, changed routing system…). These will all show through HTTP status codes (or through timeout), but not through a JSON-encoded answer, since your application will have already crashed before being able to output anything.
Like #Dimitar put it, from a programming point of view, this is somehow “naive”: you trust not only your code (you shouldn't), but also the environment (server) and the network. That's a very, very optimistic vision.
Using status codes as the standard way to handle expected exceptional situations give you a free handling of those unexpected situations: you've already registered other handlers than onSuccess, and supposedly good ones (retrying once, notifying the user, offering backup possibilities…).

Answer 2

Personaly, I feel that using the HTTP status codes to indicate the success/failure of whatever was supposed to happen on the server is incorrect. Everything about the HTTP call itself worked perfectly - the fact that the server was unable to complete the request doesn't mean the HTTP request failed.
It's like driving to the store to buy something, only to find it's out of stock. Returning an HTTP 404, to me, would imply that the store itself was gone. Yet, you've successfully driven to the store, walked inside, walked back out, drove home.
So, use a JSON data structure to indicate the results of the requested transaction, which you can check for in your client-side code:
$results = array()
$results['success'] = false;
$results['failure_code'] = XXX; // some code meaningful to your app
$results['failure_message'] = 'Something dun gone blowed up, pa!';
echo json_encode($results);
Then in your Moo code:
if (!results['success']) {
alert("AJAX call failed: " + results['failure_message']);
}
If the call worked, then you'd have
$results = array();
$results['success'] = true;
$results['data'] = ....;

Answer 3

You have a couple options, two of which you mentionned in your question. You can use onSuccess and execute some code based on a true/false response, like so :
onSuccess: function(responseText, xml){
if(responseText == "false"){
// do something...
}
}
Or you could raise errors in your PHP code, returning an actual valid error code thus firing the onFailure event.
Or as mentionned by Marc previously, you could use a JSON response format, in which case you would use MooTools' Request.JSON.
onSuccess: function(responseJSON, responseText){
// do something...
}