Source for file Log.class.php

Documentation is available at Log.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 Log
  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.  * Log Class
  22.  * 
  23.  * The Log class receives all Log_Message objects from the program.  The Message
  24.  * must be an active type (or ignore types on).  When the program is ready, simply
  25.  * call the 'write' method to save all the Message into a file.  Once written,
  26.  * the messages are removed.
  27.  * 
  28.  * The class implements the Lockable Interface.  This lock only applies to Message
  29.  * Types.  Once set, it cannot be unlocked from outside the class.  This helps to
  30.  * ensure that additional Log Types are not added in other locations of the program.
  31.  *
  32.  * @category Gumbo
  33.  * @package Log
  34.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  35.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  36.  * @author Michael Luster <mluster79@yahoo.com>
  37.  * @link http://sourceforge.net/projects/phpgumbo
  38.  * @desc Log Class
  39.  * @version 0.0.1
  40.  */
  41.  
  42. gumbo_load ("Interface_Singleton");
  43. gumbo_load ("Interface_Lockable");
  44. gumbo_load ("Interface_Log");
  45. gumbo_load ("Log_Message");
  46.  
  47. class Gumbo_Log implements Gumbo_Interface_Singleton, Gumbo_Interface_Log, Gumbo_Interface_Lockable {
  48.     
  49.     /** @var Gumbo_Interface_Singleton $_instance */
  50.     private static $_instance = null;
  51.     
  52.     /** @var Gumbo_Log_Message[] $_messages list of Log_Messages */
  53.     private $_messages = array ();
  54.     /** @var bool $_status Logging turned on or off */
  55.     private $_status = false;
  56.     
  57.     /** @var array $_types type of Log messages to allow */
  58.     private $_types = array ();
  59.     /** @var bool $_ignore ignores Type restrictions */
  60.     private $_ignore = false;
  61.     
  62.     /** @var bool $_locked if Log Message Types are locked */
  63.     private $_locked = false;
  64.     
  65.     
  66.     
  67.     /**
  68.      * Constructor
  69.      */
  70.     private function __construct () {}
  71.     
  72.     /**
  73.      * Singleton Method
  74.      * @return Gumbo_Interface_Log 
  75.      */
  76.     public static function instance () {
  77.         if (self::$_instance == null) {
  78.             self::$_instance = new Gumbo_Log ();
  79.         }
  80.         return self::$_instance;
  81.     }
  82.     
  83.     
  84.     
  85.     /** ACTION METHODS **/
  86.     /**
  87.      * Writes the messages to the corresponding Log file
  88.      * @precondition isOn()
  89.      * @throws Gumbo_Exception
  90.      */
  91.     public function write () {
  92.         // check if Logging is turned on
  93.         if (!$this->isOn ()) {
  94.             return;
  95.         }
  96.         
  97.         foreach ($this->getAll () as $mess) {
  98.             // check message type
  99.             if (!$this->ignoreTypes () && !$this->isType ($mess->getType ())) {
  100.                 continue;
  101.             }
  102.             
  103.             try {
  104.                 // verify precondition
  105.                 if ($fp = @fopen ($mess->getFile (), "a+")) {
  106.                     fwrite ($fp, $mess->getMessage ());
  107.                     @fclose ($fp);
  108.                 } else {
  109.                     throw new Gumbo_Exception ("Unable to Append Log File: {$mess->getFile ()}");
  110.                 }
  111.             } catch (Gumbo_Exception $e) {
  112.                 $e->setFunction (__METHOD__);
  113.                 gumbo_trigger ($e);
  114.             }
  115.         }
  116.         $this->clear ();
  117.     }
  118.     
  119.     /**
  120.      * Adds a log message to the list
  121.      * @precondition isOn()
  122.      * @param Gumbo_Interface_Log_Message $mess 
  123.      */
  124.     public function add (Gumbo_Log_Message $mess) {
  125.         // verify precondition
  126.         if (!$this->isOn ()) {
  127.             return;
  128.         }
  129.         
  130.         // check message type
  131.         if (!$this->ignoreTypes () && !$this->isType ($mess->getType ())) {
  132.             return;
  133.         }
  134.         
  135.         $this->_messages [] = $mess;
  136.     }
  137.     
  138.     /**
  139.      * Clears the log messages in the system
  140.      */
  141.     public function clear () {
  142.         $this->_messages = array ();
  143.     }
  144.     
  145.     /**
  146.      * Turn on Logging
  147.      * @postcondition isOn()
  148.      */
  149.     public function turnOn () {
  150.         $this->_status = true;
  151.     }
  152.     
  153.     /**
  154.      * Turn off Logging
  155.      * @postcondition !isOn()
  156.      */
  157.     public function turnOff () {
  158.         $this->_status = false;
  159.     }
  160.     
  161.     /**
  162.      * Adds an active Log Message Type
  163.      * @precondition !isLocked()
  164.      * @precondition Type is not set
  165.      * @param string $type 
  166.      */
  167.     public function addType ($type) {
  168.         try {
  169.             // verify precondition
  170.             if ($this->isLocked ()) {
  171.                 throw new Gumbo_Exception ("Log Types Locked");
  172.             }
  173.             if (!is_string ($type)) {
  174.                 throw new Gumbo_Exception ("Invalid Argument 'type:str' => {$type}:" . gettype ($type));
  175.             }
  176.             if ($this->isType ($type)) {
  177.                 throw new Gumbo_Exception ("Type Defined: {$type}");
  178.             }
  179.             
  180.             $this->_types [] = $type;
  181.         } catch (Gumbo_Exception $e) {
  182.             $e->setFunction (__METHOD__);
  183.             gumbo_trigger ($e);
  184.         }
  185.     }
  186.     
  187.     /**
  188.      * Removes an active Log Message Type
  189.      * @precondition !isLocked()
  190.      * @precondition Type set
  191.      * @param string $type 
  192.      */
  193.     public function delType ($type) {
  194.         try {
  195.             // verify precondition
  196.             if ($this->isLocked ()) {
  197.                 throw new Gumbo_Exception ("Log Types Locked");
  198.             }
  199.             if (!is_string ($type)) {
  200.                 throw new Gumbo_Exception ("Invalid Argument 'type:str' => {$type}:" . gettype ($type));
  201.             }
  202.             if (!$this->isType ($type)) {
  203.                 throw new Gumbo_Exception ("Type Undefined: {$type}");
  204.             }
  205.             
  206.             foreach ($this->getTypes () as $key=>$val) {
  207.                 if ($type == $val) {
  208.                     unset ($this->_types [$key]);
  209.                     break;
  210.                 }
  211.             }
  212.         } catch (Gumbo_Exception $e) {
  213.             $e->setFunction (__METHOD__);
  214.             gumbo_trigger ($e);
  215.         }
  216.     }
  217.     
  218.     /**
  219.      * Resets the types
  220.      * @precondition !isLocked()
  221.      * @postcondition !getTypes()
  222.      * @throws Gumbo_Exception
  223.      */
  224.     public function resetTypes () {
  225.         try {
  226.             // verify precondition
  227.             if ($this->isLocked ()) {
  228.                 throw new Gumbo_Exception ("Log Types Locked");
  229.             }
  230.             
  231.             $this->_types = array ();
  232.         } catch (Gumbo_Exception $e) {
  233.             $e->setFunction (__METHOD__);
  234.             gumbo_trigger ($e);
  235.         }
  236.     }
  237.     
  238.     /**
  239.      * Locks an object
  240.      * @postcondition isLocked()
  241.      */
  242.     public function lock () {
  243.         $this->_locked = true;
  244.     }
  245.     
  246.     
  247.     
  248.     /** ACCESSOR METHODS **/
  249.     /**
  250.      * Returns all the log messages
  251.      * @return array 
  252.      */
  253.     public function getAll () {
  254.         return $this->_messages;
  255.     }
  256.     
  257.     /**
  258.      * Returns all the registered message types
  259.      * @return array 
  260.      */
  261.     public function getTypes () {
  262.         return $this->_types;
  263.     }
  264.     
  265.     /**
  266.      * Returns if Logging is on
  267.      * @return bool 
  268.      */
  269.     public function isOn () {
  270.         return $this->_status;
  271.     }
  272.     
  273.     /**
  274.      * Returns if the message type is registered
  275.      * @param string $type 
  276.      * @return bool 
  277.      * @throws Gumbo_Exception
  278.      */
  279.     public function isType ($type) {
  280.         $found = false;
  281.         try {
  282.             // verify precondition
  283.             if (!is_string ($type)) {
  284.                 throw new Gumbo_Exception ("Invalid Argument 'type:str' => {$type}:" . gettype ($type));
  285.             }
  286.             
  287.             foreach ($this->getTypes () as $val) {
  288.                 if ($type == $val) {
  289.                     $found = true;
  290.                     break;
  291.                 }
  292.             }
  293.         } catch (Gumbo_Exception $e) {
  294.             $e->setFunction (__METHOD__);
  295.             gumbo_trigger ($e);
  296.         }
  297.         return $found;
  298.     }
  299.     
  300.     /**
  301.      * Returns if to ignore Types (or set to ignore Types)
  302.      * @precondition !isLocked()
  303.      * @param bool $ignore 
  304.      * @return bool 
  305.      * @throws Gumbo_Exception
  306.      */
  307.     public function ignoreTypes ($ignore=null) {
  308.         try {
  309.             // verify precondition
  310.             if ($this->isLocked ()) {
  311.                 throw new Gumbo_Exception ("Log Types Locked");
  312.             }
  313.             if (!is_null ($ignore) && !is_bool ($ignore)) {
  314.                 throw new Gumbo_Exception ("Invalid Argument 'ignore:bool|null' => {$ignore}:" . gettype ($ignore));
  315.             }
  316.             
  317.             if (is_null ($ignore)) {
  318.                 return $this->_ignore;
  319.             }
  320.             $this->_ignore = $ignore;
  321.         } catch (Gumbo_Exception $e) {
  322.             $e->setFunction (__METHOD__);
  323.             gumbo_trigger ($e);
  324.         }
  325.     }
  326.     
  327.     /**
  328.      * Returns if the object is currently locked
  329.      * @return bool 
  330.      */
  331.     public function isLocked () {
  332.         return $this->_locked;
  333.     }
  334.     
  335. }
  336.  
  337. ?>