<?php
/**
 * $Header$
 * $Horde: horde/lib/Log.php,v 1.15 2000/06/29 23:39:45 jon Exp $
 *
 * @version $Revision$
 * @package Log
 */

define('PEAR_LOG_EMERG',    0);     /* System is unusable */
define('PEAR_LOG_ALERT',    1);     /* Immediate action required */
define('PEAR_LOG_CRIT',     2);     /* Critical conditions */
define('PEAR_LOG_ERR',      3);     /* Error conditions */
define('PEAR_LOG_WARNING',  4);     /* Warning conditions */
define('PEAR_LOG_NOTICE',   5);     /* Normal but significant */
define('PEAR_LOG_INFO',     6);     /* Informational */
define('PEAR_LOG_DEBUG',    7);     /* Debug-level messages */

define('PEAR_LOG_ALL',      0xffffffff);    /* All messages */
define('PEAR_LOG_NONE',     0x00000000);    /* No message */

/* Log types for PHP's native error_log() function. */
define('PEAR_LOG_TYPE_SYSTEM',  0); /* Use PHP's system logger */
define('PEAR_LOG_TYPE_MAIL',    1); /* Use PHP's mail() function */
define('PEAR_LOG_TYPE_DEBUG',   2); /* Use PHP's debugging connection */
define('PEAR_LOG_TYPE_FILE',    3); /* Append to a file */
define('PEAR_LOG_TYPE_SAPI',    4); /* Use the SAPI logging handler */

/**
 * The Log:: class implements both an abstraction for various logging
 * mechanisms and the Subject end of a Subject-Observer pattern.
 *
 * @author  Chuck Hagenbuch <chuck@horde.org>
 * @author  Jon Parise <jon@php.net>
 * @since   Horde 1.3
 * @package Log
 */
class Log
{
	/**
	 * Indicates whether or not the log can been opened / connected.
	 *
	 * @var boolean
	 * @access protected
	 */
	var $_opened = false;

	/**
	 * Instance-specific unique identification number.
	 *
	 * @var integer
	 * @access protected
	 */
	var $_id = 0;

	/**
	 * The label that uniquely identifies this set of log messages.
	 *
	 * @var string
	 * @access protected
	 */
	var $_ident = '';

	/**
	 * The default priority to use when logging an event.
	 *
	 * @var integer
	 * @access protected
	 */
	var $_priority = PEAR_LOG_INFO;

	/**
	 * The bitmask of allowed log levels.
	 *
	 * @var integer
	 * @access protected
	 */
	var $_mask = PEAR_LOG_ALL;

	/**
	 * Holds all Log_observer objects that wish to be notified of new messages.
	 *
	 * @var array
	 * @access protected
	 */
	var $_listeners = array();

	/**
	 * Starting depth to use when walking a backtrace in search of the
	 * function that invoked the log system.
	 *
	 * @var integer
	 * @access protected
	 */
	var $_backtrace_depth = 0;

	/**
	 * Maps canonical format keys to position arguments for use in building
	 * "line format" strings.
	 *
	 * @var array
	 * @access protected
	 */
	var $_formatMap = array('%{timestamp}'  => '%1$s',
		'%{ident}'      => '%2$s',
		'%{priority}'   => '%3$s',
		'%{message}'    => '%4$s',
		'%{file}'       => '%5$s',
		'%{line}'       => '%6$s',
		'%{function}'   => '%7$s',
		'%{class}'      => '%8$s',
		'%\{'           => '%%{');

