Source for file Message.class.php

Documentation is available at Message.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.  * Abstract Log Message
  22.  * 
  23.  * A Log Message contains information that should be logged into the Log file.
  24.  * A Message can contain a single line of information, or span multiple lines.  It
  25.  * depends on the type of Message.  Every line is separated into sections, each
  26.  * section contain an actual piece of data.  The information is written to the
  27.  * Message file, either directly or through a Log class.  The file is appended,
  28.  * placing the formatted message at the end of the file.
  29.  * 
  30.  * The Abstract Message contains a standard formatting implementation.  This will
  31.  * format a string based on the contents of the Message.  The format method will
  32.  * loop through each line, appending a string variable with the details.  The
  33.  * line is formatted started with the 'Left Delimeter'.  Each line is parsed into
  34.  * sections, each section appended to the string, separated by the 'Separator'
  35.  * character string.  The line ends by placing the 'Right Delimeter' before the
  36.  * 'Line End' string.  Once all lines have been formatted, the 'Message' text
  37.  * is set.
  38.  * 
  39.  * To add Lines to a message, call the addLine() method with arguments that represent
  40.  * the sections of the line.  For example, if producing a Log Message with the
  41.  * following format: 'date|id|name', simply call addLine() as:
  42.  * <pre>
  43.  * $mess->addLine ($date, $id, $name);
  44.  * </pre>
  45.  * 
  46.  * Log Files will contain different formats.  In order to format a Log File to
  47.  * a specific format, simply extend the Abstract Message class, writing the rules
  48.  * and defaults in the Constructor (see Gumbo_Log_Message_Generic).  If special
  49.  * formatting is required, simply write a custom 'format' implementation.  If the
  50.  * default values should not be changed, simply 'lock' the message.  (This does
  51.  * not apply to adding lines).
  52.  * 
  53.  * It is important to define the Log File inside the Message class.  An Email Log
  54.  * Message should write to an 'email.log' file, while an Access Log Message should write
  55.  * to an 'access.log' file.  This allows the program to simply create a new Log Message
  56.  * without having to define the file to write to.  By creating multiple Log Messages
  57.  * with specific formatting rules, the program would only need to instantiate the
  58.  * Log Message class, add the necessary details and send to the Log class.
  59.  *
  60.  * @category Gumbo
  61.  * @package Log
  62.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  63.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  64.  * @author Michael Luster <mluster79@yahoo.com>
  65.  * @link http://sourceforge.net/projects/phpgumbo
  66.  * @desc Abstract Log Message
  67.  * @version 0.0.1
  68.  */
  69.  
  70. gumbo_load ("Interface_Lockable");
  71.  
  72. abstract class Gumbo_Log_Message implements Gumbo_Interface_Lockable {
  73.     
  74.     /** @var string $_type log message type */
  75.     private $_type = "default";
  76.     
  77.     /** @var array $_lines a single message line */
  78.     private $_lines = array ();
  79.     /** @var string $_file log file name (absolute path) */
  80.     private $_file = "gumbo.log";
  81.     /** @var string $_message formatted log message */
  82.     private $_message;
  83.     /** @var string $_separator element separator */
  84.     private $_separator = "|";
  85.     
  86.     /** @var string $_line_end end of line string */
  87.     private $_line_end = "\n";
  88.     
  89.     /** @var string $_left_delimeter line begin delimeter */
  90.     private $_left_delimeter;
  91.     /** @var string $_right_delimeter line end delimeter */
  92.     private $_right_delimeter;
  93.     
  94.     /** @var bool $_formatted if the message has been formatted */
  95.     private $_formatted = false;
  96.     
  97.     /** @var bool $_locked if the settings are locked */
  98.     private $_locked = false;
  99.     
  100.     
  101.     
  102.     /** ACTION METHODS **/
  103.     /**
  104.      * Formats the Log message
  105.      * @precondition !isFormatted()
  106.      * @postcondition isFormatted()
  107.      * @postcondition isset($_message)
  108.      */
  109.     protected function format () {
  110.         // verify precondition
  111.         if ($this->isFormatted ()) {
  112.             return;
  113.         }
  114.         
  115.         $txt = false;
  116.         foreach ($this->getLines () as $val) {
  117.             $txt .= $this->getLeftDelimeter ();
  118.             
  119.             if (is_array ($val)) {
  120.                 $x = 1;
  121.                 $num = count ($val);
  122.                 foreach ($val as $element) {
  123.                     if ($x == $num) { $txt .= (string) $element; break; }
  124.                     $txt .= (string) $element;
  125.                     $txt .= $this->getSeparator ();
  126.                     $x++;
  127.                 }
  128.                 
  129.                 unset ($x);
  130.                 unset ($num);
  131.             } else {
  132.                 $txt .= $val;
  133.             }
  134.             
  135.             $txt .= $this->getRightDelimeter ();
  136.             $txt .= $this->getLineEnd ();
  137.         }
  138.         
  139.         $this->setFormatted (true);
  140.         $this->setMessage ($txt);
  141.     }
  142.     
  143.     /**
  144.      * Adds a line to the log message
  145.      * 
  146.      * The arguments supplied will be the data that is represented in the printed
  147.      * string in the message.  Each argument will be a different piece of data, which
  148.      * will be separated by the Separator character string when the message is
  149.      * formatted.
  150.      * 
  151.      * @postcondition !isFormatted()
  152.      */
  153.     public function addLine () {
  154.         // verify preconditions
  155.         $args = array ();
  156.         
  157.         foreach (func_get_args () as $val) {
  158.             if (!is_string ($val) && !is_numeric ($val) && !is_bool ($val)) {
  159.                 $val = null;
  160.             }
  161.             $args [] = $val;
  162.         }
  163.         
  164.         $this->_lines [] = $args;
  165.         $this->setFormatted (false);
  166.     }
  167.     
  168.     /**
  169.      * Resets the message lines
  170.      */
  171.     public function reset () {
  172.         $this->_lines = array ();
  173.         $this->_file = "default.log";
  174.         
  175.         $this->_separator = "|";
  176.         $this->_left_delimeter = null;
  177.         $this->_right_delimeter = null;
  178.         $this->_line_end = "\n";
  179.         
  180.         $this->_message = null;
  181.         $this->setFormatted (false);
  182.     }
  183.     
  184.     /**
  185.      * Locks an object
  186.      * @postcondition isLocked()
  187.      */
  188.     public function lock () {
  189.         $this->_locked = true;
  190.     }
  191.     
  192.     
  193.     
  194.     /** MUTATOR METHODS **/
  195.     /**
  196.      * Sets the message type
  197.      * @precondition !isLocked()
  198.      * @param string $type 
  199.      * @throws Gumbo_Exception
  200.      */
  201.     public function setType ($type) {
  202.         try {
  203.             // verify precondition
  204.             if ($this->isLocked ()) {
  205.                 throw new Gumbo_Exception ("Log Message Locked");
  206.             }
  207.             if (!is_string ($type)) {
  208.                 throw new Gumbo_Exception ("Invalid Argument 'type:str' => {$type}:" . gettype ($type));
  209.             }
  210.             
  211.             $this->_type = $type;
  212.         } catch (Gumbo_Exception $e) {
  213.             $e->setFunction (__METHOD__);
  214.             gumbo_trigger ($e);
  215.         }
  216.     }
  217.     
  218.     /**
  219.      * Sets the message string
  220.      * @param string $mess 
  221.      * @throws Gumbo_Exception
  222.      */
  223.     protected function setMessage ($mess) {
  224.         try {
  225.             // verify precondition
  226.             if (!is_string ($mess)) {
  227.                 throw new Gumbo_Exception ("Invalid Argument 'mess:str' => {$mess}:" . gettype ($mess));
  228.             }
  229.             
  230.             $this->_message = $mess;
  231.         } catch (Gumbo_Exception $e) {
  232.             $e->setFunction (__METHOD__);
  233.             gumbo_trigger ($e);
  234.         }
  235.     }
  236.     
  237.     /**
  238.      * Sets if the message has been formatted
  239.      * @param bool $val 
  240.      * @throws Gumbo_Exception
  241.      */
  242.     protected function setFormatted ($val) {
  243.         try {
  244.             // verify precondition
  245.             if (!is_bool ($val)) {
  246.                 throw new Gumbo_Exception ("Invalid Argument 'val:bool' => {$val}:" . gettype ($val));
  247.             }
  248.             
  249.             $this->_formatted = $val;
  250.         } catch (Gumbo_Exception $e) {
  251.             $e->setFunction (__METHOD__);
  252.             gumbo_trigger ($e);
  253.         }
  254.     }
  255.     
  256.     /**
  257.      * Sets the log file
  258.      * @precondition !isLocked()
  259.      * @param string $file file name (absolute path)
  260.      * @throws Gumbo_Exception
  261.      */
  262.     public function setFile ($file) {
  263.         try {
  264.             // verify precondition
  265.             if ($this->isLocked ()) {
  266.                 throw new Gumbo_Exception ("Log Message Locked");
  267.             }
  268.             if (!is_string ($file)) {
  269.                 throw new Gumbo_Exception ("Invalid Argument 'file:str' => {$file}:" . gettype ($file));
  270.             }
  271.             
  272.             $this->_file = $file;
  273.         } catch (Gumbo_Exception $e) {
  274.             $e->setFunction (__METHOD__);
  275.             gumbo_trigger ($e);
  276.         }
  277.     }
  278.     
  279.     /**
  280.      * Sets the line end string
  281.      * @precondition !isLocked()
  282.      * @postcondition !isFormatted()
  283.      * @param string $end 
  284.      * @throws Gumbo_Exception
  285.      */
  286.     public function setLineEnd ($end) {
  287.         try {
  288.             // verify precondition
  289.             if ($this->isLocked ()) {
  290.                 throw new Gumbo_Exception ("Log Message Locked");
  291.             }
  292.             if (!is_string ($end)) {
  293.                 throw new Gumbo_Exception ("Invalid Argument 'end:str' => {$end}:" . gettype ($end));
  294.             }
  295.             
  296.             $this->_line_end = $end;
  297.             $this->setFormatted (false);
  298.         } catch (Gumbo_Exception $e) {
  299.             $e->setFunction (__METHOD__);
  300.             gumbo_trigger ($e);
  301.         }
  302.     }
  303.     
  304.     /**
  305.      * Sets the separator between elements
  306.      * @precondition !isLocked()
  307.      * @postcondition !isFormatted()
  308.      * @param string $sep 
  309.      * @throws Gumbo_Exception
  310.      */
  311.     public function setSeparator ($sep) {
  312.         try {
  313.             // verify precondition
  314.             if ($this->isLocked ()) {
  315.                 throw new Gumbo_Exception ("Log Message Locked");
  316.             }
  317.             if (!is_string ($sep)) {
  318.                 throw new Gumbo_Exception ("Invalid Argument 'sep:str' => {$sep}:" . gettype ($sep));
  319.             }
  320.             
  321.             $this->_separator = $sep;
  322.             $this->setFormatted (false);
  323.         } catch (Gumbo_Exception $e) {
  324.             $e->setFunction (__METHOD__);
  325.             gumbo_trigger ($e);
  326.         }
  327.     }
  328.     
  329.     /**
  330.      * Sets the left delimeter
  331.      * @precondition !isLocked()
  332.      * @postcondition !isFormatted()
  333.      * @param string $del 
  334.      * @throws Gumbo_Exception
  335.      */
  336.     public function setLeftDelimeter ($del) {
  337.         try {
  338.             // verify precondition
  339.             if ($this->isLocked ()) {
  340.                 throw new Gumbo_Exception ("Log Message Locked");
  341.             }
  342.             if (!is_string ($del) && !is_null ($del)) {
  343.                 throw new Gumbo_Exception ("Invalid Argument 'del:str|null' => {$del}:" . gettype ($del));
  344.             }
  345.             
  346.             $this->_left_delimeter = $del;
  347.             $this->setFormatted (false);
  348.         } catch (Gumbo_Exception $e) {
  349.             $e->setFunction (__METHOD__);
  350.             gumbo_trigger ($e);
  351.         }
  352.     }
  353.     
  354.     /**
  355.      * Sets the right delimeter
  356.      * @precondition !isLocked()
  357.      * @postcondition !isFormatted()
  358.      * @param string $del 
  359.      * @throws Gumbo_Exception
  360.      */
  361.     public function setRightDelimeter ($del) {
  362.         try {
  363.             // verify precondition
  364.             if ($this->isLocked ()) {
  365.                 throw new Gumbo_Exception ("Log Message Locked");
  366.             }
  367.             if (!is_string ($del) && !is_null ($del)) {
  368.                 throw new Gumbo_Exception ("Invalid Argument 'del:str|null' => {$del}:" . gettype ($del));
  369.             }
  370.             
  371.             $this->_right_delimeter = $del;
  372.             $this->setFormatted (false);
  373.         } catch (Gumbo_Exception $e) {
  374.             $e->setFunction (__METHOD__);
  375.             gumbo_trigger ($e);
  376.         }
  377.     }
  378.     
  379.     
  380.     
  381.     
  382.     /** ACCESSOR METHODS **/
  383.     /**
  384.      * Returns the message type
  385.      * @return string 
  386.      */
  387.     public function getType () {
  388.         return $this->_type;
  389.     }
  390.     
  391.     /**
  392.      * Returns the message
  393.      * @return string 
  394.      */
  395.     public function getMessage () {
  396.         $this->format ();
  397.         return $this->_message;
  398.     }
  399.     
  400.     /**
  401.      * Returns the log file
  402.      * @return string 
  403.      */
  404.     public function getFile () {
  405.         return $this->_file;
  406.     }
  407.     
  408.     /**
  409.      * Returns all the message lines
  410.      * @return array 
  411.      */
  412.     public function getLines () {
  413.         return $this->_lines;
  414.     }
  415.     
  416.     /**
  417.      * Returns the line ending string
  418.      * @return string 
  419.      */
  420.     public function getLineEnd () {
  421.         return $this->_line_end;
  422.     }
  423.     
  424.     /**
  425.      * Returns the element separator
  426.      * @return string 
  427.      */
  428.     public function getSeparator () {
  429.         return $this->_separator;
  430.     }
  431.     
  432.     /**
  433.      * Returns the left delimeter
  434.      * @return string 
  435.      */
  436.     public function getLeftDelimeter () {
  437.         return $this->_left_delimeter;
  438.     }
  439.     
  440.     /**
  441.      * Returns the right delimeter
  442.      * @return string 
  443.      */
  444.     public function getRightDelimeter () {
  445.         return $this->_right_delimeter;
  446.     }
  447.     
  448.     /**
  449.      * Returns if the message has been formatted
  450.      * @return bool 
  451.      */
  452.     public function isFormatted () {
  453.         return $this->_formatted;
  454.     }
  455.     
  456.     /**
  457.      * Returns if the object is currently locked
  458.      * @return bool 
  459.      */
  460.     public function isLocked () {
  461.         return $this->_locked;
  462.     }
  463.     
  464. }
  465.  
  466. ?>