ch06.html
8.27 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 6. Error handling</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="pt02.html" title="Part II. Basic graph creation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 6. Error handling</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Part II. Basic graph creation</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="chapter" title="Chapter 6. Error handling"><div class="titlepage"><div><div><h2 class="title"><a name="chap.error-handling"></a>Chapter 6. Error handling</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="ch06.html#id2495302">6.1. The problem with error messages and images</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch06.html#id2495400">6.1.1. Catching errors in other parts of the system while creating images</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch06s02.html">6.2. Available error messages</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch06s02.html#sec2.localizing-errmsg">6.2.1. Localizing error messages</a></span></dt><dt><span class="sect2"><a href="ch06s02.html#id2495515">6.2.2. Error messages on a production server</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch06s03.html">6.3. Using PHP Exceptions</a></span></dt><dd><dl><dt><span class="sect2"><a href="ch06s03.html#id2495896">6.3.1. Selecting between text and image based error handling</a></span></dt><dt><span class="sect2"><a href="ch06s03.html#id2495901">6.3.2. Writing error message to a log file (or system logger)</a></span></dt></dl></dd><dt><span class="sect1"><a href="ch06s04.html">6.4. Adding a new locale</a></span></dt></dl></div>
<div class="sect1" title="The problem with error messages and images"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2495302"></a>The problem with error messages and images</h2></div></div></div>
<p>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
<span class="markup"><img></span> 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.</p>
<p>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 <a class="xref" href="ch06.html#fig.errmsg-ex1" title="Figure 6.1. Typical image error message">Figure 6.1. Typical image error message</a></p>
<div class="figure"><a name="fig.errmsg-ex1"></a><p class="title"><b>Figure 6.1. Typical image error message</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/errmsg-ex1.png" alt="Typical image error message"></div>
</div></div><br class="figure-break">
<p>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 <a class="xref" href="ch06.html#fig.errmsg-header-sent" title='Figure 6.2. The "Header already sent error message"'>Figure 6.2. The "Header already sent error message"</a></p>
<div class="figure"><a name="fig.errmsg-header-sent"></a><p class="title"><b>Figure 6.2. The "Header already sent error message"</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/errmsg-headersent.png" alt='The "Header already sent error message"'></div>
</div></div><br class="figure-break">
<p>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! </p>
<div class="sect2" title="Catching errors in other parts of the system while creating images"><div class="titlepage"><div><div><h3 class="title"><a name="id2495400"></a>Catching errors in other parts of the system while creating images</h3></div></div></div>
<p>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
<code class="code">INSTALL_PHP_ERR_HANDLER</code> and <code class="code">CATCH_PHPERR</code> define in
<code class="filename">jpg-config.inc.php</code>
</p>
<p>
</p><div class="variablelist"><dl><dt><span class="term"><code class="code">INSTALL_PHP_ERR_HANDLER</code></span></dt><dd>
<p>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 <a class="xref" href="ch06.html#fig.errmsg-ex1" title="Figure 6.1. Typical image error message">Figure 6.1. Typical image error message</a>. </p>
<p>By default this is disabled.</p>
</dd><dt><span class="term"><code class="code">CATCH_PHPERR</code></span></dt><dd>
<p>This defines control whether the library shall check for any
generated error message that are stored in the global PHP
pre-defined variable <code class="code">php_errmsg</code>. 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.</p>
<p>By default this is enabled.</p>
</dd></dl></div><p>
</p>
</div>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="pt02.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>