Source for file Debug.class.php

Documentation is available at Debug.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 Debug
  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.  * Debug Class
  22.  *
  23.  * @category Gumbo
  24.  * @package Debug
  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 Debug Class
  30.  * @version 0.0.1
  31.  */
  32.  
  33. gumbo_load ("Interface_Debug");
  34. gumbo_load ("Debug_Message");
  35. gumbo_load ("Iterator");
  36.  
  37. class Gumbo_Debug implements Gumbo_Interface_Debug, Gumbo_Interface_Singleton, IteratorAggregate {
  38.     
  39.     /** @var Gumbo_Interface_Singleton $_instance */
  40.     private static $_instance = null;
  41.     
  42.     /** @var bool $_active if Debug mode is active */
  43.     private $_active = false;
  44.     /** @var array $_list list of Debug Messages */
  45.     private $_list = array ();
  46.     
  47.     /** @var num $_time start time of the program */
  48.     private $_time;
  49.     
  50.     /** @var bool $_inclusive the list of elements are inclusive if true, exclusive if false */
  51.     private $_inclusive = true;
  52.     /** @var array $_functions list of functions to allow/deny */
  53.     private $_functions = array ();
  54.     /** @var array $_classes list of classes to include */
  55.     private $_classes = array ();
  56.     /** @var array $_files list of files to include */
  57.     private $_files = array ();
  58.     
  59.     
  60.     
  61.     /**
  62.      * Constructor, for Singleton Pattern
  63.      */
  64.     private function __construct () {
  65.         $this->_setTime (microtime (true));
  66.     }
  67.     
  68.     /**
  69.      * Singleton Pattern Method
  70.      * @return Gumbo_Interface_Debug 
  71.      */
  72.     public static function instance () {
  73.         if (self::$_instance == null) {
  74.             self::$_instance = new Gumbo_Debug ();
  75.         }
  76.         return self::$_instance;
  77.     }
  78.     
  79.     
  80.     
  81.     /** ACTION METHODS **/
  82.     /**
  83.      * Creates a message and adds it to the Debugger
  84.      * @param string $mess message content
  85.      * @param string $file file name
  86.      * @param int $line line number
  87.      * @param string $func function/method name
  88.      * @param string $cls class name
  89.      */
  90.     public function add ($mess, $file, $line, $func=null, $cls=null) {
  91.         if (!$this->isActive ()) { return; }
  92.         
  93.         $restricted = false;
  94.         if ($this->isRestrictedClass ($cls)) { $restricted = true; }
  95.         if ($this->isRestrictedFunction ($func, $cls)) { $restricted = true; }
  96.         if ($this->isRestrictedFile (strtolower ($file), $line)) { $restricted = true; }
  97.         
  98.         if (($this->isInclusive () && $restricted) || (!$this->isInclusive () && !$restricted)) {
  99.             $this->_messages [] = new Gumbo_Debug_Message ($mess, $file, $line, $func, $cls);
  100.         }
  101.     }
  102.     
  103.     /**
  104.      * Adds a function to the restriction list
  105.      * @precondition function_exists ($func) or method_exists ($cls, $func)
  106.      * @precondition !isRestrictedFunction ($func, $cls)
  107.      * @param string $func function name
  108.      * @param string $cls class name
  109.      * @throws Gumbo_Exception
  110.      */
  111.     public function addRestrictedFunction ($func, $cls=null) {
  112.         try {
  113.             // verify precondition
  114.             if (!is_string ($func)) {
  115.                 throw new Gumbo_Exception ("Invalid Argument 'func:str' => {$func}:" . gettype ($func));
  116.             }
  117.             if (!is_null ($cls) && !is_string ($cls)) {
  118.                 throw new Gumbo_Exception ("Invalid Argument 'cls:str' => {$cls}:" . gettype ($cls));
  119.             }
  120.             if (is_null ($cls) && !function_exists ($func)) {
  121.                 throw new Gumbo_Exception ("Function Does Not Exist: {$func}");
  122.             }
  123.             if (!is_null ($cls) && !method_exists ($cls, $func)) {
  124.                 throw new Gumbo_Exception ("Class Method Not Found: {$func}::{$cls}");
  125.             }
  126.             if ($this->isRestrictedFunction ($func, $cls)) {
  127.                 throw new Gumbo_Exception ("Function|Method Restricted: {$cls}::{$func}");
  128.             }
  129.             
  130.             if (!is_null ($cls)) { $func .= "." . $cls; }
  131.             $this->_functions [] = $func;
  132.         } catch (Gumbo_Exception $e) {
  133.             $e->setFunction (__METHOD__);
  134.             gumbo_trigger ($e);
  135.         }
  136.     }
  137.     
  138.     /**
  139.      * Adds a class to the restriction list
  140.      * @precondition is_class ($cls)
  141.      * @precondition !isRestrictedClass ($cls)
  142.      * @param string $cls class name
  143.      * @throws Gumbo_Exception
  144.      */
  145.     public function addRestrictedClass ($cls) {
  146.         try {
  147.             // verify precondition
  148.             if (!is_string ($cls)) {
  149.                 throw new Gumbo_Exception ("Invalid Argument 'cls:str' => {$cls}:" . gettype ($cls));
  150.             }
  151.             if (!class_exists ($cls, false)) {
  152.                 throw new Gumbo_Exception ("Class|Interface Does Not Exist: {$cls}");
  153.             }
  154.             if ($this->isRestrictedClass ($cls)) {
  155.                 throw new Gumbo_Exception ("Class Restricted: {$cls}");
  156.             }
  157.             
  158.             $this->_classes [] = $cls;
  159.         } catch (Gumbo_Exception $e) {
  160.             $e->setFunction (__METHOD__);
  161.             gumbo_trigger ($e);
  162.         }
  163.     }
  164.     
  165.     /**
  166.      * Adds a file to the restriction list
  167.      * @precondition file_exists ($file)
  168.      * @precondition $start < $end
  169.      * @precondition !isRestrictedFile ($file, $start, $end)
  170.      * @param string $file file name
  171.      * @param int $start start line
  172.      * @param int $end end line
  173.      * @throws Gumbo_Exception
  174.      */
  175.     public function addRestrictedFile ($file, $start=null, $end=null) {
  176.         try {
  177.             // verify precondition
  178.             if (!is_string ($file)) {
  179.                 throw new Gumbo_Exception ("Invalid Argument 'file:str' => {$file}:" . gettype ($file));
  180.             }
  181.             if (!is_numeric ($start)) { $start = 0; }
  182.             if (!is_numeric ($end)) { $end = 0; }
  183.             if (!is_file ($file)) {
  184.                 throw new Gumbo_Exception ("File Not Found: {$file}");
  185.             }
  186.             if ($start < 0) { $start = 0; }
  187.             if ($end < 0) { $end = 0; }
  188.             if ($start > $end) {
  189.                 $tmp = $end;
  190.                 $end = $start;
  191.                 $start = $tmp;
  192.                 unset ($tmp);
  193.             }
  194.             
  195.             $file = strtolower (str_replace ("\\", "/", $file));
  196.             $start = (int) $start;
  197.             $end = (int) $end;
  198.             
  199.             $this->_files [] = array ("file"=>$file, "start"=>$start, "end"=>$end);
  200.         } catch (Gumbo_Exception $e) {
  201.             $e->setFunction (__METHOD__);
  202.             gumbo_trigger ($e);
  203.         }
  204.     }
  205.     
  206.     
  207.     
  208.     /**
  209.      * Resets all the restrictions
  210.      * @postcondition $_functions, $_classes, $_files = array ()
  211.      */
  212.     public function resetRestrictions () {
  213.         $this->_functions = array ();
  214.         $this->_classes = array ();
  215.         $this->_files = array ();
  216.     }
  217.     
  218.     /**
  219.      * Resets the Debug messages
  220.      * @postcondition setTime ()
  221.      * @postcondition $_messages = array ()
  222.      */
  223.     public function reset () {
  224.         $this->_setTime (microtime (true));
  225.         $this->_messages = array ();
  226.         
  227.         $this->resetRestrictions ();
  228.     }
  229.     
  230.     /**
  231.      * Activates the Debugger
  232.      * @postcondition $_active = true
  233.      */
  234.     public function activate () {
  235.         $this->_active = true;
  236.     }
  237.     
  238.     /**
  239.      * Deactivates the Debugger
  240.      * @postcondition $_active = false
  241.      */
  242.     public function deactivate () {
  243.         $this->_active = false;
  244.     }
  245.     
  246.     
  247.     
  248.     /** MUTATOR METHODS **/
  249.     /**
  250.      * Sets the time stamp when the debugger started
  251.      * @param num $time 
  252.      * @throws Gumbo_Exception
  253.      */
  254.     private function _setTime ($time) {
  255.         try {
  256.             // verify precondition
  257.             if (!is_double ($time)) {
  258.                 throw new Gumbo_Exception ("Invalid Argument 'time:num' => {$time}:" . gettype ($time));
  259.             }
  260.             
  261.             $this->_time = $time;
  262.         } catch (Gumbo_Exception $e) {
  263.             $e->setFunction (__METHOD__);
  264.             gumbo_trigger ($e);
  265.         }
  266.     }
  267.     
  268.     /**
  269.      * Set the mode to Inclusive
  270.      * @postcondition $_inclusive = true
  271.      */
  272.     public function setInclusive () {
  273.         $this->_inclusive = true;
  274.     }
  275.     
  276.     /**
  277.      * Sets the mode to Exclusive
  278.      * @postcondition $_inclusive = false
  279.      */
  280.     public function setExclusive () {
  281.         $this->_inclusive = false;
  282.     }
  283.     
  284.     
  285.     
  286.     /** ACCESSOR METHODS **/
  287.     /**
  288.      * Returns all the messages of the Debugger
  289.      * @return array 
  290.      */
  291.     public function getAllMessages () {
  292.         return $this->_messages;
  293.     }
  294.     
  295.     /**
  296.      * Returns the time stamp when the Debugger was started
  297.      * @return num 
  298.      */
  299.     public function getTime () {
  300.         return $this->_time;
  301.     }
  302.     
  303.     /**
  304.      * Returns a list of restricted functions
  305.      * @return array 
  306.      */
  307.     private function _getFunctions () {
  308.         return $this->_functions;
  309.     }
  310.     
  311.     /**
  312.      * Returns a list of restricted classes
  313.      * @return array 
  314.      */
  315.     private function _getClasses () {
  316.         return $this->_classes;
  317.     }
  318.     
  319.     /**
  320.      * Returns a list of restricted files
  321.      * @return array 
  322.      */
  323.     private function _getFiles () {
  324.         return $this->_files;
  325.     }
  326.     
  327.     
  328.     
  329.     /**
  330.      * Returns if the Debug mode is active
  331.      * @return bool 
  332.      */
  333.     public function isActive () {
  334.         return $this->_active;
  335.     }
  336.     
  337.     /**
  338.      * Returns if the restrictions are inclusive
  339.      * @return bool 
  340.      */
  341.     public function isInclusive () {
  342.         return $this->_inclusive;
  343.     }
  344.     
  345.     /**
  346.      * Returns if the function is restricted
  347.      * @param string $func function name
  348.      * @param string $cls class name
  349.      * @return bool 
  350.      * @throws Gumbo_Exception
  351.      */
  352.     public function isRestrictedFunction ($func, $cls=null) {
  353.         try {
  354.             // verify precondition
  355.             if (!is_string ($func)) {
  356.                 throw new Gumbo_Exception ("Invalid Argument 'func:str' => {$func}:" . gettype ($func));
  357.             }
  358.             if (!is_null ($cls) && !is_string ($cls)) {
  359.                 throw new Gumbo_Exception ("Invalid Argument 'cls:str' => {$cls}:" . gettype ($cls));
  360.             }
  361.             
  362.             if (!is_null ($cls)) {
  363.                 $func .= "." . $cls;
  364.             }
  365.             
  366.             // loop through restricted functions
  367.             foreach ($this->_getFunctions () as $val) {
  368.                 if ($val == $func) {
  369.                     return true;
  370.                 }
  371.             }
  372.             
  373.         } catch (Gumbo_Exception $e) {
  374.             $e->setFunction (__METHOD__);
  375.             gumbo_trigger ($e);
  376.         }
  377.         return false;
  378.     }
  379.     
  380.     /**
  381.      * Returns if the class is restricted
  382.      * @param string $cls class name
  383.      * @return bool 
  384.      * @throws Gumbo_Exception
  385.      */
  386.     public function isRestrictedClass ($cls) {
  387.         try {
  388.             // verify precondition
  389.             if (!is_string ($cls)) {
  390.                 throw new Gumbo_Exception ("Invalid Argument 'cls:str' => {$cls}:" . gettype ($cls));
  391.             }
  392.             
  393.             // loop through restricted classes
  394.             foreach ($this->_getClasses () as $val) {
  395.                 if ($val == $cls) {
  396.                     return true;
  397.                 }
  398.             }
  399.         } catch (Gumbo_Exception $e) {
  400.             $e->setFunction (__METHOD__);
  401.             gumbo_trigger ($e);
  402.         }
  403.         return false;
  404.     }
  405.     
  406.     /**
  407.      * Returns if the file is restricted
  408.      * @param string $file file name
  409.      * @param int $line line number
  410.      * @return bool 
  411.      * @throws Gumbo_Exception
  412.      */
  413.     public function isRestrictedFile ($file, $line=null) {
  414.         try {
  415.             // verify precondition
  416.             if (!is_string ($file)) {
  417.                 throw new Gumbo_Exception ("Invalid Argument 'file:str' => {$file}:" . gettype ($file));
  418.             }
  419.             if (!is_null ($line) && !is_numeric ($line)) {
  420.                 $line = null;
  421.             }
  422.             
  423.             // loop through restricted files
  424.             foreach ($this->_getFiles () as $val) {
  425.                 if ($val ['file'] == $file) {
  426.                     // check if restricting entire file
  427.                     if ($val ['start'] == 0 && $val ['end'] == 0) {
  428.                         return true;
  429.                     }
  430.                     
  431.                     // check for restriction of line number
  432.                     if (!is_null ($line) && ($val ['start'] <= $line && $val ['end'] >= $line)) {
  433.                         return true;
  434.                     }
  435.                     
  436.                     // check for restrition of file in general
  437.                     if (is_null ($line)) {
  438.                         return true;
  439.                     }
  440.                 }
  441.             }
  442.         } catch (Gumbo_Exception $e) {
  443.             $e->setFunction (__METHOD__);
  444.             gumbo_trigger ($e);
  445.         }
  446.         return false;
  447.     }
  448.     
  449.     
  450.     
  451.     /**
  452.      * Returns an Iterator object
  453.      * @return Iterator 
  454.      */
  455.     public function getIterator () {
  456.         return new Gumbo_Iterator ($this->getAllMessages ());
  457.     }
  458.     
  459. }
  460.  
  461. ?>