	/**
	 * Attempts to return a concrete Log instance of type $handler.
	 *
	 * @param string $handler   The type of concrete Log subclass to return.
	 *                          Attempt to dynamically include the code for
	 *                          this subclass. Currently, valid values are
	 *                          'console', 'syslog', 'sql', 'file', and 'mcal'.
	 *
	 * @param string $name      The name of the actually log file, table, or
	 *                          other specific store to use. Defaults to an
	 *                          empty string, with which the subclass will
	 *                          attempt to do something intelligent.
	 *
	 * @param string $ident     The identity reported to the log system.
	 *
	 * @param array  $conf      A hash containing any additional configuration
	 *                          information that a subclass might need.
	 *
	 * @param int $level        Log messages up to and including this level.
	 *
	 * @return object Log       The newly created concrete Log instance, or
	 *                          null on an error.
	 * @access public
	 * @since Log 1.0
	 */
	public static function factory($handler, $name = '', $ident = '',
								   $conf = array(), $level = PEAR_LOG_DEBUG)
	{
		$handler = strtolower($handler);
		$class = 'Log_' . $handler;
		$classfile = 'Log/' . $handler . '.php';

		/*
		 * Attempt to include our version of the named class, but don't treat
		 * a failure as fatal.  The caller may have already included their own
		 * version of the named class.
		 */
		if (!class_exists($class, false)) {
			include_once $classfile;
		}

		/* If the class exists, return a new instance of it. */
		if (class_exists($class, false)) {
			$obj = new $class($name, $ident, $conf, $level);
			return $obj;
		}

		$null = null;
		return $null;
	}

	/**
	 * Attempts to return a reference to a concrete Log instance of type
	 * $handler, only creating a new instance if no log instance with the same
	 * parameters currently exists.
	 *
	 * You should use this if there are multiple places you might create a
	 * logger, you don't want to create multiple loggers, and you don't want to
	 * check for the existance of one each time. The singleton pattern does all
	 * the checking work for you.
	 *
	 * <b>You MUST call this method with the $var = &Log::singleton() syntax.
	 * Without the ampersand (&) in front of the method name, you will not get
	 * a reference, you will get a copy.</b>
	 *
	 * @param string $handler   The type of concrete Log subclass to return.
	 *                          Attempt to dynamically include the code for
	 *                          this subclass. Currently, valid values are
	 *                          'console', 'syslog', 'sql', 'file', and 'mcal'.
	 *
	 * @param string $name      The name of the actually log file, table, or
	 *                          other specific store to use.  Defaults to an
	 *                          empty string, with which the subclass will
	 *                          attempt to do something intelligent.
	 *
	 * @param string $ident     The identity reported to the log system.
	 *
	 * @param array $conf       A hash containing any additional configuration
	 *                          information that a subclass might need.
	 *
	 * @param int $level        Log messages up to and including this level.
	 *
	 * @return object Log       The newly created concrete Log instance, or
	 *                          null on an error.
	 * @access public
	 * @since Log 1.0
	 */
	public static function singleton($handler, $name = '', $ident = '',
									 $conf = array(), $level = PEAR_LOG_DEBUG)
	{
		static $instances;
		if (!isset($instances)) $instances = array();

		$signature = serialize(array($handler, $name, $ident, $conf, $level));
		if (!isset($instances[$signature])) {
			$instances[$signature] = Log::factory($handler, $name, $ident,
				$conf, $level);
		}

		return $instances[$signature];
	}

	/**
	 * Abstract implementation of the open() method.
	 * @since Log 1.0
	 */
	function open()
	{
		return false;
	}

	/**
	 * Abstract implementation of the close() method.
	 * @since Log 1.0
	 */
	function close()
	{
		return false;
	}

	/**
	 * Abstract implementation of the flush() method.
	 * @since Log 1.8.2
	 */
	function flush()
	{
		return false;
	}

	/**
	 * Abstract implementation of the log() method.
	 * @since Log 1.0
	 */
//	function log($message, $priority = null)
//	{
//		return false;
//	}

	/**
	 * A convenience function for logging a emergency event.  It will log a
	 * message at the PEAR_LOG_EMERG log level.
	 *
	 * @param   mixed   $message    String or object containing the message
	 *                              to log.
	 *
	 * @return  boolean True if the message was successfully logged.
	 *
	 * @access  public
	 * @since   Log 1.7.0
	 */
	function emerg($message)
	{
		return $this->log($message, PEAR_LOG_EMERG);
	}

