| 98 |
- |
1 |
<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
|
|
|
2 |
<!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>
|
|
|
3 |
This section describes error handling in PHPlot. This information may not
|
|
|
4 |
be accurate for PHPlot-5.0.4 and earlier.
|
|
|
5 |
</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>
|
|
|
6 |
Errors detected within PHPlot are programming or installation errors. These
|
|
|
7 |
are conditions that web application users should never see, because they
|
|
|
8 |
should be detected and corrected before an application is deployed.
|
|
|
9 |
Therefore, error handling in PHPlot is aimed more at the developer
|
|
|
10 |
than the application user.
|
|
|
11 |
</p><p>
|
|
|
12 |
PHPlot does the following by default when an error is detected:
|
|
|
13 |
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
|
|
14 |
Creates an error image - an image containing the text of the error message.
|
|
|
15 |
</p></li><li class="listitem"><p>
|
|
|
16 |
Outputs the error image to standard output or to a file, depending on where
|
|
|
17 |
the plot image was supposed to go.
|
|
|
18 |
</p></li><li class="listitem"><p>
|
|
|
19 |
Triggers a user-level error condition.
|
|
|
20 |
If an error handler has been established, it determines what happens next.
|
|
|
21 |
Otherwise, with no error handler:
|
|
|
22 |
Writes the error message to error output, or logs it to the
|
|
|
23 |
web server error log, depending on the PHPlot SAPI in use.
|
|
|
24 |
Then the script will exit with a non-zero exit status.
|
|
|
25 |
</p></li></ul></div><p>
|
|
|
26 |
It is important not to have any text sent to standard output, even when
|
|
|
27 |
an error occurs, or the image will be corrupted or PHP will display a "headers
|
|
|
28 |
already sent" error and no image. Therefore it is necessary to turn off the
|
|
|
29 |
PHP <span class="command"><strong>display_errors</strong></span> parameter, otherwise PHP will also
|
|
|
30 |
write the error messages to standard output. This can be turned off in the
|
|
|
31 |
php.ini configuration file, where it affects all scripts, or in an
|
|
|
32 |
application script using:
|
|
|
33 |
</p><pre class="programlisting">ini_set('display_errors', 'off');
|
|
|
34 |
</pre><p>
|
|
|
35 |
</p><p>
|
|
|
36 |
Note that an image is produced and output on error even if
|
|
|
37 |
<code class="function">SetPrintImage(False)</code> is used to suppress or delay
|
|
|
38 |
the normal output of a plot image. The error image is meant for the application
|
|
|
39 |
developer or tester, but you need to see the error message in order to fix
|
|
|
40 |
the problem which caused it, so the image is output when the error occurs.
|
|
|
41 |
</p><p>
|
|
|
42 |
|
|
|
43 |
The following figure shows an example of an error image resulting from
|
|
|
44 |
<code class="function">$plot->SetPlotType('dots')</code>:
|
|
|
45 |
</p><div class="informalfigure"><div class="mediaobject"><img src="images/error-image.png" alt="Example of an error image" /></div></div><p>
|
|
|
46 |
</p><p>
|
|
|
47 |
You can disable the error image entirely using
|
|
|
48 |
<a class="xref" href="SetFailureImage.html" title="SetFailureImage"><span class="refentrytitle">SetFailureImage</span></a> (added in PHPlot-5.5.0).
|
|
|
49 |
One case where this is recommended is when your script will use
|
|
|
50 |
<a class="xref" href="EncodeImage.html" title="EncodeImage"><span class="refentrytitle">EncodeImage</span></a> to get the plot image, rather than sending
|
|
|
51 |
it to a file or back to the browser. Since your script is not intended to ever
|
|
|
52 |
produce an image, it should not produce an error image either.
|
|
|
53 |
</p><p>
|
|
|
54 |
If a failure occurs when error images are disabled with
|
|
|
55 |
<a class="xref" href="SetFailureImage.html" title="SetFailureImage"><span class="refentrytitle">SetFailureImage</span></a>, PHPlot will still trigger a user-level error
|
|
|
56 |
condition, which will normally record the error message in the server log,
|
|
|
57 |
and terminate the script. However, there will be no feedback to the user that
|
|
|
58 |
the error occurred.
|
|
|
59 |
If using <code class="literal">SetFailureImage(False)</code> to disable error images,
|
|
|
60 |
you should place this call right after creating the PHPlot object, because
|
|
|
61 |
an error which occurs before the call will produce an error image.
|
|
|
62 |
</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>
|
|
|
63 |
The following types of errors can occur within PHPlot:
|
|
|
64 |
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
|
|
|
65 |
Parameter value errors: Use of an incorrect argument to a PHPlot function,
|
|
|
66 |
such as: SetPlotType('dots') ['dots' is not a valid plot type].
|
|
|
67 |
</p></li><li class="listitem"><p>
|
|
|
68 |
Semantic errors: Invalid combination of parameters or data values, such as
|
|
|
69 |
trying to use data type 'data-data' with plot type 'bars' [bar charts only
|
|
|
70 |
work with 'text-data' data type].
|
|
|
71 |
</p></li><li class="listitem"><p>
|
|
|
72 |
Pathname errors: Missing font file or invalid font path; missing or
|
|
|
73 |
invalid image file used as background. It might seem extreme to have a
|
|
|
74 |
missing font file be a fatal error, but PHPlot has no way to substitute an
|
|
|
75 |
appropriate font, and a missing font would indicate an application
|
|
|
76 |
configuration or installation error.
|
|
|
77 |
</p></li><li class="listitem"><p>
|
|
|
78 |
Inability to create a GD image resource. Probably the only way this can
|
|
|
79 |
happen is if there is insufficient memory, which can occur if PHP's
|
|
|
80 |
configured per-script memory limit is reached. (See note below)
|
|
|
81 |
</p></li></ol></div><p>
|
|
|
82 |
All of these result in an E_USER_ERROR level error, except for memory
|
|
|
83 |
exhaustion when creating an image, which is E_ERROR (fatal unrecoverable).
|
|
|
84 |
If no GD image resource was created, no error image will be output.
|
|
|
85 |
Furthermore, if the reason was memory exhaustion, there is no way to catch
|
|
|
86 |
the error and PHP will cause the script to immediately exit.
|
|
|
87 |
</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>
|
|
|
88 |
It is possible to set up an error handler with PHP's
|
|
|
89 |
<code class="function">set_error_handler</code> to catch most errors from PHPlot.
|
|
|
90 |
The handler can be established for all errors (the default), or just
|
|
|
91 |
E_USER_ERROR error types (the only type PHPlot will trigger).
|
|
|
92 |
See the PHP documentation for more details.
|
|
|
93 |
Your handler function can perform cleanup before it exits, however it should
|
|
|
94 |
not return.
|
|
|
95 |
Some of the PHPlot functions will correctly handle a return from an error
|
|
|
96 |
handler, and return FALSE to their callers, but not all. At the very least,
|
|
|
97 |
a PHPlot object instance should be unset and not re-used after error.
|
|
|
98 |
</p><p>
|
|
|
99 |
Note that if you do choose to have an error handler that returns, a return
|
|
|
100 |
value of FALSE from the handler function will result in the standard PHP error
|
|
|
101 |
handling, meaning the script will exit with an error message. If you want
|
|
|
102 |
your script to continue after the handled error, your error handler must
|
|
|
103 |
return TRUE. (A return with no value, or return of NULL, seems to work the
|
|
|
104 |
same as TRUE, but this is not documented.)
|
|
|
105 |
</p><p>
|
|
|
106 |
Note that an error image will be created and output, as described above,
|
|
|
107 |
even if you have established an error handler.
|
|
|
108 |
</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>
|
|
|
109 |
If you would like your application to handle some errors in a similar
|
|
|
110 |
manner to PHPlot, you can use <a class="xref" href="DrawMessage.html" title="DrawMessage"><span class="refentrytitle">DrawMessage</span></a> to create
|
|
|
111 |
and output an image contain a message from your application.
|
|
|
112 |
See also <a class="xref" href="ex-drawmessage.html" title="5.42. Example - DrawMessage">Section 5.42, “Example - DrawMessage”</a>.
|
|
|
113 |
(<code class="function">DrawMessage</code> was added in PHPlot-5.7.0.)
|
|
|
114 |
</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>
|