When should I throw an exception as opposed to return an error in PHP?

Question

I'm working on an API wrapper class, which is the first I've made. For the most part it hasn't been too difficult. Getting to the point where I need to deal with the potential of errors being returned by the API, however confused as to how I should go about dealing with them.

An external file will make a call to the API class, ie, findVenueByLocationID($locationID); This function will then construct the URL and method of API call (POST, GET, DELETE, etc) and pass that to a function called makeCall.

MakeCall constructs the completed URL, sends the request to the service and passes back the resulting XML. If the API returns an error, it is within the XML it returns. The URL is called using the function file_get_contents(). The API has a set number of error codes it will return in the XML.

As I understand it, I should do the following during the function makeCall:

• Before the XML is returned, check to see if it contains an error code, and if so, pass that to an error handling class to deal with the error. (Log and return client version error message)
• add a try catch around the file_get_contents() function to catch any connection errors, ie not being able to access the server?

Is that considered the best way to do things? Should I be adding a try catch around the call to makeCall rather than inside it round file_get_contents? Should I be throwing an exception for each error returned by the XML and handling them with an error class?

The sort of answer I'm looking for should also contain a link to a resource explaining some best practices surrounding error handling with API wrappers or such things.

Thanks in advance for your time and responses.

---

EDIT: After talking with our CTO, errors in PHP at current version ARE exceptions, and I should throw exceptions and leave the dealing of the exceptions to the caller. Remember, I'm implementing a wrapper class for an API. Thoughts?

Answer 1

You should first know the difference between exceptions and errors: errors happen, exceptions are exceptional.

For instance, a user who types a wrong password (cannot log in) gets an error. When the database is not available while checking the password, you would get an exception (and hopefully graceful handling of that exception).

So if you get XML from a third party you would probably expect it to be valid. But there could be errors. If the API gives you an error (location not found) it will probably be an error on your side too. Only in special cases (you've hardcoded a location you know for sure will always be there) that might be an exception.

The most trivial exceptions are the connection errors: there is most definitely something wrong then. The other easy thing are errors in the API that you could expect, like "no new information" (Just as an example): This is an internal error. And somewhere you must draw a line, but in most cases it is kinda clear what is exceptional and what is just an error that can occur.