	/**
	 * A convenience function for logging an alert event.  It will log a
	 * message at the PEAR_LOG_ALERT log level.
	 *
	 * @param   mixed   $message    String or object containing the message
	 *                              to log.
	 *
	 * @return  boolean True if the message was successfully logged.
	 *
	 * @access  public
	 * @since   Log 1.7.0
	 */
	function alert($message)
	{
		return $this->log($message, PEAR_LOG_ALERT);
	}

	/**
	 * A convenience function for logging a critical event.  It will log a
	 * message at the PEAR_LOG_CRIT log level.
	 *
	 * @param   mixed   $message    String or object containing the message
	 *                              to log.
	 *
	 * @return  boolean True if the message was successfully logged.
	 *
	 * @access  public
	 * @since   Log 1.7.0
	 */
	function crit($message)
	{
		return $this->log($message, PEAR_LOG_CRIT);
	}

	/**
	 * A convenience function for logging a error event.  It will log a
	 * message at the PEAR_LOG_ERR log level.
	 *
	 * @param   mixed   $message    String or object containing the message
	 *                              to log.
	 *
	 * @return  boolean True if the message was successfully logged.
	 *
	 * @access  public
	 * @since   Log 1.7.0
	 */
	function err($message)
	{
		return $this->log($message, PEAR_LOG_ERR);
	}

	/**
	 * A convenience function for logging a warning event.  It will log a
	 * message at the PEAR_LOG_WARNING log level.
	 *
	 * @param   mixed   $message    String or object containing the message
	 *                              to log.
	 *
	 * @return  boolean True if the message was successfully logged.
	 *
	 * @access  public
	 * @since   Log 1.7.0
	 */
	function warning($message)
	{
		return $this->log($message, PEAR_LOG_WARNING);
	}

	/**
	 * A convenience function for logging a notice event.  It will log a
	 * message at the PEAR_LOG_NOTICE log level.
	 *
	 * @param   mixed   $message    String or object containing the message
	 *                              to log.
	 *
	 * @return  boolean True if the message was successfully logged.
	 *
	 * @access  public
	 * @since   Log 1.7.0
	 */
	function notice($message)
	{
		return $this->log($message, PEAR_LOG_NOTICE);
	}

	/**
	 * A convenience function for logging a information event.  It will log a
	 * message at the PEAR_LOG_INFO log level.
	 *
	 * @param   mixed   $message    String or object containing the message
	 *                              to log.
	 *
	 * @return  boolean True if the message was successfully logged.
	 *
	 * @access  public
	 * @since   Log 1.7.0
	 */
	function info($message)
	{
		return $this->log($message, PEAR_LOG_INFO);
	}

	/**
	 * A convenience function for logging a debug event.  It will log a
	 * message at the PEAR_LOG_DEBUG log level.
	 *
	 * @param   mixed   $message    String or object containing the message
	 *                              to log.
	 *
	 * @return  boolean True if the message was successfully logged.
	 *
	 * @access  public
	 * @since   Log 1.7.0
	 */
	function debug($message)
	{
		return $this->log($message, PEAR_LOG_DEBUG);
	}

	/**
	 * Returns the string representation of the message data.
	 *
	 * If $message is an object, _extractMessage() will attempt to extract
	 * the message text using a known method (such as a PEAR_Error object's
	 * getMessage() method).  If a known method, cannot be found, the
	 * serialized representation of the object will be returned.
	 *
	 * If the message data is already a string, it will be returned unchanged.
	 *
	 * @param  mixed $message   The original message data.  This may be a
	 *                          string or any object.
	 *
	 * @return string           The string representation of the message.
	 *
	 * @access protected
	 */
	function _extractMessage($message)
	{
		/*
		 * If we've been given an object, attempt to extract the message using
		 * a known method.  If we can't find such a method, default to the
		 * "human-readable" version of the object.
		 *
		 * We also use the human-readable format for arrays.
		 */
		if (is_object($message)) {
			if (method_exists($message, 'getmessage')) {
				$message = $message->getMessage();
			} else if (method_exists($message, 'tostring')) {
				$message = $message->toString();
			} else if (method_exists($message, '__tostring')) {
				$message = (string)$message;
			} else {
				$message = var_export($message, true);
			}
		} else if (is_array($message)) {
			if (isset($message['message'])) {
				if (is_scalar($message['message'])) {
					$message = $message['message'];
				} else {
					$message = var_export($message['message'], true);
				}
			} else {
				$message = var_export($message, true);
			}
		} else if (is_bool($message) || $message === NULL) {
			$message = var_export($message, true);
		}

		/* Otherwise, we assume the message is a string. */
		return $message;
	}

