Location: PHPKode > scripts > xError > xerror/readme.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<html>
<head>
	<title>xError Class - Version 0.1</title>
	<style type="text/css">
	/* Standard Elements */
	body { background-color:#e2e3fa; color:#394198; font-family:sans-serif; font-size:100%; margin:10px 10px 10px 10px; }
	a:link,a:active,a:visited,a:hover { text-decoration:underline; font-weight:bold; }
	a:link { color:#000080; }
	a:visited { color:#394198; }
	a:active,a:hover { color:#b22222; }
        h1 { font-family:sans-serif; font-size:130%; font-weight:bold; margin-top:0px; }
        td { font-family:sans-serif; font-size:75%; }
        hr { color:#394198; }


	/* Style Sheet Classes */
	.navHeader { background-color:#394198; color:#e2e3fa; font-weight:bold; text-align:left; padding:3px; font-size:120%; }

	/* Named Elements */
	#header { background-color:#394198; color:#e2e3fa; font-family:sans-serif; font-size:120%; font-weight:bold; padding:10px; height:80px; }
	#content { font-family:sans-serif; font-size:75%; border:1px solid #394198; margin:0px 0px 0px 0px; background-color:#c7cae9; }
	#innerContent { margin:5px 5px 5px 200px; background-color:#e2e3fa; padding:5px; }
	#rightNav { position:absolute; top:90px; left:10px; padding:5px; background-color:#e2e3fa; border:1px solid #394198; width:170px; font-size:75%; }
	#footer { background-color:#394198; color:#e2e3fa; padding:3px; font-size:75%; text-align:center; font-family:sans-serif; }

        #innerContent p { font-family:sans-serif; font-size:100%; text-align:left; }
        #innerContent p.code { font-family:'Courier New',monospace, font-size:100%; text-align:left; margin-left:30px; }
        </style>
</head>

<body>

<a name="top"></a>
<div id="header">
	xError 0.1
</div>

<div id="rightNav">
	<a href="readme.php#intro">Introduction</a><br />
        <a href="readme.php#overview">Overview</a><br />
        <a href="readme.php#inst">Installation</a><br />
        <a href="readme.php#usage">Usage</a><br />
        <a href="readme.php#vars">Variables</a><br />
        <a href="readme.php#list">Functions</a><br />
	<a href="readme.php#terms">Terms of Use</a><br /><br />
	<a href="./demo.php" target="_blank">Demo</a><br />
        <a href="./source.html" target="_blank">Source Code</a><br />
</div>

<div id="content">
	<div id="innerContent">
        	<a name="intro"></a>
		<h1>Introduction</h1>

		<p><b><i>&quot;The greatest of all faults, I should say, is to be conscious of none.&quot;</i></b><br />
                &nbsp;&nbsp;&nbsp;&nbsp;Thomas Carlyle, Scottish author, essayist &amp; historian (1795 - 1881)</p>

                <p>According to Mr Carlyle, everybody should be aware of the circumstance, that errors may occur anytime and anywhere. And for sure, as a software developer, you are painfully aware of this fact. The stranger it seems, that especially people related to software development (or at least most of them) are obviously trying to avoid this subject, wherever possible. And although I somehow understand this kind of demeanour, it has to be mentioned, that a proper and consistent handling of errors is essential to keeping you, your boss and/or your customer happy. Also, thinking about errors that may occur during the execution of a program, is helping to avoid those errors beforehand.</p>

                <p>My way of sneaking around this problem as smoothly as possible was to develop a generic PHP class that takes a great deal of the burden off of my shoulders by giving me a simple means of reporting and handling errors with as little effort as possible. And, after all, it was not that hard to write this class. And, measured by how much it eased my daily work (and still does), it was unquestionable worth the effort!</p>

		<div align="right"><a href="#top">[Back to Top]</a></div>

                <hr noshade size="1" />

                <a name="overview"></a>
                <h1>Overview</h1>

		<p>xError is a generic error reporting and handling class written in PHP. It may be used for debugging and/or monitoring purposes.</p>
		<p>The basic concept is to define as many errors as needed for the application. These errors may be declared as 'fatal' or 'non-fatal' errors.</p>
             	<p>Whenever an error is encountered during the execution of the program, xError checks whether it is classified as 'fatal' or 'non-fatal'.</p>
                <p>Fatal errors cause the immediate abortion of the program's execution. Instead of the output normally generated, an error message is displayed, describing the error that just occurred, accompanied by suggestions on how to avoid the error (if that is possible). Additionally, the error could be logged in a text file.</p>
                <p>Non-fatal errors do not cause the running program to be aborted. The error message is merely added to the so-called error stack. The developer is free to decide where and how he wants to react to these errors. For the sake of completeness, a means of displaying the non-fatal errors the same way, fatal errors are displayed, has been implemented.</p>

		<div align="right"><a href="#top">[Back to Top]</a></div>

                <hr noshade size="1" />

                <a name="inst"></a>
                <h1>Installation</h1>

		<p>Simply copy the class file 'class.xerror.php' and the templates for fatal and non-fatal errors 'fatal.html' and 'non-fatal.html' (the latter is only needed if you want to display non-fatal errors using the displayNonFatalError method) to any directory on your web server. That's all.</p>

		<div align="right"><a href="#top">[Back to Top]</a></div>

                <hr noshade size="1" />

                <a name="usage"></a>
                <h1>Usage</h1>

                <p>First, include the class file into your script, using either the include or require function of PHP. After that, instantiate a new object with the new operator.</p>
                <p><b>Example</b></p>
                <p class="code">include ( &quot;class.xerror.php&quot; );<br />
                $error = new xError();</p>
                <p>There are two ways of adding error definitions.</p>
                <ol>
                	<li>Add them one by one, using the setError method or</li>
                        <li>Load them from an external text file, using the importDefinitions method.</li>
                </ol>
                <p><b>Example</b></p>
                <p class="code"><b>Adding errors manually</b></p>
                <p class="code">$error-&gt;setError ( &quot;x100&quot;, &quot;[user message]&quot;, &quot;[admin message]&quot;, "nonfatal&quot;, &quot;[suggestions]&quot; );</p>
                <p class="code"><b>Loading errors from an external text file</b></p>
                <p class="code">$error-&gt;importDefinitions ( &quot;./definitions.txt&quot; );</p>
                <p>When you have defined all errors (or loaded them from the text file), you may start writing your script. Whenever you want an error to be raised you just pass it's error code to the raiseError method. This method checks if the error passed is fatal or non-fatal and reacts accordingly.</p>
                <p><b>Example</b></p>
                <p class="code">$error-&gt;raiseError ( &quot;x100&quot;, &quot;[additional information]&quot; );</p>
                <p>At the end of your script call the flushErrors method. This method empties the error stack and returnsit's contents in an array for further processing. To check if any (non-fatal) errors were encountered during the execution of the script, you just have to check if the array returned by flushErrors has any elements stored in it.</p>
                <p><b>Example</b></p>
                <p class="code">$errorArray = $error-&gt;flushErrors();</p>
		<p>That's it! Pretty simple, isn't it?</p>

		<div align="right"><a href="#top">[Back to Top]</a></div>

                <hr noshade size="1" />

                <a name="vars"></a>
                <h1>Variables</h1>

                <ul>
                	<li><i>array</i> <b>definitions</b> – Defined errors.</li>
                        <li><i>array</i> <b>errorStack</b> – Non-fatal errors that occurred during the execution of the script.</li>
                        <li><i>string</i> <b>errorLog</b> – The file used as error log.</li>
                        <li><i>boolean</i> <b>logFatalErrors</b> – Flag to determine whether fatal errors should be logged (true) or not (false).</li>
                	<li><i>string</i> <b>tmpFatal</b> – Template for fatal errors.</li>
                        <li><i>string</i> <b>tmpNonFatal</b> – Template for non-fatal errors.</li>
                </ul>

		<div align="right"><a href="#top">[Back to Top]</a></div>

                <hr noshade size="1" />

                <a name="list"></a>
                <h1>Function Reference</h1>

                <p><b>1. Public Functions</b></p>

                <ul>
                	<li><b>xError()</b> - Constructor</li>
                        <li><b>displayNonFatalError()</b> – Displays the contents of the error stack on the screen, using a HTML template.</li>
                	<li><b>flushErrors()</b> – Empties the error stack and returns it's contents in an array.</li>
                        <li><b>importDefinitions()</b> – Imports error definitions from a text file.</li>
                        <li><b>logFatalErrors()</b> – Determines whether fatal errors should be logged or not.</li>
                        <li><b>raiseError()</b> – Adds an error to the error stack (after checking if it is not fatal).</li>
                        <li><b>setError()</b> – Adds an error definition to the list of errors.</li>
                        <li><b>setLogFile()</b> – Sets the error log.</li>
                        <li><b>setTemplates()</b> – Sets the templates used to display fatal and non-fatal errors.</li>
                        <li><b>writeLog()</b> – Writes the contents of the error stack into the error log.</li>
                </ul>

                <p><b>2. Private Functions</b></p>

                <ul>
			<li><b>checkErrorCode()</b> – Checks if an error code is found in the list of error definitions.</li>
                        <li><b>displayFatalError()</b> – Displays a fatal error.</li>
                        <li><b>getError()</b> – Returns an error from the error stack.</li>
                        <li><b>getErrorDefinition()</b> – Returns an error definition from the list of defined errors.</li>
                </ul>

                <div align="right"><a href="#top">[Back to Top]</a></div>

                <hr noshade size="1" />

                <a name="terms"></a>
                <h1>Terms of Use</h1>

		<p>Copyright &copy; 2003 by Alexander Serbe. All rights reserved.</p>
                <p>This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.<br />
                This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.<br />
		You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.</p>
                <p>Dieses Programm ist freie Software. Sie können es unter den Bedingungen der GNU General Public License, wie von der Free Software Foundation veröffentlicht, weitergeben und/oder modifizieren, entweder gemäß Version 2 der Lizenz oder (nach Ihrer Option) jeder späteren Version.<br />
		Die Veröffentlichung dieses Programms erfolgt in der Hoffnung, daß es Ihnen von Nutzen sein wird, aber OHNE IRGENDEINE GARANTIE, sogar ohne die implizite Garantie der MARKTREIFE oder der VERWENDBARKEIT FÜR EINEN BESTIMMTEN ZWECK. Details finden Sie in der GNU General Public License.<br />
                Sie sollten eine Kopie der GNU General Public License zusammen mit diesem Programm erhalten haben. Falls nicht, schreiben Sie an die Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.</p>
                <p>Ce programme est libre, vous pouvez le redistribuer et/ou le modifier selon les termes de la Licence Publique Générale GNU publiée par la Free Software Foundation (version 2 ou bien toute autre version ultérieure choisie par vous).<br />
		Ce programme est distribué car potentiellement utile, mais SANS AUCUNE GARANTIE, ni explicite ni implicite, y compris les garanties de commercialisation ou d'adaptation dans un but spécifique. Reportez-vous à la Licence Publique Générale GNU pour plus de détails.<br />
		Vous devez avoir reçu une copie de la Licence Publique Générale GNU en même temps que ce programme ; si ce n'est pas le cas, écrivez à la Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, États-Unis.</p>

		<div align="right"><a href="#top">[Back to Top]</a></div>

                <hr noshade size="1" />
	</div>
</div>
<div id="footer">
	Copyright &copy; 2003 by Alexander Serbe. All rights reserved.
</div>


</body>
</html>
Return current item: xError