<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>