Source for file Exception.class.php

Documentation is available at Exception.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.  * Exception Class
  22.  * 
  23.  * A Gumbo Exception is an extension to the PHP5 Exception class.  The extra
  24.  * methods defined allows the programmer to provide special information to
  25.  * the Exception.  All Exceptions are defaulted to the ERROR_DEBUG level.  This
  26.  * can be defined by the 'code' argument.
  27.  * 
  28.  * The function setting will accept a function name or a class method.  This
  29.  * should be set using either __FUNCTION__ or __METHOD__.  This element does not
  30.  * need to be set, but useful if thrown inside a function or method.
  31.  * 
  32.  * The Exception contains static methods that are involved with the __toString
  33.  * method.  The values determine which pieces are displayed.  The __toString
  34.  * method provides an HTML formatted message, with class and id attributes to
  35.  * format the message.
  36.  * 
  37.  * Exceptions should be thrown using try...catch blocks.  Once thrown, the file
  38.  * and line number will automatically be set.
  39.  * <pre>
  40.  * try {
  41.  *         // test conditions
  42.  *         if (failed) {
  43.  *             throw new Gumbo_Exception ("<error message>");
  44.  *         }
  45.  *         ...
  46.  * } catch (Gumbo_Exception $e) {
  47.  *         $e->setFunction (__METHOD__);
  48.  *         gumbo_trigger ($e);
  49.  * }
  50.  * </pre>
  51.  * 
  52.  * Exceptions could be created by creating a new Exception object directly.  The
  53.  * file and line number may not be set, but the Exception object will still contain
  54.  * a message.
  55.  * <pre>
  56.  * $e = new Gumbo_Exception ("<error message>", ERROR_LEVEL, __FILE__, __LINE__, __METHOD__);
  57.  * </pre>
  58.  *
  59.  * @category Gumbo
  60.  * @package Error
  61.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  62.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  63.  * @author Michael Luster <mluster79@yahoo.com>
  64.  * @link http://sourceforge.net/projects/phpgumbo
  65.  * @desc Exception Class
  66.  * @version 0.0.1
  67.  */
  68.  
  69. gumbo_load ("Interface_Exception");
  70.  
  71. class Gumbo_Exception extends Exception implements Gumbo_Interface_Exception {
  72.     
  73.     /** @var string $_function class method file name */
  74.     private $_function;
  75.     
  76.     /** @var bool $_display_title displays the Error title bar */
  77.     private static $_display_title = true;
  78.     /** @var bool $_display_function displays the function in the error message */
  79.     private static $_display_function = true;
  80.     /** @var bool $_display_file displays the file in the error message */
  81.     private static $_display_file = true;
  82.     /** @var bool $_display_trace displays the error trace in message */
  83.     private static $_display_trace = true;
  84.     
  85.     
  86.     
  87.     /**
  88.      * Constructor
  89.      * @param string $mess Error message
  90.      * @param int $code Error level code
  91.      * @param string $file file name
  92.      * @param int $line line number
  93.      * @param string $func function/method name
  94.      */
  95.     public function __construct ($mess, $code=0, $file=null, $line=0, $func=null) {
  96.         // verify precondition
  97.         if (!is_string ($mess)) { $mess = null; }
  98.         if (!is_int ($code)) { $code = ERROR_DEBUG; }
  99.         if ($code <= 0) { $code = ERROR_DEBUG; }
  100.         
  101.         parent::__construct ($mess, $code);
  102.         
  103.         $this->setFile ($file);
  104.         $this->setLine ($line);
  105.         $this->setFunction ($func);
  106.     }
  107.     
  108.     
  109.     
  110.     /** ACTION METHODS **/
  111.     /**
  112.      * Displays the error title
  113.      * @param bool $val 
  114.      */
  115.     public static function displayTitle ($val) {
  116.         // verify precondition
  117.         if (!is_bool ($val)) { return; }
  118.         Gumbo_Exception::$_display_title = $val;
  119.     }
  120.     
  121.     /**
  122.      * Displays the function information
  123.      * @param bool $val 
  124.      */
  125.     public static function displayFile ($val) {
  126.         // verify precondition
  127.         if (!is_bool ($val)) { return; }
  128.         Gumbo_Exception::$_display_function = $val;
  129.     }
  130.     
  131.     /**
  132.      * Displays the file information
  133.      * @param bool $val 
  134.      */
  135.     public static function displayFunction ($val) {
  136.         // verify precondition
  137.         if (!is_bool ($val)) { return; }
  138.         Gumbo_Exception::$_display_file = $val;
  139.     }
  140.     
  141.     /**
  142.      * Displays the error trace information
  143.      * @param bool $val 
  144.      */
  145.     public static function displayTrace ($val) {
  146.         // verify precondition
  147.         if (!is_bool ($val)) { return; }
  148.         Gumbo_Exception::$_display_trace = $val;
  149.     }
  150.     
  151.     
  152.     
  153.     /** MUTATOR METHODS **/
  154.     /**
  155.      * Sets the Message text
  156.      * @param string $mess 
  157.      */
  158.     public function setMessage ($mess) {
  159.         // verify precondition
  160.         if (!is_string ($mess)) { return; }
  161.         $this->message = $mess;
  162.     }
  163.     
  164.     /**
  165.      * Sets the error level code
  166.      * @param int $code 
  167.      */
  168.     public function setCode ($code) {
  169.         // verify precondition
  170.         if (!is_int ($code)) { return; }
  171.         if ($code <= 0) { return; }
  172.         $this->code = $code;
  173.     }
  174.     
  175.     /**
  176.      * Sets the file name where error occured
  177.      * @param string $file 
  178.      */
  179.     public function setFile ($file) {
  180.         // verify precondition
  181.         if (!is_string ($file)) { return; }
  182.         $this->file = $file;
  183.     }
  184.     
  185.     /**
  186.      * Sets the line number where error occured
  187.      * @param int $line 
  188.      */
  189.     public function setLine ($line) {
  190.         // verify precondition
  191.         if (!is_int ($line)) { return; }
  192.         if ($line <= 0) { return; }
  193.         $this->line = $line;
  194.     }
  195.     
  196.     /**
  197.      * Sets the function or class method
  198.      * @param string $func function/method name
  199.      */
  200.     public function setFunction ($func) {
  201.         // verify precondition
  202.         if (!is_string ($func)) { return; }
  203.         $this->_function = $func;
  204.     }
  205.     
  206.     
  207.     
  208.     /** ACCESSOR METHOD **/
  209.     /**
  210.      * Returns the function / class method name
  211.      * @return string 
  212.      */
  213.     public function getFunction () {
  214.         return $this->_function;
  215.     }
  216.     
  217.     
  218.     
  219.     /**
  220.      * Returns the Object in string format
  221.      * 
  222.      * The following CSS style rules apply to an Error message
  223.      * - div.error
  224.      * - div.error h3 :: Error Title
  225.      * - div.error p :: Error Message
  226.      * - div.error p.details :: Error Class::Function and File Name
  227.      * - div.error ul :: Error Trace details
  228.      * - div.error ul li :: Trace Line Item
  229.      * - - *.file :: file name
  230.      * - - *.line :: file line number
  231.      * - - *.cls :: class name
  232.      * - - *.function :: function/method name
  233.      * - - *.typeArray :: parameter type Array
  234.      * - - *.typeClass :: parameter type Class
  235.      * - - *.typeNull :: parameter type null
  236.      * - - *.typeResource :: parameter type Resource
  237.      * - - *.typeBoolean :: parameter type Boolean
  238.      * - - *.typeNumber :: parameter type numeric
  239.      * - - *.typeString :: parameter type String
  240.      * 
  241.      * @return string 
  242.      */
  243.     public function __toString () {
  244.         $color = "standard";
  245.         switch ($this->getCode ()) {
  246.             case ERROR_DEBUG : $level = "debug"; break;
  247.             case ERROR_NOTICE : $level = "notice"; break;
  248.             case ERROR_WARNING : $level = "warning"; break;
  249.             case ERROR_ERROR : $level = "error"; $color = "urgent"; break;
  250.             case ERROR_CRITICAL : $level = "critical"; $color = "urgent"; break;
  251.             case ERROR_ALERT : $level = "alert"; $color = "urgent"; break;
  252.             case ERROR_EMERGENCY : $level = "emergency"; $color = "urgent"; break;
  253.             default : $level = "unknown";
  254.         }
  255.         
  256.         $txt = "<div class=\"error\">\n";
  257.             if (Gumbo_Exception::$_display_title) {
  258.                 $txt .= "\t<h3 class=\"" . $color . "\">" . ucwords ($level) . "</h3>\n";
  259.             }
  260.             $txt .= "\t<p>" . $this->getMessage () . "</p>\n";
  261.             
  262.             if (Gumbo_Exception::$_display_function || Gumbo_Exception::$_display_file) {
  263.                 $txt .= "\t<p class=\"details\">";
  264.                     
  265.                     if (Gumbo_Exception::$_display_function) {
  266.                         if ($this->getFunction ()) { 
  267.                             $txt .= "<code>" . $this->getFunction () . " ()</code><br />";
  268.                         }
  269.                     }
  270.                     
  271.                     if (Gumbo_Exception::$_display_file) {
  272.                         $txt .= $this->getFile () . " [" . $this->getLine () . "]";
  273.                     }
  274.                 
  275.                 $txt .= "</p>\n";
  276.             }
  277.         
  278.         // retrieving Trace information
  279.         if (Gumbo_Exception::$_display_trace) {
  280.             $trace = $this->getTrace ();
  281.             $num = count ($trace);
  282.             if ($num > 0) {
  283.                 $txt .= "\t<ul>";
  284.                 for ($x = $num;$x >= 0;$x--) {
  285.                     if (count ($trace [$x]) == 0) { continue; }
  286.                     
  287.                     $txt .= "\t\t<li>";
  288.                     $txt .= "<em class=\"file\">" . $trace [$x]['file'] . "</em> [<em class=\"line\">" . $trace [$x]['line'] . "</em>] ";
  289.                     
  290.                     if ($trace [$x]['function']) { $txt .= "--- "; }
  291.                     if ($trace [$x]['class']) { $txt .= "<em class=\"cls\">" . $trace [$x]['class'] . "</em>" . $trace [$x]['type']; }
  292.                     if ($trace [$x]['function']) {
  293.                         $txt .= "<em class=\"function\">" . $trace [$x]['function'] . "</em> ( ";
  294.                         
  295.                         $tmp = false;
  296.                         $num = count ($trace [$x]['args']);
  297.                         foreach ($trace [$x]['args'] as $key=>$val) {
  298.                             if (is_array ($val)) {
  299.                                 $tmp .= "<em class=\"typeArray\">Array</em>";
  300.                             } elseif (is_object ($val)) {
  301.                                 $tmp .= "<em class=\"typeClass\">" . get_class ($val) . "</em>";
  302.                             } elseif (is_null ($val)) {
  303.                                 $tmp .= "<em class=\"typeNull\">null</em>";
  304.                             } elseif (is_resource ($val)) {
  305.                                 $tmp .= "<em class=\"typeResource\">Resource</em>";
  306.                             } elseif (is_bool ($val)) {
  307.                                 $tmp .= "<em class=\"typeBoolean\">";
  308.                                 if ($val == true) {
  309.                                     $tmp .= "TRUE";
  310.                                 } else {
  311.                                     $tmp .= "FALSE";
  312.                                 }
  313.                                 $tmp .= "</em>";
  314.                             } elseif (is_numeric ($val)) {
  315.                                 $tmp .= "<em class=\"typeNumber\"" . $val . "</em>";
  316.                             } else {
  317.                                 $tmp .= "<em class=\"typeString\">\"" . $val . "\"</em>";
  318.                             }
  319.                             
  320.                             $tmp .= ", ";
  321.                         }
  322.                         $tmp = substr ($tmp, 0, strlen ($tmp) - 2);
  323.                         
  324.                         $txt .= $tmp . " )";
  325.                     }
  326.                     $txt .= "</li>\n";
  327.                 }
  328.                 $txt .= "\t</ul>\n";
  329.             }
  330.         }
  331.         
  332.         $txt .= "</div>\n\n";
  333.         
  334.         return $txt;
  335.     }
  336.     
  337. }
  338.  
  339. ?>