Source for file Error.class.php

Documentation is available at Error.class.php

  1. <?php
  2. /**
  3.  * Gumbo Library Framework
  4.  *
  5.  * LICENSE
  6.  * This library is being released under the terms of the New BSD License.  A
  7.  * copy of the license is packaged with the software (LICENSE.txt).  If no
  8.  * copy is found, a copy of the license template can be found at:
  9.  * http://www.opensource.org/licenses/bsd-license.php
  10.  * 
  11.  * @category Gumbo
  12.  * @package Error
  13.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  14.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  15.  * @author Michael Luster <mluster79@yahoo.com>
  16.  * @link http://sourceforge.net/projects/phpgumbo
  17.  * @version 0.0.1
  18.  */
  19.  
  20. /**
  21.  * Error Class
  22.  *
  23.  * @category Gumbo
  24.  * @package Error
  25.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  26.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  27.  * @author Michael Luster <mluster79@yahoo.com>
  28.  * @link http://sourceforge.net/projects/phpgumbo
  29.  * @desc Error Class
  30.  * @version 0.0.1
  31.  */
  32.  
  33. gumbo_load ("Interface_Error");
  34. gumbo_load ("Interface_Singleton");
  35. gumbo_load ("Interface_Observerable");
  36.  
  37. class Gumbo_Error implements Gumbo_Interface_Error, Gumbo_Interface_Singleton, IteratorAggregate, Gumbo_Interface_Observerable {
  38.     
  39.     /** @var int OK no errors found */
  40.     const OK = 0;
  41.     /** @var int DEBUG debug error found */
  42.     const DEBUG = 1;
  43.     /** @var int NOTICE user notice found */
  44.     const NOTICE = 2;
  45.     /** @var int WARNING user warning found */
  46.     const WARNING = 4;
  47.     /** @var int ERROR user error found */
  48.     const ERROR = 8;
  49.     /** @var int CRITICAL critical error found */
  50.     const CRITICAL = 16;
  51.     /** @var int ALERT alert error found */
  52.     const ALERT = 32;
  53.     /** @var int EMERGENCY emergency error found */
  54.     const EMERGENCY = 64;
  55.     /** @var int ALL all error levels */
  56.     const ALL = 127;
  57.     
  58.     /** @var Gumbo_Interface_Singleton $_instance */
  59.     private static $_instance = null;
  60.     
  61.     /** @var array $_observers list of Observer objects */
  62.     private $_observers = array ();
  63.     
  64.     /** @var int $_level error levels commited during the program execution */
  65.     private $_level = Gumbo_Error::OK;
  66.     /** @var array $_errors list of Exceptions added to the object */
  67.     private $_errors = array ();
  68.     /** @var bool $_exists if any errors exists */
  69.     private $_exists = false;
  70.     
  71.     /** @var int $_report_level the minimum level on errors to report */
  72.     private $_report_level = Gumbo_Error::NOTICE;
  73.     /** @var int $_ignore_level disregards any errors at or below this level */
  74.     private $_ignore_level = Gumbo_Error::DEBUG;
  75.     
  76.     
  77.     
  78.     /**
  79.      * Constructor
  80.      */
  81.     private function __construct () {}
  82.     
  83.     /**
  84.      * Singleton Method
  85.      * @return Gumbo_Interface_Error 
  86.      */
  87.     public static function instance () {
  88.         if (self::$_instance == null) {
  89.             self::$_instance = new Gumbo_Error ();
  90.         }
  91.         return self::$_instance;
  92.     }
  93.     
  94.     
  95.     
  96.     /** ACTION METHODS **/
  97.     /**
  98.      * Attaches an Error_Observer to the object
  99.      * @param Gumbo_Interface_Observer $obj 
  100.      * @return int current error level
  101.      */
  102.     public function attach (Gumbo_Interface_Observer $obj) {
  103.         // check if object was previously loaded
  104.         $found = false;
  105.         foreach ($this->_observers as $key=>$val) {
  106.             if ($val === $obj) {
  107.                 $found = true;
  108.                 break;
  109.             }
  110.         }
  111.         
  112.         // add the Error_Observer
  113.         if (!$found) {
  114.             $this->_observers [] = $obj;
  115.         }
  116.         
  117.         // return the current error level
  118.         return $this->level ();
  119.     }
  120.     
  121.     /**
  122.      * Detach an Error_Observer from the object
  123.      * @param Gumbo_Interface_Observer $obj 
  124.      * @return void 
  125.      */
  126.     public function detach (Gumbo_Interface_Observer $obj) {
  127.         foreach ($this->_observers as $key=>$val) {
  128.             if ($val === $obj) { unset ($this->_observers [$key]); }
  129.         }
  130.     }
  131.     
  132.     /**
  133.      * Notifies the Error_Observers about changes to the system
  134.      */
  135.     public function notify () {
  136.         foreach ($this->_observers as $val) {
  137.             $val->update (array ("error_level", $this->level ()));
  138.         }
  139.     }
  140.     
  141.     /**
  142.      * Adds an Exception to the list
  143.      * @param Exception $e 
  144.      */
  145.     public function add (Exception $e) {
  146.         // check the Error Code
  147.         $code = Gumbo_Error::ERROR;
  148.         if ($e instanceof Gumbo_Exception) {
  149.             $code = $e->getCode ();
  150.         }
  151.         
  152.         // check if Exception should be ignore
  153.         if ($code <= $this->getIgnoreLevel ()) {
  154.             return;
  155.         }
  156.         
  157.         // check error level
  158.         if (!($this->level () & $code)) {
  159.             $this->_level += $code;
  160.         }
  161.         
  162.         // add the Exception
  163.         $this->_errors [] = $e;
  164.         $this->_exists = true;
  165.         
  166.         // notify observers
  167.         $this->notify ();
  168.     }
  169.     
  170.     /**
  171.      * Clears all the errors from the system
  172.      * @postcondition level() = Gumbo_Error::OK
  173.      * @postcondition exceptions thrown are cleared
  174.      * @param int $level level to clear
  175.      */
  176.     public function clear ($level=null) {
  177.         if ($this->_validLevel ($level)) {
  178.             foreach ($this->getAll ($level, true) as $key=>$e) {
  179.                 unset ($this->_errors [$key]);
  180.             }
  181.             
  182.             // remove the level from the current error level
  183.             if ($this->level () & $level) {
  184.                 $this->_level -= $level;
  185.             }
  186.         } else {
  187.             $this->_level = Gumbo_Error::OK;
  188.             $this->_errors = array ();
  189.         }
  190.         
  191.         if ($this->count () <= 0) {
  192.             $this->_exists = false;
  193.         }
  194.         
  195.         // notify observers
  196.         $this->notify ();
  197.     }
  198.     
  199.     
  200.     
  201.     /** MUTATOR METHODS **/
  202.     /**
  203.      * Sets the minimum error reporting level
  204.      * A value of 0 reports ALL errors
  205.      * @param int $level 
  206.      */
  207.     public function setReportLevel ($level) {
  208.         // verify precondition
  209.         if (!$this->_validLevel ($level)) { return; }
  210.         $this->_report_level = $level;
  211.     }
  212.     
  213.     /**
  214.      * Sets the ignore level, which disregards any errors at or below this level
  215.      * @param int $level 
  216.      */
  217.     public function setIgnoreLevel ($level) {
  218.         // verify precondition
  219.         if (!$this->_validLevel ($level)) { return; }
  220.         $this->_ignore_level = $level;
  221.     }
  222.     
  223.     
  224.     
  225.     /** ACCESSOR METHODS **/
  226.     /**
  227.      * Returns all Errors
  228.      * @param int $level limit to supplied level and above
  229.      * @param bool $only limits to only errors at the supplied level
  230.      * @return Exception[] 
  231.      */
  232.     public function getAll ($level=null, $only=false) {
  233.         // verify precondition
  234.         if (!is_null ($level) && !$this->_validLevel ($level)) { $level = null; }
  235.         if (!is_bool ($only)) { $only = false; }
  236.         
  237.         // return limited errors
  238.         if ($this->_validLevel ($level)) {
  239.             $errs = array ();
  240.             foreach ($this->_errors as $e) {
  241.                 // check for non Gumbo_Exception classes
  242.                 $code = Gumbo_Error::ERROR;
  243.                 if ($e instanceof Gumbo_Exception) {
  244.                     $code = $e->getCode ();
  245.                 }
  246.                 
  247.                 // add to the list
  248.                 if ($only) {
  249.                     if ($code == $level) {
  250.                         $errs [] = $e;
  251.                     }
  252.                 } else {
  253.                     if ($code >= $level) {
  254.                         $errs [] = $e;
  255.                     }
  256.                 }
  257.             }
  258.             return $errs;
  259.         }
  260.         
  261.         // return all errors
  262.         return $this->_errors;
  263.     }
  264.     
  265.     /**
  266.      * Returns if any Errors exist
  267.      * @param int $level if errors of this level exist
  268.      * @return bool 
  269.      */
  270.     public function exists ($level=null) {
  271.         // return if only errors of given level exists
  272.         if ($this->_validLevel ($level)) {
  273.             $test = false;
  274.             foreach ($this->_errors as $e) {
  275.                 // set the right Error Level
  276.                 $code = Gumbo_Error::ERROR;
  277.                 if ($e instanceof Gumbo_Exception) {
  278.                     $code = $e->getCode ();
  279.                 }
  280.                 
  281.                 if ($code == $level) {
  282.                     $test = true;
  283.                     break;
  284.                 }
  285.             }
  286.             return $test;
  287.         }
  288.         
  289.         // return if any errors exist
  290.         return $this->_exists;
  291.     }
  292.     
  293.     /**
  294.      * Returns the current error level value
  295.      * 
  296.      * The Error level will be a binary representation of the
  297.      * available error level constants.  This will allow the system
  298.      * to determine the level of errors triggered during program
  299.      * execution.
  300.      * 
  301.      * @return int 
  302.      */
  303.     public function level () {
  304.         return $this->_level;
  305.     }
  306.     
  307.     /**
  308.      * Returns the number of errors
  309.      * @param int $level number of errors at level
  310.      * @return int 
  311.      */
  312.     public function count ($level=null) {
  313.         // returning number of specific level of errors
  314.         if ($this->_validLevel ($level)) {
  315.             $num = 0;
  316.             foreach ($this->_errors as $e) {
  317.                 // set proper Error Level of Exception
  318.                 $code = Gumbo_Error::ERROR;
  319.                 if ($e instanceof Gumbo_Exception) {
  320.                     $code = $e->getCode ();
  321.                 }
  322.                 
  323.                 if ($code == $level) {
  324.                     $num++;
  325.                 }
  326.             }
  327.             return $num;
  328.         }
  329.         
  330.         // return total count
  331.         return count ($this->_errors);
  332.     }
  333.     
  334.     /**
  335.      * Returns the minimum reporting level
  336.      * @return int 
  337.      */
  338.     public function getReportLevel () {
  339.         return $this->_report_level;
  340.     }
  341.     
  342.     /**
  343.      * Returns the minimum ignore level
  344.      * @return int 
  345.      */
  346.     public function getIgnoreLevel () {
  347.         return $this->_ignore_level;
  348.     }
  349.     
  350.     /**
  351.      * Returns an Iterator object
  352.      * @return Iterator 
  353.      * @uses Gumbo_Iterator
  354.      */
  355.     public function getIterator () {
  356.         gumbo_load ("Iterator");
  357.         $errors = array ();
  358.         foreach ($this->_errors as $e) {
  359.             // set proper Error Level on Exception
  360.             $code = Gumbo_Error::ERROR;
  361.             if ($e instanceof Gumbo_Exception) {
  362.                 $code = $e->getCode ();
  363.             }
  364.             
  365.             if ($code >= $this->getReportLevel ()) {
  366.                 $errors [] = $e;
  367.             }
  368.         }
  369.         return new Gumbo_Iterator ($errors);
  370.     }
  371.     
  372.     
  373.     
  374.     /**
  375.      * Returns if the given integer is a valid error level
  376.      * @param int $level 
  377.      * @return bool 
  378.      */
  379.     private function _validLevel ($level) {
  380.         // verify precondition
  381.         if (!is_numeric ($level)) { return false; }
  382.         $level = (int) $level;
  383.         
  384.         switch ($level) {
  385.             case Gumbo_Error::OK : break;
  386.             case Gumbo_Error::DEBUG : break;
  387.             case Gumbo_Error::NOTICE : break;
  388.             case Gumbo_Error::WARNING : break;
  389.             case Gumbo_Error::ERROR : break;
  390.             case Gumbo_Error::CRITICAL : break;
  391.             case Gumbo_Error::ALERT : break;
  392.             case Gumbo_Error::EMERGENCY : break;
  393.             case Gumbo_Error::ALL : break;
  394.             default : return false;
  395.         }
  396.         
  397.         return true;
  398.     }
  399.     
  400. }
  401.  
  402. define ("ERROR_OK", Gumbo_Error::OK);
  403. define ("ERROR_DEBUG", Gumbo_Error::DEBUG);
  404. define ("ERROR_NOTICE", Gumbo_Error::NOTICE);
  405. define ("ERROR_WARNING", Gumbo_Error::WARNING);
  406. define ("ERROR_ERROR", Gumbo_Error::ERROR);
  407. define ("ERROR_CRITICAL", Gumbo_Error::CRITICAL);
  408. define ("ERROR_ALERT", Gumbo_Error::ALERT);
  409. define ("ERROR_EMERGENCY", Gumbo_Error::EMERGENCY);
  410.  
  411. ?>