Chapter 6. Error handling

Table of Contents

6.1. The problem with error messages and images
6.1.1. Catching errors in other parts of the system while creating images
6.2. Available error messages
6.2.1. Localizing error messages
6.2.2. Error messages on a production server
6.3. Using PHP Exceptions
6.3.1. Selecting between text and image based error handling
6.3.2. Writing error message to a log file (or system logger)
6.4. Adding a new locale

The problem with error messages and images

Why a whole chapter on error handling? The answer is that error handling with scripts that produces images requires a slightly different approach than normal error messages. In order to appreciate the added complexity one needs to consider how a graph script is called. Usually a graph script is called from an <img> tag. This means that the client (e.g. the browser) expect image data to be sent from the script. If we instead send a textual error message the browser will not be able to display anything. It was expecting a stream with image data and the data received was a representation of an error message which of course cannot be interpreted as an image.

To handle this problem the error messages produced by the library are normally generated as an image. A typical error message can be seen in Figure 6.1. Typical image error message

Figure 6.1. Typical image error message

Typical image error message

There is one exception to this rule and that is in the case of the "Headed already sent" error message. This means that the client has already received an header and with probability bordering on certainty this is a text header. Hence in this case it does not make sense to send an image so this, and only this, error message is sent as a normal "text/html" type message. A typical example how this message is shown in the browser can be seen in Figure 6.2. The "Header already sent error message"

Figure 6.2. The "Header already sent error message"

The "Header already sent error message"

When you get this error (and we mean when - not if) take a very close look at the text in red. This will tell you in what file and what line the erroneous output started. In most cases this will be an innocent looking space or a tab character. It could also be caused by multiple newlines at the end of a file. Since by definition these mistakes can be hard to spot since spaces and tabs are not normally visible in an editor so take care!

Catching errors in other parts of the system while creating images

The problem described in the previous section will also apply to error messages that are generated directly from PHP as well. In order to be able to see any potential error messages during development it is possible to instruct the library to intercept PHP error messages and convert them to image messages instead. This is controlled by the two defines INSTALL_PHP_ERR_HANDLER and CATCH_PHPERR define in jpg-config.inc.php

INSTALL_PHP_ERR_HANDLER

Setting this define to true will make the library install a custom error handler which will catch all PHP error messages and convert them into an image like what can be seen in Figure 6.1. Typical image error message.

By default this is disabled.

CATCH_PHPERR

This defines control whether the library shall check for any generated error message that are stored in the global PHP pre-defined variable php_errmsg. This can be very useful during development if an error has occurred prior to calling the graph script. This error will then be displayed as an image.

By default this is enabled.