	/**
	 * Using debug_backtrace(), returns the file, line, and enclosing function
	 * name of the source code context from which log() was invoked.
	 *
	 * @param   int     $depth  The initial number of frames we should step
	 *                          back into the trace.
	 *
	 * @return  array   Array containing four strings: the filename, the line,
	 *                  the function name, and the class name from which log()
	 *                  was called.
	 *
	 * @access  private
	 * @since   Log 1.9.4
	 */
	function _getBacktraceVars($depth)
	{
		/* Start by generating a backtrace from the current call (here). */
		$bt = debug_backtrace();

		/* Store some handy shortcuts to our previous frames. */
		$bt0 = isset($bt[$depth]) ? $bt[$depth] : null;
		$bt1 = isset($bt[$depth + 1]) ? $bt[$depth + 1] : null;

		/*
		 * If we were ultimately invoked by the composite handler, we need to
		 * increase our depth one additional level to compensate.
		 */
		$class = isset($bt1['class']) ? $bt1['class'] : null;
		if ($class !== null && strcasecmp($class, 'Log_composite') == 0) {
			$depth++;
			$bt0 = isset($bt[$depth]) ? $bt[$depth] : null;
			$bt1 = isset($bt[$depth + 1]) ? $bt[$depth + 1] : null;
			$class = isset($bt1['class']) ? $bt1['class'] : null;
		}

		/*
		 * We're interested in the frame which invoked the log() function, so
		 * we need to walk back some number of frames into the backtrace.  The
		 * $depth parameter tells us where to start looking.   We go one step
		 * further back to find the name of the encapsulating function from
		 * which log() was called.
		 */
		$file = isset($bt0) ? $bt0['file'] : null;
		$line = isset($bt0) ? $bt0['line'] : 0;
		$func = isset($bt1) ? $bt1['function'] : null;

		/*
		 * However, if log() was called from one of our "shortcut" functions,
		 * we're going to need to go back an additional step.
		 */
		if (in_array($func, array('emerg', 'alert', 'crit', 'err', 'warning',
			'notice', 'info', 'debug'))) {
			$bt2 = isset($bt[$depth + 2]) ? $bt[$depth + 2] : null;

			$file = is_array($bt1) ? $bt1['file'] : null;
			$line = is_array($bt1) ? $bt1['line'] : 0;
			$func = is_array($bt2) ? $bt2['function'] : null;
			$class = isset($bt2['class']) ? $bt2['class'] : null;
		}

		/*
		 * If we couldn't extract a function name (perhaps because we were
		 * executed from the "main" context), provide a default value.
		 */
		if ($func === null) {
			$func = '(none)';
		}

		/* Return a 4-tuple containing (file, line, function, class). */
		return array($file, $line, $func, $class);
	}

	/**
	 * Sets the starting depth to use when walking a backtrace in search of
	 * the function that invoked the log system.  This is used on conjunction
	 * with the 'file', 'line', 'function', and 'class' formatters.
	 *
	 * @param int $depth    The new backtrace depth.
	 *
	 * @access  public
	 * @since   Log 1.12.7
	 */
	public function setBacktraceDepth($depth)
	{
		$this->_backtrace_depth = $depth;
	}

	/**
	 * Produces a formatted log line based on a format string and a set of
	 * variables representing the current log record and state.
	 *
	 * @return  string  Formatted log string.
	 *
	 * @access  protected
	 * @since   Log 1.9.4
	 */
	function _format($format, $timestamp, $priority, $message)
	{
		/*
		 * If the format string references any of the backtrace-driven
		 * variables (%5 %6,%7,%8), generate the backtrace and fetch them.
		 */
		if (preg_match('/%[5678]/', $format)) {
			/* Plus 2 to account for our internal function calls. */
			$d = $this->_backtrace_depth + 2;
			list($file, $line, $func, $class) = $this->_getBacktraceVars($d);
		}

		/*
		 * Build the formatted string.  We use the sprintf() function's
		 * "argument swapping" capability to dynamically select and position
		 * the variables which will ultimately appear in the log string.
		 */
		return sprintf($format,
			$timestamp,
			$this->_ident,
			$this->priorityToString($priority),
			$message,
			isset($file) ? $file : '',
			isset($line) ? $line : '',
			isset($func) ? $func : '',
			isset($class) ? $class : '');
	}

	/**
	 * Returns the string representation of a PEAR_LOG_* integer constant.
	 *
	 * @param int $priority     A PEAR_LOG_* integer constant.
	 *
	 * @return string           The string representation of $level.
	 *
	 * @access  public
	 * @since   Log 1.0
	 */
	function priorityToString($priority)
	{
		$levels = array(
			PEAR_LOG_EMERG   => 'emergency',
			PEAR_LOG_ALERT   => 'alert',
			PEAR_LOG_CRIT    => 'critical',
			PEAR_LOG_ERR     => 'error',
			PEAR_LOG_WARNING => 'warning',
			PEAR_LOG_NOTICE  => 'notice',
			PEAR_LOG_INFO    => 'info',
			PEAR_LOG_DEBUG   => 'debug'
		);

		return $levels[$priority];
	}

	/**
	 * Returns the the PEAR_LOG_* integer constant for the given string
	 * representation of a priority name.  This function performs a
	 * case-insensitive search.
	 *
	 * @param string $name      String containing a priority name.
	 *
	 * @return string           The PEAR_LOG_* integer contstant corresponding
	 *                          the the specified priority name.
	 *
	 * @access  public
	 * @since   Log 1.9.0
	 */
	function stringToPriority($name)
	{
		$levels = array(
			'emergency' => PEAR_LOG_EMERG,
			'alert'     => PEAR_LOG_ALERT,
			'critical'  => PEAR_LOG_CRIT,
			'error'     => PEAR_LOG_ERR,
			'warning'   => PEAR_LOG_WARNING,
			'notice'    => PEAR_LOG_NOTICE,
			'info'      => PEAR_LOG_INFO,
			'debug'     => PEAR_LOG_DEBUG
		);

		return $levels[strtolower($name)];
	}

	/**
	 * Calculate the log mask for the given priority.
	 *
	 * This method may be called statically.
	 *
	 * @param integer   $priority   The priority whose mask will be calculated.
	 *
	 * @return integer  The calculated log mask.
	 *
	 * @access  public
	 * @since   Log 1.7.0
	 */
	public static function MASK($priority)
	{
		return (1 << $priority);
	}

	/**
	 * Calculate the log mask for all priorities up to the given priority.
	 *
	 * This method may be called statically.
	 *
	 * @param integer   $priority   The maximum priority covered by this mask.
	 *
	 * @return integer  The resulting log mask.
	 *
	 * @access  public
	 * @since   Log 1.7.0
	 *
	 * @deprecated deprecated since Log 1.9.4; use Log::MAX() instead
	 */
	public static function UPTO($priority)
	{
		return Log::MAX($priority);
	}

	/**
	 * Calculate the log mask for all priorities greater than or equal to the
	 * given priority.  In other words, $priority will be the lowest priority
	 * matched by the resulting mask.
	 *
	 * This method may be called statically.
	 *
	 * @param integer   $priority   The minimum priority covered by this mask.
	 *
	 * @return integer  The resulting log mask.
	 *
	 * @access  public
	 * @since   Log 1.9.4
	 */
	public static function MIN($priority)
	{
		return PEAR_LOG_ALL ^ ((1 << $priority) - 1);
	}

