This section describes error handling in PHPlot. This information may not be accurate for PHPlot-5.0.4 and earlier.
Errors detected within PHPlot are programming or installation errors. These are conditions that web application users should never see, because they should be detected and corrected before an application is deployed. Therefore, error handling in PHPlot is aimed more at the developer than the application user.
PHPlot does the following by default when an error is detected:
Creates an error image - an image containing the text of the error message.
Outputs the error image to standard output or to a file, depending on where the plot image was supposed to go.
Triggers a user-level error condition. If an error handler has been established, it determines what happens next. Otherwise, with no error handler: Writes the error message to error output, or logs it to the web server error log, depending on the PHPlot SAPI in use. Then the script will exit with a non-zero exit status.
It is important not to have any text sent to standard output, even when an error occurs, or the image will be corrupted or PHP will display a "headers already sent" error and no image. Therefore it is necessary to turn off the PHP display_errors parameter, otherwise PHP will also write the error messages to standard output. This can be turned off in the php.ini configuration file, where it affects all scripts, or in an application script using:
ini_set('display_errors', 'off');
Note that an image is produced and output on error even if
SetPrintImage(False) is used to suppress or delay
the normal output of a plot image. The error image is meant for the application
developer or tester, but you need to see the error message in order to fix
the problem which caused it, so the image is output when the error occurs.
The following figure shows an example of an error image resulting from
$plot->SetPlotType('dots'):
You can disable the error image entirely using SetFailureImage (added in PHPlot-5.5.0). One case where this is recommended is when your script will use EncodeImage to get the plot image, rather than sending it to a file or back to the browser. Since your script is not intended to ever produce an image, it should not produce an error image either.
If a failure occurs when error images are disabled with
SetFailureImage, PHPlot will still trigger a user-level error
condition, which will normally record the error message in the server log,
and terminate the script. However, there will be no feedback to the user that
the error occurred.
If using SetFailureImage(False) to disable error images,
you should place this call right after creating the PHPlot object, because
an error which occurs before the call will produce an error image.
The following types of errors can occur within PHPlot:
Parameter value errors: Use of an incorrect argument to a PHPlot function, such as: SetPlotType('dots') ['dots' is not a valid plot type].
Semantic errors: Invalid combination of parameters or data values, such as trying to use data type 'data-data' with plot type 'bars' [bar charts only work with 'text-data' data type].
Pathname errors: Missing font file or invalid font path; missing or invalid image file used as background. It might seem extreme to have a missing font file be a fatal error, but PHPlot has no way to substitute an appropriate font, and a missing font would indicate an application configuration or installation error.
Inability to create a GD image resource. Probably the only way this can happen is if there is insufficient memory, which can occur if PHP's configured per-script memory limit is reached. (See note below)
All of these result in an E_USER_ERROR level error, except for memory exhaustion when creating an image, which is E_ERROR (fatal unrecoverable). If no GD image resource was created, no error image will be output. Furthermore, if the reason was memory exhaustion, there is no way to catch the error and PHP will cause the script to immediately exit.
It is possible to set up an error handler with PHP's
set_error_handler to catch most errors from PHPlot.
The handler can be established for all errors (the default), or just
E_USER_ERROR error types (the only type PHPlot will trigger).
See the PHP documentation for more details.
Your handler function can perform cleanup before it exits, however it should
not return.
Some of the PHPlot functions will correctly handle a return from an error
handler, and return FALSE to their callers, but not all. At the very least,
a PHPlot object instance should be unset and not re-used after error.
Note that if you do choose to have an error handler that returns, a return value of FALSE from the handler function will result in the standard PHP error handling, meaning the script will exit with an error message. If you want your script to continue after the handled error, your error handler must return TRUE. (A return with no value, or return of NULL, seems to work the same as TRUE, but this is not documented.)
Note that an error image will be created and output, as described above, even if you have established an error handler.
If you would like your application to handle some errors in a similar
manner to PHPlot, you can use DrawMessage to create
and output an image contain a message from your application.
See also Section 5.42, “Example - DrawMessage”.
(DrawMessage was added in PHPlot-5.7.0.)