Documentation is available at RSErrorManager.php
1 <?php
2 // RSErrorManager: A Pear Error Manager
3 // Copyright (C) 2003 Lukas Feiler
4 //
5 // This library is free software; you can redistribute it and/or
6 // modify it under the terms of the GNU Lesser General Public
7 // License as published by the Free Software Foundation; either
8 // version 2.1 of the License, or (at your option) any later version.
9 //
10 // This library is distributed in the hope that it will be useful,
11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 // Lesser General Public License for more details.
14 //
15 // You should have received a copy of the GNU Lesser General Public
16 // License along with this library; if not, write to the Free Software
17 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18
19 /**This file contains the class RSErrorManager.
20 *
21 * @package RSErrorManager
22 * @author Lukas Feiler <lukas.feiler@chello.at>
23 * @copyright Lukas Feiler 2003
24 * @filesource
25 */
26
27 /**RSErrorManager needs the error code definitions
28 * to catch certain types of errors.
29 */
30 require_once('RSErrorCodes.php');
31
32 /**Implementation of an Error Management System.
33 *
34 * Please see the docmentation for details.
35 *
36 * @author Lukas Feiler
37 * @copyright Lukas Feiler 2003
38 * @package RSErrorManager
39 * @version 0.1.9
40 */
41 class RSErrorManager {
42
43 /**The name of the current operation.
44 * @var String
45 * @access private
46 */
47 var $_currentOperation = 'undefined';
48
49 /**An array holding all errors that occurre - the error stack.
50 * @var Array
51 * @access private
52 */
53 var $_errors = array();
54
55 /**Constructor method.
56 *
57 * Calls reset to clear the error stack.
58 * @see reset
59 *
60 * @param String $newOperation The current operation - the default value for the property 'operation' of raised errors.
61 */
62 function RSErrorManager($newOperation = 'unspecified operation')
63 {
64 $this->reset($newOperation);
65 }
66
67 /**Saves the error passed as argument on the error stack.
68 *
69 * If the error does not define the property operation or if
70 * it is set to null the current operation is assigned to this property.
71 * @see getCurrentOperation
72 * @see RSError
73 *
74 * @param PEAR_Error $pearError An instance of the class PEAR_Error or a class that extends it (RSError for example).
75 */
76 function catch($pearError)
77 {
78 if (($pearError->operation == null) || (!isset($pearError->operation))) {
79 $pearError->operation = $this->getCurrentOperation();
80 }
81
82 //push error onto the stack
83 $this->_errors[] = $pearError;
84
85 if(
86 $pearError->getCode() == RSERROR_FATAL_ERROR ||
87 $pearError->getCode() == DB_ERROR_CONNECT_FAILED ||
88 $pearError->getCode() == DB_ERROR_NOSUCHDB ||
89 $pearError->getCode() == DB_ERROR_NODBSELECTED
90 ){
91 $this->onFatalError($pearError);
92 }
93
94 if ($pearError->getCode() == RSERROR_PERMISSION_DENIED) {
95 $this->onPermissionDenied($pearError);
96 }
97 if (get_class($pearError) == 'db_error') {
98 $this->onDBError($pearError);
99 }
100 }
101
102 /**Handle the occurence of DB errors.
103 *
104 * This method gets called by catch.
105 * @see catch
106 *
107 * @param DB_Error $dbError
108 */
109 function onDBError($dbError)
110 {
111
112 }
113
114 /**Handle the occurence of fatal errors.
115 *
116 * This method gets called by catch.
117 * @see catch
118 *
119 * @param PEAR_Error $pearError
120 */
121 function onFatalError($pearError)
122 {
123 $this->reportError($pearError);
124 die($pearError->getMessage());
125 }
126
127 /**Handle the occurence of permission-denied errors.
128 *
129 * This method gets called by catch.
130 * @see catch
131 *
132 * @param PEAR_Error $pearError
133 */
134 function onPermissionDenied($pearError)
135 {
136 $this->reportError($pearError);
137
138 die("PERMISSION DENIED: " . $pearError->getMessage());
139 }
140
141 /**Report the occurence of an error.
142 *
143 * This method is called by onFatalError and onPermissionDenied.
144 * If you want to do this method anything inherit from RSErrorManager
145 * and overwrite this method.
146 *
147 * @param PEAR_Error $pearError
148 */
149 function reportError($pearError)
150 {
151
152 }
153
154 /**Removes all errors from the error stack and sets a new default operation.
155 *
156 * @see _errors
157 * @see _currentOperation
158 *
159 * @param String $newOperation The name of the default operation.
160 */
161 function reset($newOperation)
162 {
163 $this->_errors = array();
164 $this->_currentOperation = $newOperation;
165 }
166
167
168
169 /**Returns an Array containing all errors from the error stack that match the specified conditions.
170 *
171 * If no conditions are specified all errors are returned from the stack.
172 * Conditions can be specified by passing an associative array with key-value-pairs.
173 * The following returns an array containing all errors that occurred on the object 't_user'
174 * and the property 'f_username' while performing the operation 'insert'.
175 * <code>
176 * $rsErrorManager->getErrors(array(
177 * 'object' => 't_users',
178 * 'property' => 'f_username',
179 * 'operation' => 'insert'
180 * )
181 * );
182 * </code>
183 *
184 * @param Array $conditions An associative array with key-value-pairs.
185 */
186 function getErrors($conditions = false)
187 {
188 $ret = array();
189 reset($this->_errors);
190 while (list($key,$error) = each($this->_errors)) {
191 if (is_array($conditions)) {
192 reset($conditions);
193 while (list($property,$value) = each($conditions)) {
194 if (!isset($error->$property) || $error->$property != $value) {
195 continue 2;
196 }
197 }
198 }
199 $ret[] = $error;
200 }
201 return $ret;
202 }
203
204 /**Returns the number of occurred errors that match the conditions passed as agrument.
205 *
206 * This method calls getErrors.
207 * Please see getErrors for writing conditions for fetching errors from the stack.
208 * @see getErrors
209 *
210 * @param mixed $conditions An associative array with key-value-pairs.
211 * If $conditions is false all errors are counted. This
212 * argument is optional. The default is false.
213 * @return int The number of errors on the stack matching the conditions.
214 */
215 function countErrors($conditions = false)
216 {
217 return count($this->getErrors($conditions));
218 }
219
220 /**Returns true if errors occurred that match the conditions passed as argument.
221 *
222 * Note that the error stack can be cleaned by calling the method reset.
223 * Please see getErrors for writing conditions for fetching errors from the stack.
224 * errorsOccurred calls countErrors.
225 * @see countErrors
226 * @see reset
227 *
228 * @param mixed $conditions An associative array with key-value-pairs.
229 * If $conditions is false this method returns true if any errors occured. This
230 * argument is optional. The default is false.
231 * @return boolean True if errors matching the conditions are found; otherwise false is returned.
232 */
233 function errorsOccurred($conditions = false)
234 {
235 return $this->countErrors($conditions) != 0;
236 }
237
238 /**Returns the number of occured errors that were related to the property passed as argument.
239 *
240 * This method calls countErrors.
241 * @see countErrors
242 *
243 * @param mixed $property Any value. It will be compared using ==.
244 * @return int The number of erros found.
245 */
246 function countErrorsByProperty($property)
247 {
248 return $this->countErrors(
249 array(
250 'property' => $property
251 )
252 );
253 }
254
255 /**Returns true if any errors occured on the property $property.
256 *
257 * This method calls countErrorsByProperty.
258 * @see countErrorsByProperty
259 *
260 * @param mixed $property This value will be used for comparison (==).
261 */
262 function errorsOccurredOnProperty($property)
263 {
264 return $this->countErrorsByProperty($property) != 0;
265 }
266
267
268 /**Returns the name of the current/default operation.
269 * @return String The name of the current operation.
270 */
271 function getCurrentOperation()
272 {
273 return $this->_currentOperation;
274 }
275
276 /**This method is a wrapper for PEAR::raiseError. It returns an instance of the class RSError.
277 *
278 * In comparison to PEAR::raiseError this method knows three additional parameters:
279 * $object, $propery and $operation to make it possibible to always tell where the error occured.
280 * You cannot pass the parameters $userinfo and $error_class known from PEAR::raiseError because the three additional
281 * parameters are stored in in $userinfo as an associative array and the $class_name is RSError.
282 * You would normally call this method just with the arguemnts $object, $property,
283 * $operation, $message and $code.
284 *
285 * @param String $object The name of the object to which the error is related.
286 * @param String $property The name of the property to which the error is related.
287 * @param String $operation The name of the operation to which the error is related.
288 * @param mixed $message A text error message or a PEAR error object.
289 * @param int $code A numeric error code.
290 * @param int $mode One of PEAR_ERROR_RETURN, PEAR_ERROR_PRINT, PEAR_ERROR_TRIGGER, PEAR_ERROR_DIE or PEAR_ERROR_CALLBACK.
291 * @param mixed $options If $mode is PEAR_ERROR_TRIGGER, this parameter
292 * specifies the PHP-internal error level (one of
293 * E_USER_NOTICE, E_USER_WARNING or E_USER_ERROR).
294 * If $mode is PEAR_ERROR_CALLBACK, this
295 * parameter specifies the callback function or
296 * method. In other error modes this parameter
297 * is ignored.
298 *
299 * @param bool $skipmsg If true, PEAR::raiseError will only pass error codes, the error message parameter will be dropped.
300 * @return RSError An instance of the class RSError.
301 * @see PEAR::raiseError
302 * @see RSError
303 */
304 function raiseRSError($object, $property, $operation, $message = null, $code = null, $mode = null, $options = null, $skipmsg = false)
305 {
306 //RSError is required on demand.
307 require_once('RSErrorManager/RSError.php');
308
309 $userinfo = array('object' => $object, 'property' => $property, 'operation' => $operation);
310 return PEAR::raiseError($message, $code, $mode, $options, $userinfo, 'RSError', $skipmsg);
311 }
312
313 /**Returns true if the passed object is an instance of RSError.
314 *
315 * @param mixed $error
316 * @return boolean True if the passed object is an instance of RSError, otherwise false.
317 */
318 function isRSError($error)
319 {
320 return (bool)(is_object($error) &&
321 (
322 get_class($error) == 'rserror' ||
323 is_subclass_of($error, 'rserror')
324 )
325 );
326 }
327 }
328 ?>
Documentation generated on Mon, 8 Dec 2003 13:13:06 +0100 by phpDocumentor 1.2.3