Blame | Last modification | View Log | RSS feed
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><title>3.9. Error Handling</title><link rel="stylesheet" type="text/css" href="phplotdoc.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><link rel="home" href="index.html" title="PHPlot Reference Manual" /><link rel="up" href="concepts.html" title="Chapter 3. PHPlot Concepts" /><link rel="prev" href="conc-text.html" title="3.8. Text Fonts" /><link rel="next" href="advanced.html" title="Chapter 4. PHPlot Advanced Topics" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3.9. Error Handling</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="conc-text.html">Prev</a> </td><th width="60%" align="center">Chapter 3. PHPlot Concepts</th><td width="20%" align="right"><a accesskey="n" href="advanced.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="conc-errors"></a>3.9. Error Handling</h2></div></div></div><div class="abstract"><p class="title"><strong></strong></p><p>This section describes error handling in PHPlot. This information may notbe accurate for PHPlot-5.0.4 and earlier.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="conc-errors-overview"></a>3.9.1. Error Handling Overview</h3></div></div></div><p>Errors detected within PHPlot are programming or installation errors. Theseare conditions that web application users should never see, because theyshould be detected and corrected before an application is deployed.Therefore, error handling in PHPlot is aimed more at the developerthan the application user.</p><p>PHPlot does the following by default when an error is detected:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Creates an error image - an image containing the text of the error message.</p></li><li class="listitem"><p>Outputs the error image to standard output or to a file, depending on wherethe plot image was supposed to go.</p></li><li class="listitem"><p>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 theweb server error log, depending on the PHPlot SAPI in use.Then the script will exit with a non-zero exit status.</p></li></ul></div><p>It is important not to have any text sent to standard output, even whenan error occurs, or the image will be corrupted or PHP will display a "headersalready sent" error and no image. Therefore it is necessary to turn off thePHP <span class="command"><strong>display_errors</strong></span> parameter, otherwise PHP will alsowrite the error messages to standard output. This can be turned off in thephp.ini configuration file, where it affects all scripts, or in anapplication script using:</p><pre class="programlisting">ini_set('display_errors', 'off');</pre><p></p><p>Note that an image is produced and output on error even if<code class="function">SetPrintImage(False)</code> is used to suppress or delaythe normal output of a plot image. The error image is meant for the applicationdeveloper or tester, but you need to see the error message in order to fixthe problem which caused it, so the image is output when the error occurs.</p><p>The following figure shows an example of an error image resulting from<code class="function">$plot->SetPlotType('dots')</code>:</p><div class="informalfigure"><div class="mediaobject"><img src="images/error-image.png" alt="Example of an error image" /></div></div><p></p><p>You can disable the error image entirely using<a class="xref" href="SetFailureImage.html" title="SetFailureImage"><span class="refentrytitle">SetFailureImage</span></a> (added in PHPlot-5.5.0).One case where this is recommended is when your script will use<a class="xref" href="EncodeImage.html" title="EncodeImage"><span class="refentrytitle">EncodeImage</span></a> to get the plot image, rather than sendingit to a file or back to the browser. Since your script is not intended to everproduce an image, it should not produce an error image either.</p><p>If a failure occurs when error images are disabled with<a class="xref" href="SetFailureImage.html" title="SetFailureImage"><span class="refentrytitle">SetFailureImage</span></a>, PHPlot will still trigger a user-level errorcondition, which will normally record the error message in the server log,and terminate the script. However, there will be no feedback to the user thatthe error occurred.If using <code class="literal">SetFailureImage(False)</code> to disable error images,you should place this call right after creating the PHPlot object, becausean error which occurs before the call will produce an error image.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="conc-errors-types"></a>3.9.2. Types of Errors</h3></div></div></div><p>The following types of errors can occur within PHPlot:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Parameter value errors: Use of an incorrect argument to a PHPlot function,such as: SetPlotType('dots') ['dots' is not a valid plot type].</p></li><li class="listitem"><p>Semantic errors: Invalid combination of parameters or data values, such astrying to use data type 'data-data' with plot type 'bars' [bar charts onlywork with 'text-data' data type].</p></li><li class="listitem"><p>Pathname errors: Missing font file or invalid font path; missing orinvalid image file used as background. It might seem extreme to have amissing font file be a fatal error, but PHPlot has no way to substitute anappropriate font, and a missing font would indicate an applicationconfiguration or installation error.</p></li><li class="listitem"><p>Inability to create a GD image resource. Probably the only way this canhappen is if there is insufficient memory, which can occur if PHP'sconfigured per-script memory limit is reached. (See note below)</p></li></ol></div><p>All of these result in an E_USER_ERROR level error, except for memoryexhaustion 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 catchthe error and PHP will cause the script to immediately exit.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="conc-errors-handle"></a>3.9.3. Error Handlers</h3></div></div></div><p>It is possible to set up an error handler with PHP's<code class="function">set_error_handler</code> to catch most errors from PHPlot.The handler can be established for all errors (the default), or justE_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 shouldnot return.Some of the PHPlot functions will correctly handle a return from an errorhandler, 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.</p><p>Note that if you do choose to have an error handler that returns, a returnvalue of FALSE from the handler function will result in the standard PHP errorhandling, meaning the script will exit with an error message. If you wantyour script to continue after the handled error, your error handler mustreturn TRUE. (A return with no value, or return of NULL, seems to work thesame as TRUE, but this is not documented.)</p><p>Note that an error image will be created and output, as described above,even if you have established an error handler.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a id="conc-errors-app"></a>3.9.4. Application-level Errors</h3></div></div></div><p>If you would like your application to handle some errors in a similarmanner to PHPlot, you can use <a class="xref" href="DrawMessage.html" title="DrawMessage"><span class="refentrytitle">DrawMessage</span></a> to createand output an image contain a message from your application.See also <a class="xref" href="ex-drawmessage.html" title="5.42. Example - DrawMessage">Section 5.42, “Example - DrawMessage”</a>.(<code class="function">DrawMessage</code> was added in PHPlot-5.7.0.)</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="conc-text.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="concepts.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="advanced.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.8. Text Fonts </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 4. PHPlot Advanced Topics</td></tr></table></div></body></html>