1: <?php
2: /**
3: * Logging.
4: *
5: * Log messages to text files.
6: *
7: * PHP 5
8: *
9: * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
10: * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
11: *
12: * Licensed under The MIT License
13: * For full copyright and license information, please see the LICENSE.txt
14: * Redistributions of files must retain the above copyright notice.
15: *
16: * @copyright Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
17: * @link http://cakephp.org CakePHP(tm) Project
18: * @package Cake.Log
19: * @since CakePHP(tm) v 0.2.9
20: * @license http://www.opensource.org/licenses/mit-license.php MIT License
21: */
22:
23: App::uses('LogEngineCollection', 'Log');
24:
25: /**
26: * Logs messages to configured Log adapters. One or more adapters
27: * can be configured using CakeLogs's methods. If you don't
28: * configure any adapters, and write to the logs a default
29: * FileLog will be autoconfigured for you.
30: *
31: * ### Configuring Log adapters
32: *
33: * You can configure log adapters in your applications `bootstrap.php` file.
34: * A sample configuration would look like:
35: *
36: * {{{
37: * CakeLog::config('my_log', array('engine' => 'FileLog'));
38: * }}}
39: *
40: * See the documentation on CakeLog::config() for more detail.
41: *
42: * ### Writing to the log
43: *
44: * You write to the logs using CakeLog::write(). See its documentation for more
45: * information.
46: *
47: * ### Logging Levels
48: *
49: * By default CakeLog supports all the log levels defined in
50: * RFC 5424. When logging messages you can either use the named methods,
51: * or the correct constants with `write()`:
52: *
53: * {{{
54: * CakeLog::error('Something horrible happened');
55: * CakeLog::write(LOG_ERR, 'Something horrible happened');
56: * }}}
57: *
58: * If you require custom logging levels, you can use CakeLog::levels() to
59: * append additional logging levels.
60: *
61: * ### Logging scopes
62: *
63: * When logging messages and configuring log adapters, you can specify
64: * 'scopes' that the logger will handle. You can think of scopes as subsystems
65: * in your application that may require different logging setups. For
66: * example in an e-commerce application you may want to handle logged errors
67: * in the cart and ordering subsystems differently than the rest of the
68: * application. By using scopes you can control logging for each part
69: * of your application and still keep standard log levels.
70: *
71: *
72: * See CakeLog::config() and CakeLog::write() for more information
73: * on scopes
74: *
75: * @package Cake.Log
76: */
77: class CakeLog {
78:
79: /**
80: * LogEngineCollection class
81: *
82: * @var LogEngineCollection
83: */
84: protected static $_Collection;
85:
86: /**
87: * Default log levels as detailed in RFC 5424
88: * http://tools.ietf.org/html/rfc5424
89: *
90: * @var array
91: */
92: protected static $_defaultLevels = array(
93: 'emergency' => LOG_EMERG,
94: 'alert' => LOG_ALERT,
95: 'critical' => LOG_CRIT,
96: 'error' => LOG_ERR,
97: 'warning' => LOG_WARNING,
98: 'notice' => LOG_NOTICE,
99: 'info' => LOG_INFO,
100: 'debug' => LOG_DEBUG,
101: );
102:
103: /**
104: * Active log levels for this instance.
105: *
106: * @var array
107: */
108: protected static $_levels;
109:
110: /**
111: * Mapped log levels
112: *
113: * @var array
114: */
115: protected static $_levelMap;
116:
117: /**
118: * initialize ObjectCollection
119: *
120: * @return void
121: */
122: protected static function _init() {
123: self::$_levels = self::defaultLevels();
124: self::$_Collection = new LogEngineCollection();
125: }
126:
127: /**
128: * Configure and add a new logging stream to CakeLog
129: * You can use add loggers from app/Log/Engine use app.loggername, or any
130: * plugin/Log/Engine using plugin.loggername.
131: *
132: * ### Usage:
133: *
134: * {{{
135: * CakeLog::config('second_file', array(
136: * 'engine' => 'FileLog',
137: * 'path' => '/var/logs/my_app/'
138: * ));
139: * }}}
140: *
141: * Will configure a FileLog instance to use the specified path.
142: * All options that are not `engine` are passed onto the logging adapter,
143: * and handled there. Any class can be configured as a logging
144: * adapter as long as it implements the methods in CakeLogInterface.
145: *
146: * ### Logging levels
147: *
148: * When configuring loggers, you can set which levels a logger will handle.
149: * This allows you to disable debug messages in production for example:
150: *
151: * {{{
152: * CakeLog::config('default', array(
153: * 'engine' => 'File',
154: * 'path' => LOGS,
155: * 'levels' => array('error', 'critical', 'alert', 'emergency')
156: * ));
157: * }}}
158: *
159: * The above logger would only log error messages or higher. Any
160: * other log messages would be discarded.
161: *
162: * ### Logging scopes
163: *
164: * When configuring loggers you can define the active scopes the logger
165: * is for. If defined only the listed scopes will be handled by the
166: * logger. If you don't define any scopes an adapter will catch
167: * all scopes that match the handled levels.
168: *
169: * {{{
170: * CakeLog::config('payments', array(
171: * 'engine' => 'File',
172: * 'scopes' => array('payment', 'order')
173: * ));
174: * }}}
175: *
176: * The above logger will only capture log entries made in the
177: * `payment` and `order` scopes. All other scopes including the
178: * undefined scope will be ignored. Its important to remember that
179: * when using scopes you must also define the `types` of log messages
180: * that a logger will handle. Failing to do so will result in the logger
181: * catching all log messages even if the scope is incorrect.
182: *
183: * @param string $key The keyname for this logger, used to remove the
184: * logger later.
185: * @param array $config Array of configuration information for the logger
186: * @return boolean success of configuration.
187: * @throws CakeLogException
188: */
189: public static function config($key, $config) {
190: if (!preg_match('/^[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*/', $key)) {
191: throw new CakeLogException(__d('cake_dev', 'Invalid key name'));
192: }
193: if (empty($config['engine'])) {
194: throw new CakeLogException(__d('cake_dev', 'Missing logger classname'));
195: }
196: if (empty(self::$_Collection)) {
197: self::_init();
198: }
199: self::$_Collection->load($key, $config);
200: return true;
201: }
202:
203: /**
204: * Returns the keynames of the currently active streams
205: *
206: * @return array Array of configured log streams.
207: */
208: public static function configured() {
209: if (empty(self::$_Collection)) {
210: self::_init();
211: }
212: return self::$_Collection->loaded();
213: }
214:
215: /**
216: * Gets/sets log levels
217: *
218: * Call this method without arguments, eg: `CakeLog::levels()` to obtain current
219: * level configuration.
220: *
221: * To append additional level 'user0' and 'user1' to to default log levels:
222: *
223: * {{{
224: * CakeLog::levels(array('user0, 'user1'));
225: * // or
226: * CakeLog::levels(array('user0, 'user1'), true);
227: * }}}
228: *
229: * will result in:
230: *
231: * {{{
232: * array(
233: * 0 => 'emergency',
234: * 1 => 'alert',
235: * ...
236: * 8 => 'user0',
237: * 9 => 'user1',
238: * );
239: * }}}
240: *
241: * To set/replace existing configuration, pass an array with the second argument
242: * set to false.
243: *
244: * {{{
245: * CakeLog::levels(array('user0, 'user1'), false);
246: * }}}
247: *
248: * will result in:
249: *
250: * {{{
251: * array(
252: * 0 => 'user0',
253: * 1 => 'user1',
254: * );
255: * }}}
256: *
257: * @param array $levels array
258: * @param boolean $append true to append, false to replace
259: * @return array Active log levels
260: */
261: public static function levels($levels = array(), $append = true) {
262: if (empty(self::$_Collection)) {
263: self::_init();
264: }
265: if (empty($levels)) {
266: return self::$_levels;
267: }
268: $levels = array_values($levels);
269: if ($append) {
270: self::$_levels = array_merge(self::$_levels, $levels);
271: } else {
272: self::$_levels = $levels;
273: }
274: self::$_levelMap = array_flip(self::$_levels);
275: return self::$_levels;
276: }
277:
278: /**
279: * Reset log levels to the original value
280: *
281: * @return array Default log levels
282: */
283: public static function defaultLevels() {
284: self::$_levelMap = self::$_defaultLevels;
285: self::$_levels = array_flip(self::$_levelMap);
286: return self::$_levels;
287: }
288:
289: /**
290: * Removes a stream from the active streams. Once a stream has been removed
291: * it will no longer have messages sent to it.
292: *
293: * @param string $streamName Key name of a configured stream to remove.
294: * @return void
295: */
296: public static function drop($streamName) {
297: if (empty(self::$_Collection)) {
298: self::_init();
299: }
300: self::$_Collection->unload($streamName);
301: }
302:
303: /**
304: * Checks whether $streamName is enabled
305: *
306: * @param string $streamName to check
307: * @return boolean
308: * @throws CakeLogException
309: */
310: public static function enabled($streamName) {
311: if (empty(self::$_Collection)) {
312: self::_init();
313: }
314: if (!isset(self::$_Collection->{$streamName})) {
315: throw new CakeLogException(__d('cake_dev', 'Stream %s not found', $streamName));
316: }
317: return self::$_Collection->enabled($streamName);
318: }
319:
320: /**
321: * Enable stream. Streams that were previously disabled
322: * can be re-enabled with this method.
323: *
324: * @param string $streamName to enable
325: * @return void
326: * @throws CakeLogException
327: */
328: public static function enable($streamName) {
329: if (empty(self::$_Collection)) {
330: self::_init();
331: }
332: if (!isset(self::$_Collection->{$streamName})) {
333: throw new CakeLogException(__d('cake_dev', 'Stream %s not found', $streamName));
334: }
335: self::$_Collection->enable($streamName);
336: }
337:
338: /**
339: * Disable stream. Disabling a stream will
340: * prevent that log stream from receiving any messages until
341: * its re-enabled.
342: *
343: * @param string $streamName to disable
344: * @return void
345: * @throws CakeLogException
346: */
347: public static function disable($streamName) {
348: if (empty(self::$_Collection)) {
349: self::_init();
350: }
351: if (!isset(self::$_Collection->{$streamName})) {
352: throw new CakeLogException(__d('cake_dev', 'Stream %s not found', $streamName));
353: }
354: self::$_Collection->disable($streamName);
355: }
356:
357: /**
358: * Gets the logging engine from the active streams.
359: *
360: * @see BaseLog
361: * @param string $streamName Key name of a configured stream to get.
362: * @return mixed instance of BaseLog or false if not found
363: */
364: public static function stream($streamName) {
365: if (empty(self::$_Collection)) {
366: self::_init();
367: }
368: if (!empty(self::$_Collection->{$streamName})) {
369: return self::$_Collection->{$streamName};
370: }
371: return false;
372: }
373:
374: /**
375: * Configures the automatic/default stream a FileLog.
376: *
377: * @return void
378: */
379: protected static function _autoConfig() {
380: self::$_Collection->load('default', array(
381: 'engine' => 'FileLog',
382: 'path' => LOGS,
383: ));
384: }
385:
386: /**
387: * Writes the given message and type to all of the configured log adapters.
388: * Configured adapters are passed both the $type and $message variables. $type
389: * is one of the following strings/values.
390: *
391: * ### Types:
392: *
393: * - LOG_EMERG => 'emergency',
394: * - LOG_ALERT => 'alert',
395: * - LOG_CRIT => 'critical',
396: * - `LOG_ERR` => 'error',
397: * - `LOG_WARNING` => 'warning',
398: * - `LOG_NOTICE` => 'notice',
399: * - `LOG_INFO` => 'info',
400: * - `LOG_DEBUG` => 'debug',
401: *
402: * ### Usage:
403: *
404: * Write a message to the 'warning' log:
405: *
406: * `CakeLog::write('warning', 'Stuff is broken here');`
407: *
408: * @param integer|string $type Type of message being written. When value is an integer
409: * or a string matching the recognized levels, then it will
410: * be treated log levels. Otherwise it's treated as scope.
411: * @param string $message Message content to log
412: * @param string|array $scope The scope(s) a log message is being created in.
413: * See CakeLog::config() for more information on logging scopes.
414: * @return boolean Success
415: */
416: public static function write($type, $message, $scope = array()) {
417: if (empty(self::$_Collection)) {
418: self::_init();
419: }
420:
421: if (is_int($type) && isset(self::$_levels[$type])) {
422: $type = self::$_levels[$type];
423: }
424: if (is_string($type) && empty($scope) && !in_array($type, self::$_levels)) {
425: $scope = $type;
426: }
427: $logged = false;
428: foreach (self::$_Collection->enabled() as $streamName) {
429: $logger = self::$_Collection->{$streamName};
430: $types = $scopes = $config = array();
431: if (method_exists($logger, 'config')) {
432: $config = $logger->config();
433: }
434: if (isset($config['types'])) {
435: $types = $config['types'];
436: }
437: if (isset($config['scopes'])) {
438: $scopes = $config['scopes'];
439: }
440: $inScope = (count(array_intersect((array)$scope, $scopes)) > 0);
441: $correctLevel = in_array($type, $types);
442:
443: if (
444: // No config is a catch all (bc mode)
445: (empty($types) && empty($scopes)) ||
446: // BC layer for mixing scope & level
447: (in_array($type, $scopes)) ||
448: // no scopes, but has level
449: (empty($scopes) && $correctLevel) ||
450: // exact scope + level
451: ($correctLevel && $inScope)
452: ) {
453: $logger->write($type, $message);
454: $logged = true;
455: }
456: }
457: if (!$logged) {
458: self::_autoConfig();
459: self::stream('default')->write($type, $message);
460: }
461: return true;
462: }
463:
464: /**
465: * Convenience method to log emergency messages
466: *
467: * @param string $message log message
468: * @param string|array $scope The scope(s) a log message is being created in.
469: * See CakeLog::config() for more information on logging scopes.
470: * @return boolean Success
471: */
472: public static function emergency($message, $scope = array()) {
473: return self::write(self::$_levelMap['emergency'], $message, $scope);
474: }
475:
476: /**
477: * Convenience method to log alert messages
478: *
479: * @param string $message log message
480: * @param string|array $scope The scope(s) a log message is being created in.
481: * See CakeLog::config() for more information on logging scopes.
482: * @return boolean Success
483: */
484: public static function alert($message, $scope = array()) {
485: return self::write(self::$_levelMap['alert'], $message, $scope);
486: }
487:
488: /**
489: * Convenience method to log critical messages
490: *
491: * @param string $message log message
492: * @param string|array $scope The scope(s) a log message is being created in.
493: * See CakeLog::config() for more information on logging scopes.
494: * @return boolean Success
495: */
496: public static function critical($message, $scope = array()) {
497: return self::write(self::$_levelMap['critical'], $message, $scope);
498: }
499:
500: /**
501: * Convenience method to log error messages
502: *
503: * @param string $message log message
504: * @param string|array $scope The scope(s) a log message is being created in.
505: * See CakeLog::config() for more information on logging scopes.
506: * @return boolean Success
507: */
508: public static function error($message, $scope = array()) {
509: return self::write(self::$_levelMap['error'], $message, $scope);
510: }
511:
512: /**
513: * Convenience method to log warning messages
514: *
515: * @param string $message log message
516: * @param string|array $scope The scope(s) a log message is being created in.
517: * See CakeLog::config() for more information on logging scopes.
518: * @return boolean Success
519: */
520: public static function warning($message, $scope = array()) {
521: return self::write(self::$_levelMap['warning'], $message, $scope);
522: }
523:
524: /**
525: * Convenience method to log notice messages
526: *
527: * @param string $message log message
528: * @param string|array $scope The scope(s) a log message is being created in.
529: * See CakeLog::config() for more information on logging scopes.
530: * @return boolean Success
531: */
532: public static function notice($message, $scope = array()) {
533: return self::write(self::$_levelMap['notice'], $message, $scope);
534: }
535:
536: /**
537: * Convenience method to log debug messages
538: *
539: * @param string $message log message
540: * @param string|array $scope The scope(s) a log message is being created in.
541: * See CakeLog::config() for more information on logging scopes.
542: * @return boolean Success
543: */
544: public static function debug($message, $scope = array()) {
545: return self::write(self::$_levelMap['debug'], $message, $scope);
546: }
547:
548: /**
549: * Convenience method to log info messages
550: *
551: * @param string $message log message
552: * @param string|array $scope The scope(s) a log message is being created in.
553: * See CakeLog::config() for more information on logging scopes.
554: * @return boolean Success
555: */
556: public static function info($message, $scope = array()) {
557: return self::write(self::$_levelMap['info'], $message, $scope);
558: }
559:
560: }
561: