source: trunk/workflow/inc/log/Log.php @ 795

Revision 795, 26.0 KB checked in by viani, 15 years ago (diff)

Ticket #488 - Inclusão do módulo workflow no ramo trunk do repositório Expresso.

  • Property svn:executable set to *
Line 
1<?php
2/**
3 * $Header: /repository/pear/Log/Log.php,v 1.74 2008/11/19 04:14:38 jon Exp $
4 * $Horde: horde/lib/Log.php,v 1.15 2000/06/29 23:39:45 jon Exp $
5 *
6 * @version $Revision: 1.74 $
7 * @package Log
8 */
9
10define('PEAR_LOG_EMERG',    0);     /* System is unusable */
11define('PEAR_LOG_ALERT',    1);     /* Immediate action required */
12define('PEAR_LOG_CRIT',     2);     /* Critical conditions */
13define('PEAR_LOG_ERR',      3);     /* Error conditions */
14define('PEAR_LOG_WARNING',  4);     /* Warning conditions */
15define('PEAR_LOG_NOTICE',   5);     /* Normal but significant */
16define('PEAR_LOG_INFO',     6);     /* Informational */
17define('PEAR_LOG_DEBUG',    7);     /* Debug-level messages */
18
19define('PEAR_LOG_ALL',      0xffffffff);    /* All messages */
20define('PEAR_LOG_NONE',     0x00000000);    /* No message */
21
22/* Log types for PHP's native error_log() function. */
23define('PEAR_LOG_TYPE_SYSTEM',  0); /* Use PHP's system logger */
24define('PEAR_LOG_TYPE_MAIL',    1); /* Use PHP's mail() function */
25define('PEAR_LOG_TYPE_DEBUG',   2); /* Use PHP's debugging connection */
26define('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 */
37class Log
38{
39    /**
40     * Indicates whether or not the log can been opened / connected.
41     *
42     * @var boolean
43     * @access protected
44     */
45    var $_opened = false;
46
47    /**
48     * Instance-specific unique identification number.
49     *
50     * @var integer
51     * @access protected
52     */
53    var $_id = 0;
54
55    /**
56     * The label that uniquely identifies this set of log messages.
57     *
58     * @var string
59     * @access protected
60     */
61    var $_ident = '';
62
63    /**
64     * The default priority to use when logging an event.
65     *
66     * @var integer
67     * @access protected
68     */
69    var $_priority = PEAR_LOG_INFO;
70
71    /**
72     * The bitmask of allowed log levels.
73     *
74     * @var integer
75     * @access protected
76     */
77    var $_mask = PEAR_LOG_ALL;
78
79    /**
80     * Holds all Log_observer objects that wish to be notified of new messages.
81     *
82     * @var array
83     * @access protected
84     */
85    var $_listeners = array();
86
87    /**
88     * Maps canonical format keys to position arguments for use in building
89     * "line format" strings.
90     *
91     * @var array
92     * @access protected
93     */
94    var $_formatMap = array('%{timestamp}'  => '%1$s',
95                            '%{ident}'      => '%2$s',
96                            '%{priority}'   => '%3$s',
97                            '%{message}'    => '%4$s',
98                            '%{file}'       => '%5$s',
99                            '%{line}'       => '%6$s',
100                            '%{function}'   => '%7$s',
101                            '%{class}'      => '%8$s',
102                            '%\{'           => '%%{');
103
104    /**
105     * Utility function which wraps PHP's class_exists() function to ensure
106     * consistent behavior between PHP versions 4 and 5.  Autoloading behavior
107     * is always disabled.
108     *
109     * @param string $class     The name of the class whose existence should
110     *                          be tested.
111     *
112     * @return bool             True if the class exists.
113     *
114     * @access private
115     * @since Log 1.9.13
116     */
117    function _classExists($class)
118    {
119        if (version_compare(PHP_VERSION, '5.0.0', 'ge')) {
120            return class_exists($class, false);
121        }
122
123        return class_exists($class);
124    }
125
126    /**
127     * Attempts to return a concrete Log instance of type $handler.
128     *
129     * @param string $handler   The type of concrete Log subclass to return.
130     *                          Attempt to dynamically include the code for
131     *                          this subclass. Currently, valid values are
132     *                          'console', 'syslog', 'sql', 'file', and 'mcal'.
133     *
134     * @param string $name      The name of the actually log file, table, or
135     *                          other specific store to use. Defaults to an
136     *                          empty string, with which the subclass will
137     *                          attempt to do something intelligent.
138     *
139     * @param string $ident     The identity reported to the log system.
140     *
141     * @param array  $conf      A hash containing any additional configuration
142     *                          information that a subclass might need.
143     *
144     * @param int $level        Log messages up to and including this level.
145     *
146     * @return object Log       The newly created concrete Log instance, or
147     *                          null on an error.
148     * @access public
149     * @since Log 1.0
150     */
151    function &factory($handler, $name = '', $ident = '', $conf = array(),
152                      $level = PEAR_LOG_DEBUG)
153    {
154        $handler = strtolower($handler);
155        $class = 'Log_' . $handler;
156        $classfile = 'Log/' . $handler . '.php';
157
158        /*
159         * Attempt to include our version of the named class, but don't treat
160         * a failure as fatal.  The caller may have already included their own
161         * version of the named class.
162         */
163        if (!Log::_classExists($class)) {
164            include_once $classfile;
165        }
166
167        /* If the class exists, return a new instance of it. */
168        if (Log::_classExists($class)) {
169            $obj = &new $class($name, $ident, $conf, $level);
170            return $obj;
171        }
172
173        $null = null;
174        return $null;
175    }
176
177    /**
178     * Attempts to return a reference to a concrete Log instance of type
179     * $handler, only creating a new instance if no log instance with the same
180     * parameters currently exists.
181     *
182     * You should use this if there are multiple places you might create a
183     * logger, you don't want to create multiple loggers, and you don't want to
184     * check for the existance of one each time. The singleton pattern does all
185     * the checking work for you.
186     *
187     * <b>You MUST call this method with the $var = &Log::singleton() syntax.
188     * Without the ampersand (&) in front of the method name, you will not get
189     * a reference, you will get a copy.</b>
190     *
191     * @param string $handler   The type of concrete Log subclass to return.
192     *                          Attempt to dynamically include the code for
193     *                          this subclass. Currently, valid values are
194     *                          'console', 'syslog', 'sql', 'file', and 'mcal'.
195     *
196     * @param string $name      The name of the actually log file, table, or
197     *                          other specific store to use.  Defaults to an
198     *                          empty string, with which the subclass will
199     *                          attempt to do something intelligent.
200     *
201     * @param string $ident     The identity reported to the log system.
202     *
203     * @param array $conf       A hash containing any additional configuration
204     *                          information that a subclass might need.
205     *
206     * @param int $level        Log messages up to and including this level.
207     *
208     * @return object Log       The newly created concrete Log instance, or
209     *                          null on an error.
210     * @access public
211     * @since Log 1.0
212     */
213    function &singleton($handler, $name = '', $ident = '', $conf = array(),
214                        $level = PEAR_LOG_DEBUG)
215    {
216        static $instances;
217        if (!isset($instances)) $instances = array();
218
219        $signature = serialize(array($handler, $name, $ident, $conf, $level));
220        if (!isset($instances[$signature])) {
221            $instances[$signature] = &Log::factory($handler, $name, $ident,
222                                                   $conf, $level);
223        }
224
225        return $instances[$signature];
226    }
227
228    /**
229     * Abstract implementation of the open() method.
230     * @since Log 1.0
231     */
232    function open()
233    {
234        return false;
235    }
236
237    /**
238     * Abstract implementation of the close() method.
239     * @since Log 1.0
240     */
241    function close()
242    {
243        return false;
244    }
245
246    /**
247     * Abstract implementation of the flush() method.
248     * @since Log 1.8.2
249     */
250    function flush()
251    {
252        return false;
253    }
254
255    /**
256     * Abstract implementation of the log() method.
257     * @since Log 1.0
258     */
259    function log($message, $priority = null)
260    {
261        return false;
262    }
263
264    /**
265     * A convenience function for logging a emergency event.  It will log a
266     * message at the PEAR_LOG_EMERG log level.
267     *
268     * @param   mixed   $message    String or object containing the message
269     *                              to log.
270     *
271     * @return  boolean True if the message was successfully logged.
272     *
273     * @access  public
274     * @since   Log 1.7.0
275     */
276    function emerg($message)
277    {
278        return $this->log($message, PEAR_LOG_EMERG);
279    }
280
281    /**
282     * A convenience function for logging an alert event.  It will log a
283     * message at the PEAR_LOG_ALERT log level.
284     *
285     * @param   mixed   $message    String or object containing the message
286     *                              to log.
287     *
288     * @return  boolean True if the message was successfully logged.
289     *
290     * @access  public
291     * @since   Log 1.7.0
292     */
293    function alert($message)
294    {
295        return $this->log($message, PEAR_LOG_ALERT);
296    }
297
298    /**
299     * A convenience function for logging a critical event.  It will log a
300     * message at the PEAR_LOG_CRIT log level.
301     *
302     * @param   mixed   $message    String or object containing the message
303     *                              to log.
304     *
305     * @return  boolean True if the message was successfully logged.
306     *
307     * @access  public
308     * @since   Log 1.7.0
309     */
310    function crit($message)
311    {
312        return $this->log($message, PEAR_LOG_CRIT);
313    }
314
315    /**
316     * A convenience function for logging a error event.  It will log a
317     * message at the PEAR_LOG_ERR log level.
318     *
319     * @param   mixed   $message    String or object containing the message
320     *                              to log.
321     *
322     * @return  boolean True if the message was successfully logged.
323     *
324     * @access  public
325     * @since   Log 1.7.0
326     */
327    function err($message)
328    {
329        return $this->log($message, PEAR_LOG_ERR);
330    }
331
332    /**
333     * A convenience function for logging a warning event.  It will log a
334     * message at the PEAR_LOG_WARNING log level.
335     *
336     * @param   mixed   $message    String or object containing the message
337     *                              to log.
338     *
339     * @return  boolean True if the message was successfully logged.
340     *
341     * @access  public
342     * @since   Log 1.7.0
343     */
344    function warning($message)
345    {
346        return $this->log($message, PEAR_LOG_WARNING);
347    }
348
349    /**
350     * A convenience function for logging a notice event.  It will log a
351     * message at the PEAR_LOG_NOTICE log level.
352     *
353     * @param   mixed   $message    String or object containing the message
354     *                              to log.
355     *
356     * @return  boolean True if the message was successfully logged.
357     *
358     * @access  public
359     * @since   Log 1.7.0
360     */
361    function notice($message)
362    {
363        return $this->log($message, PEAR_LOG_NOTICE);
364    }
365
366    /**
367     * A convenience function for logging a information event.  It will log a
368     * message at the PEAR_LOG_INFO log level.
369     *
370     * @param   mixed   $message    String or object containing the message
371     *                              to log.
372     *
373     * @return  boolean True if the message was successfully logged.
374     *
375     * @access  public
376     * @since   Log 1.7.0
377     */
378    function info($message)
379    {
380        return $this->log($message, PEAR_LOG_INFO);
381    }
382
383    /**
384     * A convenience function for logging a debug event.  It will log a
385     * message at the PEAR_LOG_DEBUG log level.
386     *
387     * @param   mixed   $message    String or object containing the message
388     *                              to log.
389     *
390     * @return  boolean True if the message was successfully logged.
391     *
392     * @access  public
393     * @since   Log 1.7.0
394     */
395    function debug($message)
396    {
397        return $this->log($message, PEAR_LOG_DEBUG);
398    }
399
400    /**
401     * Returns the string representation of the message data.
402     *
403     * If $message is an object, _extractMessage() will attempt to extract
404     * the message text using a known method (such as a PEAR_Error object's
405     * getMessage() method).  If a known method, cannot be found, the
406     * serialized representation of the object will be returned.
407     *
408     * If the message data is already a string, it will be returned unchanged.
409     *
410     * @param  mixed $message   The original message data.  This may be a
411     *                          string or any object.
412     *
413     * @return string           The string representation of the message.
414     *
415     * @access protected
416     */
417    function _extractMessage($message)
418    {
419        /*
420         * If we've been given an object, attempt to extract the message using
421         * a known method.  If we can't find such a method, default to the
422         * "human-readable" version of the object.
423         *
424         * We also use the human-readable format for arrays.
425         */
426        if (is_object($message)) {
427            if (method_exists($message, 'getmessage')) {
428                $message = $message->getMessage();
429            } else if (method_exists($message, 'tostring')) {
430                $message = $message->toString();
431            } else if (method_exists($message, '__tostring')) {
432                if (version_compare(PHP_VERSION, '5.0.0', 'ge')) {
433                    $message = (string)$message;
434                } else {
435                    $message = $message->__toString();
436                }
437            } else {
438                $message = var_export($message, true);
439            }
440        } else if (is_array($message)) {
441            if (isset($message['message'])) {
442                if (is_scalar($message['message'])) {
443                    $message = $message['message'];
444                } else {
445                    $message = var_export($message['message'], true);
446                }
447            } else {
448                $message = var_export($message, true);
449            }
450        } else if (is_bool($message) || $message === NULL) {
451            $message = var_export($message, true);
452        }
453
454        /* Otherwise, we assume the message is a string. */
455        return $message;
456    }
457
458    /**
459     * Using debug_backtrace(), returns the file, line, and enclosing function
460     * name of the source code context from which log() was invoked.
461     *
462     * @param   int     $depth  The initial number of frames we should step
463     *                          back into the trace.
464     *
465     * @return  array   Array containing four strings: the filename, the line,
466     *                  the function name, and the class name from which log()
467     *                  was called.
468     *
469     * @access  private
470     * @since   Log 1.9.4
471     */
472    function _getBacktraceVars($depth)
473    {
474        /* Start by generating a backtrace from the current call (here). */
475        $bt = debug_backtrace();
476
477        /*
478         * If we were ultimately invoked by the composite handler, we need to
479         * increase our depth one additional level to compensate.
480         */
481        $class = isset($bt[$depth+1]['class']) ? $bt[$depth+1]['class'] : null;
482        if ($class !== null && strcasecmp($class, 'Log_composite') == 0) {
483            $depth++;
484            $class = isset($bt[$depth + 1]) ? $bt[$depth + 1]['class'] : null;
485        }
486
487        /*
488         * We're interested in the frame which invoked the log() function, so
489         * we need to walk back some number of frames into the backtrace.  The
490         * $depth parameter tells us where to start looking.   We go one step
491         * further back to find the name of the encapsulating function from
492         * which log() was called.
493         */
494        $file = isset($bt[$depth])     ? $bt[$depth]['file'] : null;
495        $line = isset($bt[$depth])     ? $bt[$depth]['line'] : 0;
496        $func = isset($bt[$depth + 1]) ? $bt[$depth + 1]['function'] : null;
497
498        /*
499         * However, if log() was called from one of our "shortcut" functions,
500         * we're going to need to go back an additional step.
501         */
502        if (in_array($func, array('emerg', 'alert', 'crit', 'err', 'warning',
503                                  'notice', 'info', 'debug'))) {
504            $file = isset($bt[$depth + 1]) ? $bt[$depth + 1]['file'] : null;
505            $line = isset($bt[$depth + 1]) ? $bt[$depth + 1]['line'] : 0;
506            $func = isset($bt[$depth + 2]) ? $bt[$depth + 2]['function'] : null;
507        }
508
509        /*
510         * If we couldn't extract a function name (perhaps because we were
511         * executed from the "main" context), provide a default value.
512         */
513        if (is_null($func)) {
514            $func = '(none)';
515        }
516
517        /* Return a 4-tuple containing (file, line, function, class). */
518        return array($file, $line, $func, $class);
519    }
520
521    /**
522     * Produces a formatted log line based on a format string and a set of
523     * variables representing the current log record and state.
524     *
525     * @return  string  Formatted log string.
526     *
527     * @access  protected
528     * @since   Log 1.9.4
529     */
530    function _format($format, $timestamp, $priority, $message)
531    {
532        /*
533         * If the format string references any of the backtrace-driven
534         * variables (%5 %6,%7,%8), generate the backtrace and fetch them.
535         */
536        if (preg_match('/%[5678]/', $format)) {
537            list($file, $line, $func, $class) = $this->_getBacktraceVars(2);
538        }
539
540        /*
541         * Build the formatted string.  We use the sprintf() function's
542         * "argument swapping" capability to dynamically select and position
543         * the variables which will ultimately appear in the log string.
544         */
545        return sprintf($format,
546                       $timestamp,
547                       $this->_ident,
548                       $this->priorityToString($priority),
549                       $message,
550                       isset($file) ? $file : '',
551                       isset($line) ? $line : '',
552                       isset($func) ? $func : '',
553                       isset($class) ? $class : '');
554    }
555
556    /**
557     * Returns the string representation of a PEAR_LOG_* integer constant.
558     *
559     * @param int $priority     A PEAR_LOG_* integer constant.
560     *
561     * @return string           The string representation of $level.
562     *
563     * @access  public
564     * @since   Log 1.0
565     */
566    function priorityToString($priority)
567    {
568        $levels = array(
569            PEAR_LOG_EMERG   => 'emergency',
570            PEAR_LOG_ALERT   => 'alert',
571            PEAR_LOG_CRIT    => 'critical',
572            PEAR_LOG_ERR     => 'error',
573            PEAR_LOG_WARNING => 'warning',
574            PEAR_LOG_NOTICE  => 'notice',
575            PEAR_LOG_INFO    => 'info',
576            PEAR_LOG_DEBUG   => 'debug'
577        );
578
579        return $levels[$priority];
580    }
581
582    /**
583     * Returns the the PEAR_LOG_* integer constant for the given string
584     * representation of a priority name.  This function performs a
585     * case-insensitive search.
586     *
587     * @param string $name      String containing a priority name.
588     *
589     * @return string           The PEAR_LOG_* integer contstant corresponding
590     *                          the the specified priority name.
591     *
592     * @access  public
593     * @since   Log 1.9.0
594     */
595    function stringToPriority($name)
596    {
597        $levels = array(
598            'emergency' => PEAR_LOG_EMERG,
599            'alert'     => PEAR_LOG_ALERT,
600            'critical'  => PEAR_LOG_CRIT,
601            'error'     => PEAR_LOG_ERR,
602            'warning'   => PEAR_LOG_WARNING,
603            'notice'    => PEAR_LOG_NOTICE,
604            'info'      => PEAR_LOG_INFO,
605            'debug'     => PEAR_LOG_DEBUG
606        );
607
608        return $levels[strtolower($name)];
609    }
610
611    /**
612     * Calculate the log mask for the given priority.
613     *
614     * This method may be called statically.
615     *
616     * @param integer   $priority   The priority whose mask will be calculated.
617     *
618     * @return integer  The calculated log mask.
619     *
620     * @access  public
621     * @since   Log 1.7.0
622     */
623    function MASK($priority)
624    {
625        return (1 << $priority);
626    }
627
628    /**
629     * Calculate the log mask for all priorities up to the given priority.
630     *
631     * This method may be called statically.
632     *
633     * @param integer   $priority   The maximum priority covered by this mask.
634     *
635     * @return integer  The resulting log mask.
636     *
637     * @access  public
638     * @since   Log 1.7.0
639     *
640     * @deprecated deprecated since Log 1.9.4; use Log::MAX() instead
641     */
642    function UPTO($priority)
643    {
644        return Log::MAX($priority);
645    }
646
647    /**
648     * Calculate the log mask for all priorities greater than or equal to the
649     * given priority.  In other words, $priority will be the lowest priority
650     * matched by the resulting mask.
651     *
652     * This method may be called statically.
653     *
654     * @param integer   $priority   The minimum priority covered by this mask.
655     *
656     * @return integer  The resulting log mask.
657     *
658     * @access  public
659     * @since   Log 1.9.4
660     */
661    function MIN($priority)
662    {
663        return PEAR_LOG_ALL ^ ((1 << $priority) - 1);
664    }
665
666    /**
667     * Calculate the log mask for all priorities less than or equal to the
668     * given priority.  In other words, $priority will be the highests priority
669     * matched by the resulting mask.
670     *
671     * This method may be called statically.
672     *
673     * @param integer   $priority   The maximum priority covered by this mask.
674     *
675     * @return integer  The resulting log mask.
676     *
677     * @access  public
678     * @since   Log 1.9.4
679     */
680    function MAX($priority)
681    {
682        return ((1 << ($priority + 1)) - 1);
683    }
684
685    /**
686     * Set and return the level mask for the current Log instance.
687     *
688     * @param integer $mask     A bitwise mask of log levels.
689     *
690     * @return integer          The current level mask.
691     *
692     * @access  public
693     * @since   Log 1.7.0
694     */
695    function setMask($mask)
696    {
697        $this->_mask = $mask;
698
699        return $this->_mask;
700    }
701
702    /**
703     * Returns the current level mask.
704     *
705     * @return interger         The current level mask.
706     *
707     * @access  public
708     * @since   Log 1.7.0
709     */
710    function getMask()
711    {
712        return $this->_mask;
713    }
714
715    /**
716     * Check if the given priority is included in the current level mask.
717     *
718     * @param integer   $priority   The priority to check.
719     *
720     * @return boolean  True if the given priority is included in the current
721     *                  log mask.
722     *
723     * @access  protected
724     * @since   Log 1.7.0
725     */
726    function _isMasked($priority)
727    {
728        return (Log::MASK($priority) & $this->_mask);
729    }
730
731    /**
732     * Returns the current default priority.
733     *
734     * @return integer  The current default priority.
735     *
736     * @access  public
737     * @since   Log 1.8.4
738     */
739    function getPriority()
740    {
741        return $this->_priority;
742    }
743
744    /**
745     * Sets the default priority to the specified value.
746     *
747     * @param   integer $priority   The new default priority.
748     *
749     * @access  public
750     * @since   Log 1.8.4
751     */
752    function setPriority($priority)
753    {
754        $this->_priority = $priority;
755    }
756
757    /**
758     * Adds a Log_observer instance to the list of observers that are listening
759     * for messages emitted by this Log instance.
760     *
761     * @param object    $observer   The Log_observer instance to attach as a
762     *                              listener.
763     *
764     * @param boolean   True if the observer is successfully attached.
765     *
766     * @access  public
767     * @since   Log 1.0
768     */
769    function attach(&$observer)
770    {
771        if (!is_a($observer, 'Log_observer')) {
772            return false;
773        }
774
775        $this->_listeners[$observer->_id] = &$observer;
776
777        return true;
778    }
779
780    /**
781     * Removes a Log_observer instance from the list of observers.
782     *
783     * @param object    $observer   The Log_observer instance to detach from
784     *                              the list of listeners.
785     *
786     * @param boolean   True if the observer is successfully detached.
787     *
788     * @access  public
789     * @since   Log 1.0
790     */
791    function detach($observer)
792    {
793        if (!is_a($observer, 'Log_observer') ||
794            !isset($this->_listeners[$observer->_id])) {
795            return false;
796        }
797
798        unset($this->_listeners[$observer->_id]);
799
800        return true;
801    }
802
803    /**
804     * Informs each registered observer instance that a new message has been
805     * logged.
806     *
807     * @param array     $event      A hash describing the log event.
808     *
809     * @access protected
810     */
811    function _announce($event)
812    {
813        foreach ($this->_listeners as $id => $listener) {
814            if ($event['priority'] <= $this->_listeners[$id]->_priority) {
815                $this->_listeners[$id]->notify($event);
816            }
817        }
818    }
819
820    /**
821     * Indicates whether this is a composite class.
822     *
823     * @return boolean          True if this is a composite class.
824     *
825     * @access  public
826     * @since   Log 1.0
827     */
828    function isComposite()
829    {
830        return false;
831    }
832
833    /**
834     * Sets this Log instance's identification string.
835     *
836     * @param string    $ident      The new identification string.
837     *
838     * @access  public
839     * @since   Log 1.6.3
840     */
841    function setIdent($ident)
842    {
843        $this->_ident = $ident;
844    }
845
846    /**
847     * Returns the current identification string.
848     *
849     * @return string   The current Log instance's identification string.
850     *
851     * @access  public
852     * @since   Log 1.6.3
853     */
854    function getIdent()
855    {
856        return $this->_ident;
857    }
858}
Note: See TracBrowser for help on using the repository browser.