[Sommaire] [Imprimer]

   1  <?php
   2  /**
   3   * $Header: /repository/pear/Log/Log.php,v 1.46 2004/09/09 02:42:22 jon Exp $
   4   * $Horde: horde/lib/Log.php,v 1.15 2000/06/29 23:39:45 jon Exp $
   5   *
   6   * @version $Revision: 1.46 $
   7   * @package Log
   8   */
   9  
  10  define('PEAR_LOG_EMERG',    0);     /** System is unusable */
  11  define('PEAR_LOG_ALERT',    1);     /** Immediate action required */
  12  define('PEAR_LOG_CRIT',     2);     /** Critical conditions */
  13  define('PEAR_LOG_ERR',      3);     /** Error conditions */
  14  define('PEAR_LOG_WARNING',  4);     /** Warning conditions */
  15  define('PEAR_LOG_NOTICE',   5);     /** Normal but significant */
  16  define('PEAR_LOG_INFO',     6);     /** Informational */
  17  define('PEAR_LOG_DEBUG',    7);     /** Debug-level messages */
  18  
  19  define('PEAR_LOG_ALL',      bindec('11111111'));  /** All messages */
  20  define('PEAR_LOG_NONE',     bindec('00000000'));  /** No message */
  21  
  22  /* Log types for PHP's native error_log() function. */
  23  define('PEAR_LOG_TYPE_SYSTEM',  0); /** Use PHP's system logger */
  24  define('PEAR_LOG_TYPE_MAIL',    1); /** Use PHP's mail() function */
  25  define('PEAR_LOG_TYPE_DEBUG',   2); /** Use PHP's debugging connection */
  26  define('PEAR_LOG_TYPE_FILE',    3); /** Append to a file */
  27  
  28  /**
  29   * The Log:: class implements both an abstraction for various logging
  30   * mechanisms and the Subject end of a Subject-Observer pattern.
  31   *
  32   * @author  Chuck Hagenbuch <chuck@horde.org>
  33   * @author  Jon Parise <jon@php.net>
  34   * @since   Horde 1.3
  35   * @package Log
  36   */
  37  class Log
  38  {
  39      /**
  40       * Indicates whether or not the log can been opened / connected.
  41       *
  42       * @var boolean
  43       * @access private
  44       */
  45      var $_opened = false;
  46  
  47      /**
  48       * Instance-specific unique identification number.
  49       *
  50       * @var integer
  51       * @access private
  52       */
  53      var $_id = 0;
  54  
  55      /**
  56       * The label that uniquely identifies this set of log messages.
  57       *
  58       * @var string
  59       * @access private
  60       */
  61      var $_ident = '';
  62  
  63      /**
  64       * The default priority to use when logging an event.
  65       *
  66       * @var integer
  67       * @access private
  68       */
  69      var $_priority = PEAR_LOG_INFO;
  70  
  71      /**
  72       * The bitmask of allowed log levels.
  73       * @var integer
  74       * @access private
  75       */
  76      var $_mask = PEAR_LOG_ALL;
  77  
  78      /**
  79       * Holds all Log_observer objects that wish to be notified of new messages.
  80       *
  81       * @var array
  82       * @access private
  83       */
  84      var $_listeners = array();
  85  
  86  
  87      /**
  88       * Attempts to return a concrete Log instance of type $handler.
  89       *
  90       * @param string $handler   The type of concrete Log subclass to return.
  91       *                          Attempt to dynamically include the code for
  92       *                          this subclass. Currently, valid values are
  93       *                          'console', 'syslog', 'sql', 'file', and 'mcal'.
  94       *
  95       * @param string $name      The name of the actually log file, table, or
  96       *                          other specific store to use. Defaults to an
  97       *                          empty string, with which the subclass will
  98       *                          attempt to do something intelligent.
  99       *
 100       * @param string $ident     The identity reported to the log system.
 101       *
 102       * @param array  $conf      A hash containing any additional configuration
 103       *                          information that a subclass might need.
 104       *
 105       * @param int $level        Log messages up to and including this level.
 106       *
 107       * @return object Log       The newly created concrete Log instance, or an
 108       *                          false on an error.
 109       * @access public
 110       * @since Log 1.0
 111       */
 112      function &factory($handler, $name = '', $ident = '', $conf = array(),
 113                        $level = PEAR_LOG_DEBUG)
 114      {
 115          $handler = strtolower($handler);
 116          $class = 'Log_' . $handler;
 117          $classfile = 'Log/' . $handler . '.php';
 118  
 119          /*
 120           * Attempt to include our version of the named class, but don't treat
 121           * a failure as fatal.  The caller may have already included their own
 122           * version of the named class.
 123           */
 124          @include_once $classfile;
 125  
 126          /* If the class exists, return a new instance of it. */
 127          if (class_exists($class)) {
 128              return new $class($name, $ident, $conf, $level);
 129          }
 130  
 131          return false;
 132      }
 133  
 134      /**
 135       * Attempts to return a reference to a concrete Log instance of type
 136       * $handler, only creating a new instance if no log instance with the same
 137       * parameters currently exists.
 138       *
 139       * You should use this if there are multiple places you might create a
 140       * logger, you don't want to create multiple loggers, and you don't want to
 141       * check for the existance of one each time. The singleton pattern does all
 142       * the checking work for you.
 143       *
 144       * <b>You MUST call this method with the $var = &Log::singleton() syntax.
 145       * Without the ampersand (&) in front of the method name, you will not get
 146       * a reference, you will get a copy.</b>
 147       *
 148       * @param string $handler   The type of concrete Log subclass to return.
 149       *                          Attempt to dynamically include the code for
 150       *                          this subclass. Currently, valid values are
 151       *                          'console', 'syslog', 'sql', 'file', and 'mcal'.
 152       *
 153       * @param string $name      The name of the actually log file, table, or
 154       *                          other specific store to use.  Defaults to an
 155       *                          empty string, with which the subclass will
 156       *                          attempt to do something intelligent.
 157       *
 158       * @param string $ident     The identity reported to the log system.
 159       *
 160       * @param array $conf       A hash containing any additional configuration
 161       *                          information that a subclass might need.
 162       *
 163       * @param int $level        Log messages up to and including this level.
 164       *
 165       * @return object Log       The newly created concrete Log instance, or an
 166       *                          false on an error.
 167       * @access public
 168       * @since Log 1.0
 169       */
 170      function &singleton($handler, $name = '', $ident = '', $conf = array(),
 171                          $level = PEAR_LOG_DEBUG)
 172      {
 173          static $instances;
 174          if (!isset($instances)) $instances = array();
 175  
 176          $signature = serialize(array($handler, $name, $ident, $conf, $level));
 177          if (!isset($instances[$signature])) {
 178              $instances[$signature] = &Log::factory($handler, $name, $ident,
 179                                                     $conf, $level);
 180          }
 181  
 182          return $instances[$signature];
 183      }
 184  
 185      /**
 186       * Abstract implementation of the open() method.
 187       * @since Log 1.0
 188       */
 189      function open()
 190      {
 191          return false;
 192      }
 193  
 194      /**
 195       * Abstract implementation of the close() method.
 196       * @since Log 1.0
 197       */
 198      function close()
 199      {
 200          return false;
 201      }
 202  
 203      /**
 204       * Abstract implementation of the flush() method.
 205       * @since Log 1.8.2
 206       */
 207      function flush()
 208      {
 209          return false;
 210      }
 211  
 212      /**
 213       * Abstract implementation of the log() method.
 214       * @since Log 1.0
 215       */
 216      function log($message, $priority = null)
 217      {
 218          return false;
 219      }
 220  
 221      /**
 222       * A convenience function for logging a emergency event.  It will log a
 223       * message at the PEAR_LOG_EMERG log level.
 224       *
 225       * @param   mixed   $message    String or object containing the message
 226       *                              to log.
 227       *
 228       * @return  boolean True if the message was successfully logged.
 229       *
 230       * @access  public
 231       * @since   Log 1.7.0
 232       */
 233      function emerg($message)
 234      {
 235          return $this->log($message, PEAR_LOG_EMERG);
 236      }
 237  
 238      /**
 239       * A convenience function for logging an alert event.  It will log a
 240       * message at the PEAR_LOG_ALERT log level.
 241       *
 242       * @param   mixed   $message    String or object containing the message
 243       *                              to log.
 244       *
 245       * @return  boolean True if the message was successfully logged.
 246       *
 247       * @access  public
 248       * @since   Log 1.7.0
 249       */
 250      function alert($message)
 251      {
 252          return $this->log($message, PEAR_LOG_ALERT);
 253      }
 254  
 255      /**
 256       * A convenience function for logging a critical event.  It will log a
 257       * message at the PEAR_LOG_CRIT log level.
 258       *
 259       * @param   mixed   $message    String or object containing the message
 260       *                              to log.
 261       *
 262       * @return  boolean True if the message was successfully logged.
 263       *
 264       * @access  public
 265       * @since   Log 1.7.0
 266       */
 267      function crit($message)
 268      {
 269          return $this->log($message, PEAR_LOG_CRIT);
 270      }
 271  
 272      /**
 273       * A convenience function for logging a error event.  It will log a
 274       * message at the PEAR_LOG_ERR log level.
 275       *
 276       * @param   mixed   $message    String or object containing the message
 277       *                              to log.
 278       *
 279       * @return  boolean True if the message was successfully logged.
 280       *
 281       * @access  public
 282       * @since   Log 1.7.0
 283       */
 284      function err($message)
 285      {
 286          return $this->log($message, PEAR_LOG_ERR);
 287      }
 288  
 289      /**
 290       * A convenience function for logging a warning event.  It will log a
 291       * message at the PEAR_LOG_WARNING log level.
 292       *
 293       * @param   mixed   $message    String or object containing the message
 294       *                              to log.
 295       *
 296       * @return  boolean True if the message was successfully logged.
 297       *
 298       * @access  public
 299       * @since   Log 1.7.0
 300       */
 301      function warning($message)
 302      {
 303          return $this->log($message, PEAR_LOG_WARNING);
 304      }
 305  
 306      /**
 307       * A convenience function for logging a notice event.  It will log a
 308       * message at the PEAR_LOG_NOTICE log level.
 309       *
 310       * @param   mixed   $message    String or object containing the message
 311       *                              to log.
 312       *
 313       * @return  boolean True if the message was successfully logged.
 314       *
 315       * @access  public
 316       * @since   Log 1.7.0
 317       */
 318      function notice($message)
 319      {
 320          return $this->log($message, PEAR_LOG_NOTICE);
 321      }
 322  
 323      /**
 324       * A convenience function for logging a information event.  It will log a
 325       * message at the PEAR_LOG_INFO log level.
 326       *
 327       * @param   mixed   $message    String or object containing the message
 328       *                              to log.
 329       *
 330       * @return  boolean True if the message was successfully logged.
 331       *
 332       * @access  public
 333       * @since   Log 1.7.0
 334       */
 335      function info($message)
 336      {
 337          return $this->log($message, PEAR_LOG_INFO);
 338      }
 339  
 340      /**
 341       * A convenience function for logging a debug event.  It will log a
 342       * message at the PEAR_LOG_DEBUG log level.
 343       *
 344       * @param   mixed   $message    String or object containing the message
 345       *                              to log.
 346       *
 347       * @return  boolean True if the message was successfully logged.
 348       *
 349       * @access  public
 350       * @since   Log 1.7.0
 351       */
 352      function debug($message)
 353      {
 354          return $this->log($message, PEAR_LOG_DEBUG);
 355      }
 356  
 357      /**
 358       * Returns the string representation of the message data.
 359       *
 360       * If $message is an object, _extractMessage() will attempt to extract
 361       * the message text using a known method (such as a PEAR_Error object's
 362       * getMessage() method).  If a known method, cannot be found, the
 363       * serialized representation of the object will be returned.
 364       *
 365       * If the message data is already a string, it will be returned unchanged.
 366       *
 367       * @param  mixed $message   The original message data.  This may be a
 368       *                          string or any object.
 369       *
 370       * @return string           The string representation of the message.
 371       *
 372       * @access private
 373       */
 374      function _extractMessage($message)
 375      {
 376          /*
 377           * If we've been given an object, attempt to extract the message using
 378           * a known method.  If we can't find such a method, default to the
 379           * "human-readable" version of the object.
 380           *
 381           * We also use the human-readable format for arrays.
 382           */
 383          if (is_object($message)) {
 384              if (method_exists($message, 'getmessage')) {
 385                  $message = $message->getMessage();
 386              } else if (method_exists($message, 'tostring')) {
 387                  $message = $message->toString();
 388              } else if (method_exists($message, '__tostring')) {
 389                  $message = (string)$message;
 390              } else {
 391                  $message = print_r($message, true);
 392              }
 393          } else if (is_array($message)) {
 394              if (isset($message['message'])) {
 395                  $message = $message['message'];
 396              } else {
 397                  $message = print_r($message, true);
 398              }
 399          }
 400  
 401          /* Otherwise, we assume the message is a string. */
 402          return $message;
 403      }
 404  
 405      /**
 406       * Returns the string representation of a PEAR_LOG_* integer constant.
 407       *
 408       * @param int $priority     A PEAR_LOG_* integer constant.
 409       *
 410       * @return string           The string representation of $level.
 411       *
 412       * @since   Log 1.0
 413       */
 414      function priorityToString($priority)
 415      {
 416          $levels = array(
 417              PEAR_LOG_EMERG   => 'emergency',
 418              PEAR_LOG_ALERT   => 'alert',
 419              PEAR_LOG_CRIT    => 'critical',
 420              PEAR_LOG_ERR     => 'error',
 421              PEAR_LOG_WARNING => 'warning',
 422              PEAR_LOG_NOTICE  => 'notice',
 423              PEAR_LOG_INFO    => 'info',
 424              PEAR_LOG_DEBUG   => 'debug'
 425          );
 426  
 427          return $levels[$priority];
 428      }
 429  
 430      /**
 431       * Calculate the log mask for the given priority.
 432       *
 433       * @param integer   $priority   The priority whose mask will be calculated.
 434       *
 435       * @return integer  The calculated log mask.
 436       *
 437       * @access  public
 438       * @since   Log 1.7.0
 439       */
 440      function MASK($priority)
 441      {
 442          return (1 << $priority);
 443      }
 444  
 445      /**
 446       * Calculate the log mask for all priorities up to the given priority.
 447       *
 448       * @param integer   $priority   The maximum priority covered by this mask.
 449       *
 450       * @return integer  The calculated log mask.
 451       *
 452       * @access  public
 453       * @since   Log 1.7.0
 454       */
 455      function UPTO($priority)
 456      {
 457          return ((1 << ($priority + 1)) - 1);
 458      }
 459  
 460      /**
 461       * Set and return the level mask for the current Log instance.
 462       *
 463       * @param integer $mask     A bitwise mask of log levels.
 464       *
 465       * @return integer          The current level mask.
 466       *
 467       * @access  public
 468       * @since   Log 1.7.0
 469       */
 470      function setMask($mask)
 471      {
 472          $this->_mask = $mask;
 473  
 474          return $this->_mask;
 475      }
 476  
 477      /**
 478       * Returns the current level mask.
 479       *
 480       * @return interger         The current level mask.
 481       *
 482       * @access  public
 483       * @since   Log 1.7.0
 484       */
 485      function getMask()
 486      {
 487          return $this->_mask;
 488      }
 489  
 490      /**
 491       * Check if the given priority is included in the current level mask.
 492       *
 493       * @param integer   $priority   The priority to check.
 494       *
 495       * @return boolean  True if the given priority is included in the current
 496       *                  log mask.
 497       *
 498       * @access  private
 499       * @since   Log 1.7.0
 500       */
 501      function _isMasked($priority)
 502      {
 503          return (Log::MASK($priority) & $this->_mask);
 504      }
 505  
 506      /**
 507       * Returns the current default priority.
 508       *
 509       * @return integer  The current default priority.
 510       *
 511       * @access  public
 512       * @since   Log 1.8.4
 513       */
 514      function getPriority()
 515      {
 516          return $this->_priority;
 517      }
 518  
 519      /**
 520       * Sets the default priority to the specified value.
 521       *
 522       * @param   integer $priority   The new default priority.
 523       *
 524       * @access  public
 525       * @since   Log 1.8.4
 526       */
 527      function setPriority($priority)
 528      {
 529          $this->_priority = $priority;
 530      }
 531  
 532      /**
 533       * Adds a Log_observer instance to the list of observers that are listening
 534       * for messages emitted by this Log instance.
 535       *
 536       * @param object    $observer   The Log_observer instance to attach as a
 537       *                              listener.
 538       *
 539       * @param boolean   True if the observer is successfully attached.
 540       *
 541       * @access  public
 542       * @since   Log 1.0
 543       */
 544      function attach(&$observer)
 545      {
 546          if (!is_a($observer, 'Log_observer')) {
 547              return false;
 548          }
 549  
 550          $this->_listeners[$observer->_id] = &$observer;
 551  
 552          return true;
 553      }
 554  
 555      /**
 556       * Removes a Log_observer instance from the list of observers.
 557       *
 558       * @param object    $observer   The Log_observer instance to detach from
 559       *                              the list of listeners.
 560       *
 561       * @param boolean   True if the observer is successfully detached.
 562       *
 563       * @access  public
 564       * @since   Log 1.0
 565       */
 566      function detach($observer)
 567      {
 568          if (!is_a($observer, 'Log_observer') ||
 569              !isset($this->_listeners[$observer->_id])) {
 570              return false;
 571          }
 572  
 573          unset($this->_listeners[$observer->_id]);
 574  
 575          return true;
 576      }
 577  
 578      /**
 579       * Informs each registered observer instance that a new message has been
 580       * logged.
 581       *
 582       * @param array     $event      A hash describing the log event.
 583       *
 584       * @access private
 585       */
 586      function _announce($event)
 587      {
 588          foreach ($this->_listeners as $id => $listener) {
 589              if ($event['priority'] <= $this->_listeners[$id]->_priority) {
 590                  $this->_listeners[$id]->notify($event);
 591              }
 592          }
 593      }
 594  
 595      /**
 596       * Indicates whether this is a composite class.
 597       *
 598       * @return boolean          True if this is a composite class.
 599       *
 600       * @access  public
 601       * @since   Log 1.0
 602       */
 603      function isComposite()
 604      {
 605          return false;
 606      }
 607  
 608      /**
 609       * Sets this Log instance's identification string.
 610       *
 611       * @param string    $ident      The new identification string.
 612       *
 613       * @access  public
 614       * @since   Log 1.6.3
 615       */
 616      function setIdent($ident)
 617      {
 618          $this->_ident = $ident;
 619      }
 620  
 621      /**
 622       * Returns the current identification string.
 623       *
 624       * @return string   The current Log instance's identification string.
 625       *
 626       * @access  public
 627       * @since   Log 1.6.3
 628       */
 629      function getIdent()
 630      {
 631          return $this->_ident;
 632      }
 633  }
 634  
 635  ?>