	/**
	 * Calculate the log mask for all priorities less than or equal to the
	 * given priority.  In other words, $priority will be the highests priority
	 * matched by the resulting mask.
	 *
	 * This method may be called statically.
	 *
	 * @param integer   $priority   The maximum priority covered by this mask.
	 *
	 * @return integer  The resulting log mask.
	 *
	 * @access  public
	 * @since   Log 1.9.4
	 */
	public static function MAX($priority)
	{
		return ((1 << ($priority + 1)) - 1);
	}

	/**
	 * Set and return the level mask for the current Log instance.
	 *
	 * @param integer $mask     A bitwise mask of log levels.
	 *
	 * @return integer          The current level mask.
	 *
	 * @access  public
	 * @since   Log 1.7.0
	 */
	function setMask($mask)
	{
		$this->_mask = $mask;

		return $this->_mask;
	}

	/**
	 * Returns the current level mask.
	 *
	 * @return interger         The current level mask.
	 *
	 * @access  public
	 * @since   Log 1.7.0
	 */
	function getMask()
	{
		return $this->_mask;
	}

	/**
	 * Check if the given priority is included in the current level mask.
	 *
	 * @param integer   $priority   The priority to check.
	 *
	 * @return boolean  True if the given priority is included in the current
	 *                  log mask.
	 *
	 * @access  protected
	 * @since   Log 1.7.0
	 */
	function _isMasked($priority)
	{
		return (Log::MASK($priority) & $this->_mask);
	}

	/**
	 * Returns the current default priority.
	 *
	 * @return integer  The current default priority.
	 *
	 * @access  public
	 * @since   Log 1.8.4
	 */
	function getPriority()
	{
		return $this->_priority;
	}

	/**
	 * Sets the default priority to the specified value.
	 *
	 * @param   integer $priority   The new default priority.
	 *
	 * @access  public
	 * @since   Log 1.8.4
	 */
	function setPriority($priority)
	{
		$this->_priority = $priority;
	}

	/**
	 * Adds a Log_observer instance to the list of observers that are listening
	 * for messages emitted by this Log instance.
	 *
	 * @param object    $observer   The Log_observer instance to attach as a
	 *                              listener.
	 *
	 * @return boolean  True if the observer is successfully attached.
	 *
	 * @access  public
	 * @since   Log 1.0
	 */
	function attach(&$observer)
	{
		if (!is_a($observer, 'Log_observer')) {
			return false;
		}

		$this->_listeners[$observer->_id] = &$observer;

		return true;
	}

	/**
	 * Removes a Log_observer instance from the list of observers.
	 *
	 * @param object    $observer   The Log_observer instance to detach from
	 *                              the list of listeners.
	 *
	 * @return boolean  True if the observer is successfully detached.
	 *
	 * @access  public
	 * @since   Log 1.0
	 */
	function detach($observer)
	{
		if (!is_a($observer, 'Log_observer') ||
			!isset($this->_listeners[$observer->_id])) {
			return false;
		}

		unset($this->_listeners[$observer->_id]);

		return true;
	}

	/**
	 * Informs each registered observer instance that a new message has been
	 * logged.
	 *
	 * @param array     $event      A hash describing the log event.
	 *
	 * @access protected
	 */
	function _announce($event)
	{
		foreach ($this->_listeners as $id => $listener) {
			if ($event['priority'] <= $this->_listeners[$id]->_priority) {
				$this->_listeners[$id]->notify($event);
			}
		}
	}

	/**
	 * Indicates whether this is a composite class.
	 *
	 * @return boolean          True if this is a composite class.
	 *
	 * @access  public
	 * @since   Log 1.0
	 */
	function isComposite()
	{
		return false;
	}

	/**
	 * Sets this Log instance's identification string.
	 *
	 * @param string    $ident      The new identification string.
	 *
	 * @access  public
	 * @since   Log 1.6.3
	 */
	function setIdent($ident)
	{
		$this->_ident = $ident;
	}

	/**
	 * Returns the current identification string.
	 *
	 * @return string   The current Log instance's identification string.
	 *
	 * @access  public
	 * @since   Log 1.6.3
	 */
	function getIdent()
	{
		return $this->_ident;
	}
}
