Welcome to part four of a five-part series on creating a dynamic Twitter signature image in PHP. In the last segment, I showed you how to implement PHP 5 exceptions as an error-handling mechanism in your signature image application. Today we're going to expand upon that concept by creating a custom exception class for handling error states in our application.
The code you have for this application so far is fully functional and includes full error-handling. You may be wondering what the need is for a custom exception class in the first place. So I'd like to take a moment to discuss why I've chosen to create one.
This application serves a single purpose. It accepts an input and delivers an image to the browser. In the event of an error, the script halts execution and displays that error.
The problem lies in this difference in output.
The calling page is expecting an image and therefore won't display the error text. So to make this useful, it might be a good idea to deliver the error text as an image instead.
Since this only needs to be done in the event an exception occurs in our application, it makes sense that the code to produce this image should reside in a custom exception. This also provides an opportunity to explore a little deeper into PHP 5's error handling capabilities.
For those readers that are just now tuning in, let's take a look at the code we have so far. On the next page you'll see the SignatureImage class in its entirety.
// Unable to add avatar to image.
To begin piecing together a custom exception, you'll first need to understand how the native Exception class is constructed. For that you'll need to sit down and examine the PHP documentation, so I'll save you a little time.
In the code above I've created an interface that lists all of the methods provided by the native Exception class. By implementing this interface in our own custom exception class, we'll have a framework to ensure that our own exception is constructed in the same manner as the original.
In larger applications, this allows multiple developers to implement any custom exception without the need for additional documentation. That's an important time-saver any time you have more than one developer collaborating on a project.
Now that we've got an interface to define our custom exceptions, we can begin putting the code together to make it work.
We're going to build a custom exception called SignatureImageException. Every error in our SignatureImage class will throw this same type of exception. In larger applications, you'd most likely have a unique exception for each type of error thrown by a particular class. Due to the small footprint of this application, it's overkill to have so many different exceptions that will inherently perform the same task.
We begin building our custom exception class by writing its declaration. Notice that this exception class will be extending the native Exception class (meaning that it will inherit all of its functionality) and that it also implements the interface we've just created. This provides a level of continuity by ensuring that our class cannot be created without all of the required parts. I've also gone one step farther and declared this as a final class, since our application won't be extending upon it.
The next step is to add the necessary class properties. These are the same properties used by the native Exception class. The $message property will contain a text string containing the exception message and the $code property will contain a user-supplied error code as an integer.
After defining the properties for our class, we'll want to override the native Exception class's constructor with one of our own. In the native Exception class, all of the constructor's parameters are optional. We're overriding that with a constructor declaration that makes the message and code parameters required.
Next, you'll see a simple If block. Here I'm checking that the message parameter contains a usable value. If it's null or an empty string, the SignatureImageException is re-thrown with the message "Unknown exception." This ensures that the image produced by our custom exception class will always have a visible message for the end-user.
Finally, we make a static call to the Exception class's constructor. This ensures that all information is preserved and correctly passed to all parent objects. It also executes the native code that properly assigns all of the internal properties for our custom exception class. No need to write the code ourselves!
Now we wrap up our custom exception class by creating a method that will produce and output an image containing our error message. Since the majority of this code has been covered in the previous articles in this series, I won't go into great detail about its inner workings.
I do want you to notice, however, the manner that I've used to handle errors in this portion of the code. To this point, our custom exception relies on the fact that it creates and outputs an image. If this code fails for any reason, the whole concept behind this application fails with it.
For that reason, any errors produced while attempting to create the image will be thrown as general Exceptions which don't rely on the need to create an image for the error. This provides an excellent example of a situation in which a custom exception is better re-thrown as a lower level exception within an application.
In order to implement our newly-created custom exception, we'll need to revisit the SignatureImage class that we built over the past few articles. Throughout that code, we you'll see instances of errors being thrown as shown below.
Implementing our new custom exception is as simple as editing the line that throws a native Exception and updating it with our custom exception instead.
And there you have it! Now instead of receiving error messages as text in the browser, they are built into an image to maintain compatibility with the expected output of our SignatureImage class.
Here again we part with a fully-functioning application. But I'm coming back for one more article in this series in which I will show you how to boost the performance of this application, overcome a pitfall in the Twitter API, and add a method of monitoring your image's analytics. Until next time, keep coding!