<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Using PHP Exceptions</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="ch06.html" title="Chapter 6. Error handling"></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">Using PHP Exceptions</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 6. Error handling</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Using PHP Exceptions"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2495627"></a>Using PHP Exceptions</h2></div></div></div>
<p>Starting with version v2.5 the library now have full support for PHP5 style
exceptions. The library provides an exception class named
<code class="code">JpGraphException</code> which is slightly different compared with
traditional exception classes in that this class can not only return an text string
as error but also an image. This is necessary in order to handle the case where a
script has an error and is called from within an <span class="markup"><img></span> tag. The
only data that can then be displayed in a browser is image data and hence it is
necessary for the error to be formatted as an image.</p>
<p>In addition to providing an exception class the library also installs its own
default exception handler to properly display an image. This default exception
handler will be automatically called whenever an "uncaught" exception would
otherwise be generated. This means that it is strictly not necessary to use
"<code class="code">try {} catch() {}</code>" blocks around the library scripts.</p>
<p>When an exception is generated the default exception handler first validates that
the exception is a proper descendant of <code class="code">JpGraphException</code> and if so,
generates the image by calling the <code class="code">JpgraphException::Stroke()</code> method.
If the exception is not a <code class="code">JpGraphException</code> based exception then the
handler re-raises the error. This means that in script that you create that is meant
to be called from within an <span class="markup"><img></span> tag all exception should be a
derivate of <code class="code">JpGraphException</code> in order to properly generate an error
image.</p>
<p>A typical example on how to raise an exception in your own code is shown in <a class="xref" href="ch06s03.html#ex.jpgraphexception1" title="Example 6.1. Throwing a JpGraph exception">Example 6.1. Throwing a JpGraph exception</a></p>
<p>
</p><div class="example"><a name="ex.jpgraphexception1"></a><p class="title"><b>Example 6.1. Throwing a JpGraph exception</b></p><div class="example-contents">
<div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags"><?php</span><span class="hl-code">
</span><span class="hl-reserved">throw</span><span class="hl-code"> </span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">JpGraphException</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string"> ... some error message ...</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?></span></pre></td></tr></table></div>
</div></div><p><br class="example-break">
</p>
<p>In case you need to handle the exception in a "<code class="code">try {} catch() {}</code>"
block (perhaps in order to do necessary cleanup) it is important to remember to call
the <code class="code">Stroke()</code> method which will create and stream the error message back
to the browser. An example of this is shown in <a class="xref" href="ch06s03.html#ex.jpgraphexception2" title="Example 6.2. Catching a JpGraph exception and sending it back as an image to the client">Example 6.2. Catching a JpGraph exception and sending it back as an image to the
client</a></p>
<p>
</p><div class="example"><a name="ex.jpgraphexception2"></a><p class="title"><b>Example 6.2. Catching a JpGraph exception and sending it back as an image to the
client</b></p><div class="example-contents">
<div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags"><?php</span><span class="hl-code">
</span><span class="hl-reserved">try</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-var">$graph</span><span class="hl-code"> = </span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">Graph</span><span class="hl-brackets">(</span><span class="hl-var">$width</span><span class="hl-code">,</span><span class="hl-var">$height</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-comment">//</span><span class="hl-comment"> ... Code to setup the graph</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-reserved">if</span><span class="hl-brackets">(</span><span class="hl-code"> </span><span class="hl-comment">/*</span><span class="hl-comment"> some error condition </span><span class="hl-comment">*/</span><span class="hl-code"> </span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-reserved">throw</span><span class="hl-code"> </span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">JpGraphException</span><span class="hl-brackets">(</span><span class="hl-quotes">'</span><span class="hl-string"> ... some error message ...</span><span class="hl-quotes">'</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-brackets">}</span><span class="hl-code">
</span><span class="hl-brackets">}</span><span class="hl-code"> </span><span class="hl-reserved">catch</span><span class="hl-code"> </span><span class="hl-brackets">(</span><span class="hl-code"> </span><span class="hl-identifier">JpGraphException</span><span class="hl-code"> </span><span class="hl-var">$e</span><span class="hl-code"> </span><span class="hl-brackets">)</span><span class="hl-code"> </span><span class="hl-brackets">{</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> .. do necessary cleanup</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> Send back error message</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$e</span><span class="hl-code">-></span><span class="hl-identifier">Stroke</span><span class="hl-brackets">(</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-brackets">}</span><span class="hl-code">
</span><span class="hl-inlinetags">?></span></pre></td></tr></table></div>
</div></div><p><br class="example-break">
</p>
<p>
</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
<p>Another typical augmentation of the exception handling might be to also
log an error to some logging server or plain log file. This should be done
before the call to <code class="code">Stroke()</code> since that call will never
return.</p>
</div><p>
</p>
<p>An example of real life error handling with exception is shown in listing <a class="xref" href="ch04s02.html#sec.preparing-sunspots-data" title="Preparing the data">Preparing the data</a> in the introductory example with Sun
spots.</p>
<div class="sect2" title="Selecting between text and image based error handling"><div class="titlepage"><div><div><h3 class="title"><a name="id2495896"></a>Selecting between text and image based error handling</h3></div></div></div>
<p>By default an exception that occurs in the library will create an error image
as shown in the previous section. However there might be circumstance where a
text based error handling is preferred (usually when graph are created from the
command line). </p>
<p>This could be accomplished in two ways. By catching the exception in the
script and handle it accordingly or we could slightly modify the default
behavior of the default exception handler in the library. How this is done will
now be described.</p>
<p>In order to enable a text based error handler we just need to disable the
image based error handler. This is done with a call to the method</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">JpGraphError::SetImageFlag($aFlag)</code></p>
</li></ul></div><p>
</p>
<p>Since the error handling have global scope this is a static function which can
be called as the following example shows</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">JpGraphError::SetImageFlag(false); // Enable text based error handling</span></pre></td></tr></table></div><p>
</p>
<p>Adding the line above to a graph script will cause any error to be printed to
<code class="code">STDERR</code> when the script is called from the command line. This is
a very convenient way to show errors when command line constructions like</p>
<p>
</p><pre class="screen">$> php mygraph.php > mygraph.png</pre><p>
</p>
<p>is used since writing the error to <code class="code">STDOUT</code> will cause the error
message to be sent back to the console since the call above only redirected
<code class="code">STDOUT</code> and not <code class="code">STDERR</code>. </p>
<p>When the script is called from PHP embedded in a HTTP server (e.g. Apache)
there is no concept of a <code class="code">STDERR</code> and the error message will just be
sent back as normal text to the browser.</p>
</div>
<div class="sect2" title="Writing error message to a log file (or system logger)"><div class="titlepage"><div><div><h3 class="title"><a name="id2495901"></a>Writing error message to a log file (or system logger)</h3></div></div></div>
<p>In addition to the option of having the error sent back as a string to the
client it can instead be written to a named log file. The log file name is
specified with a call to the (static) method</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">JpGraphError::SetLogFile($aFileName)</code></p>
</li></ul></div><p>
</p>
<p>The file needs to be writable by the PHP process. All error messages are
appended to the end of the file and each error message is prepended by the date
and time (in <code class="uri"><a class="uri" href="http://www.faqs.org/rfcs/rfc2822" target="_top">RFC 2822</a></code> formatted
date).</p>
<p>If the filename is given as the string <code class="code">'syslog'</code> then the error
message will be written to the default system logger instead. When a script is
run from, for example, Apache this is normally on Unix
'<code class="filename">/var/log/apache2/error_log</code>'</p>
</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="ch06.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>