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