Skip to content
This repository
Browse code

Add documentation.

  • Loading branch information...
commit 7d9f44102017067059320ecdc48d781d72d821cb 1 parent 6bb29ea
Mark Story authored May 15, 2012
150  lib/Cake/Log/CakeLog.php
@@ -22,22 +22,53 @@
22 22
 App::uses('LogEngineCollection', 'Log');
23 23
 
24 24
 /**
25  
- * Logs messages to configured Log adapters.  One or more adapters can be configured
26  
- * using CakeLogs's methods.  If you don't configure any adapters, and write to the logs
27  
- * a default FileLog will be autoconfigured for you.
  25
+ * Logs messages to configured Log adapters.  One or more adapters
  26
+ * can be configured using CakeLogs's methods.  If you don't
  27
+ * configure any adapters, and write to the logs a default
  28
+ * FileLog will be autoconfigured for you.
28 29
  *
29 30
  * ### Configuring Log adapters
30 31
  *
31  
- * You can configure log adapters in your applications `bootstrap.php` file.  A sample configuration
32  
- * would look like:
  32
+ * You can configure log adapters in your applications `bootstrap.php` file.
  33
+ * A sample configuration would look like:
33 34
  *
34  
- * `CakeLog::config('my_log', array('engine' => 'FileLog'));`
  35
+ * {{{
  36
+ * CakeLog::config('my_log', array('engine' => 'FileLog'));
  37
+ * }}}
35 38
  *
36 39
  * See the documentation on CakeLog::config() for more detail.
37 40
  *
38 41
  * ### Writing to the log
39 42
  *
40  
- * You write to the logs using CakeLog::write().  See its documentation for more information.
  43
+ * You write to the logs using CakeLog::write().  See its documentation for more
  44
+ * information.
  45
+ *
  46
+ * ### Logging Levels
  47
+ *
  48
+ * By default CakeLog supports all the log levels defined in
  49
+ * RFC 5424. When logging messages you can either use the named methods,
  50
+ * or the correct constants with `write()`:
  51
+ *
  52
+ * {{{
  53
+ * CakeLog::error('Something horrible happened');
  54
+ * CakeLog::write(LOG_ERR, 'Something horrible happened');
  55
+ * }}}
  56
+ *
  57
+ * If you require custom logging levels, you can use CakeLog::levels() to
  58
+ * append additoinal logging levels.
  59
+ *
  60
+ * ### Logging scopes
  61
+ *
  62
+ * When logging messages and configuring log adapters, you can specify
  63
+ * 'scopes' that the logger will handle.  You can think of scopes as subsystems
  64
+ * in your application that may require different logging setups.  For
  65
+ * example in an e-commerce application you may want to handle logged errors
  66
+ * in the cart and ordering subsystems differently than the rest of the
  67
+ * application.  By using scopes you can control logging for each part
  68
+ * of your application and still keep standard log levels.
  69
+ *
  70
+ * See CakeLog::config() and CakeLog::write() for more information
  71
+ * on scopes
41 72
  *
42 73
  * @package       Cake.Log
43 74
  */
@@ -53,6 +84,8 @@ class CakeLog {
53 84
 /**
54 85
  * Default log levels as detailed in RFC 5424
55 86
  * http://tools.ietf.org/html/rfc5424
  87
+ *
  88
+ * @var array
56 89
  */
57 90
 	protected static $_defaultLevels = array(
58 91
 		LOG_EMERG => 'emergency',
@@ -67,11 +100,15 @@ class CakeLog {
67 100
 
68 101
 /**
69 102
  * Active log levels for this instance.
  103
+ *
  104
+ * @var array
70 105
  */
71 106
 	protected static $_levels;
72 107
 
73 108
 /**
74 109
  * Mapped log levels
  110
+ *
  111
+ * @var array
75 112
  */
76 113
 	protected static $_levelMap;
77 114
 
@@ -87,22 +124,59 @@ protected static function _init() {
87 124
 
88 125
 /**
89 126
  * Configure and add a new logging stream to CakeLog
90  
- * You can use add loggers from app/Log/Engine use app.loggername, or any plugin/Log/Engine using plugin.loggername.
  127
+ * You can use add loggers from app/Log/Engine use app.loggername, or any
  128
+ * plugin/Log/Engine using plugin.loggername.
91 129
  *
92 130
  * ### Usage:
93 131
  *
94 132
  * {{{
95 133
  * CakeLog::config('second_file', array(
96  
- * 		'engine' => 'FileLog',
97  
- * 		'path' => '/var/logs/my_app/'
  134
+ *     'engine' => 'FileLog',
  135
+ *     'path' => '/var/logs/my_app/'
98 136
  * ));
99 137
  * }}}
100 138
  *
101  
- * Will configure a FileLog instance to use the specified path.  All options that are not `engine`
102  
- * are passed onto the logging adapter, and handled there.  Any class can be configured as a logging
  139
+ * Will configure a FileLog instance to use the specified path.
  140
+ * All options that are not `engine` are passed onto the logging adapter,
  141
+ * and handled there.  Any class can be configured as a logging
103 142
  * adapter as long as it implements the methods in CakeLogInterface.
104 143
  *
105  
- * @param string $key The keyname for this logger, used to remove the logger later.
  144
+ * ### Logging levels
  145
+ *
  146
+ * When configuring loggers, you can set which levels a logger will handle.
  147
+ * This allows you to disable debug messages in production for example:
  148
+ *
  149
+ * {{{
  150
+ * CakeLog::config('default', array(
  151
+ *     'engine' => 'File',
  152
+ *     'path' => LOGS,
  153
+ *     'levels' => array('error', 'critical', 'alert', 'emergency')
  154
+ * ));
  155
+ * }}}
  156
+ *
  157
+ * The above logger would only log error messages or higher. Any
  158
+ * other log messages would be discarded.
  159
+ *
  160
+ * ### Logging scopes
  161
+ *
  162
+ * When configuring loggers you can define the active scopes the logger
  163
+ * is for.  If defined only the listed scopes will be handled by the
  164
+ * logger.  If you don't define any scopes an adapter will catch
  165
+ * all scopes that match the handled levels.
  166
+ *
  167
+ * {{{
  168
+ * CakeLog::config('payments', array(
  169
+ *     'engine' => 'File',
  170
+ *     'scopes' => array('payment', 'order')
  171
+ * ));
  172
+ * }}}
  173
+ *
  174
+ * The above logger will only capture log entries made in the
  175
+ * `payment` and `order` scopes. All other scopes including the
  176
+ * undefined scope will be ignored.
  177
+ *
  178
+ * @param string $key The keyname for this logger, used to remove the
  179
+ *    logger later.
106 180
  * @param array $config Array of configuration information for the logger
107 181
  * @return boolean success of configuration.
108 182
  * @throws CakeLogException
@@ -141,11 +215,15 @@ public static function configured() {
141 215
  *
142 216
  * To append additional level 'user0' and 'user1' to to default log levels:
143 217
  *
144  
- *     `CakeLog::levels(array('user0, 'user1'))` or
145  
- *     `CakeLog::levels(array('user0, 'user1'), true)`
  218
+ * {{{
  219
+ * CakeLog::levels(array('user0, 'user1'));
  220
+ * // or
  221
+ * CakeLog::levels(array('user0, 'user1'), true);
  222
+ * }}}
146 223
  *
147 224
  * will result in:
148 225
  *
  226
+ * {{{
149 227
  * array(
150 228
  *     0 => 'emergency',
151 229
  *     1 => 'alert',
@@ -153,17 +231,23 @@ public static function configured() {
153 231
  *     8 => 'user0',
154 232
  *     9 => 'user1',
155 233
  * );
  234
+ * }}}
156 235
  *
157 236
  * To set/replace existing configuration, pass an array with the second argument
158 237
  * set to false.
159 238
  *
160  
- *     `CakeLog::levels(array('user0, 'user1'), false);
  239
+ * {{{
  240
+ * CakeLog::levels(array('user0, 'user1'), false);
  241
+ * }}}
161 242
  *
162 243
  * will result in:
  244
+ *
  245
+ * {{{
163 246
  * array(
164 247
  *      0 => 'user0',
165 248
  *      1 => 'user1',
166 249
  * );
  250
+ * }}}
167 251
  *
168 252
  * @param mixed $levels array
169 253
  * @param bool $append true to append, false to replace
@@ -285,8 +369,9 @@ public static function stream($streamName) {
285 369
  * @return void
286 370
  */
287 371
 	protected static function _autoConfig() {
288  
-		self::$_Collection->load('default', array(
  372
+		self::$_Collection->load('error', array(
289 373
 			'engine' => 'FileLog',
  374
+			'types' => array('warning', 'error', 'critical', 'alert', 'emergency'),
290 375
 			'path' => LOGS,
291 376
 		));
292 377
 	}
@@ -314,10 +399,11 @@ protected static function _autoConfig() {
314 399
  * `CakeLog::write('warning', 'Stuff is broken here');`
315 400
  *
316 401
  * @param mixed $type Type of message being written. When value is an integer
317  
- *                    or a string matching the recognized levels, then it will
318  
- *                    be treated log levels. Otherwise it's treated as scope.
  402
+ *    or a string matching the recognized levels, then it will
  403
+ *    be treated log levels. Otherwise it's treated as scope.
319 404
  * @param string $message Message content to log
320  
- * @param mixed $scope string or array
  405
+ * @param string|array $scope The scope(s) a log messge is being created in.
  406
+ *    See CakeLog::config() for more information on logging scopes.
321 407
  * @return boolean Success
322 408
  */
323 409
 	public static function write($type, $message, $scope = array()) {
@@ -364,7 +450,8 @@ public static function write($type, $message, $scope = array()) {
364 450
  * Convenience method to log emergency messages
365 451
  *
366 452
  * @param string $message log message
367  
- * @param mixed $scope string or array of scopes
  453
+ * @param string|array $scope The scope(s) a log messge is being created in.
  454
+ *    See CakeLog::config() for more information on logging scopes.
368 455
  * @return boolean Success
369 456
  */
370 457
 	public static function emergency($message, $scope = array()) {
@@ -375,7 +462,8 @@ public static function emergency($message, $scope = array()) {
375 462
  * Convenience method to log alert messages
376 463
  *
377 464
  * @param string $message log message
378  
- * @param mixed $scope string or array of scopes
  465
+ * @param string|array $scope The scope(s) a log messge is being created in.
  466
+ *    See CakeLog::config() for more information on logging scopes.
379 467
  * @return boolean Success
380 468
  */
381 469
 	public static function alert($message, $scope = array()) {
@@ -386,7 +474,8 @@ public static function alert($message, $scope = array()) {
386 474
  * Convenience method to log critical messages
387 475
  *
388 476
  * @param string $message log message
389  
- * @param mixed $scope string or array of scopes
  477
+ * @param string|array $scope The scope(s) a log messge is being created in.
  478
+ *    See CakeLog::config() for more information on logging scopes.
390 479
  * @return boolean Success
391 480
  */
392 481
 	public static function critical($message, $scope = array()) {
@@ -397,7 +486,8 @@ public static function critical($message, $scope = array()) {
397 486
  * Convenience method to log error messages
398 487
  *
399 488
  * @param string $message log message
400  
- * @param mixed $scope string or array of scopes
  489
+ * @param string|array $scope The scope(s) a log messge is being created in.
  490
+ *    See CakeLog::config() for more information on logging scopes.
401 491
  * @return boolean Success
402 492
  */
403 493
 	public static function error($message, $scope = array()) {
@@ -408,7 +498,8 @@ public static function error($message, $scope = array()) {
408 498
  * Convenience method to log warning messages
409 499
  *
410 500
  * @param string $message log message
411  
- * @param mixed $scope string or array of scopes
  501
+ * @param string|array $scope The scope(s) a log messge is being created in.
  502
+ *    See CakeLog::config() for more information on logging scopes.
412 503
  * @return boolean Success
413 504
  */
414 505
 	public static function warning($message, $scope = array()) {
@@ -419,7 +510,8 @@ public static function warning($message, $scope = array()) {
419 510
  * Convenience method to log notice messages
420 511
  *
421 512
  * @param string $message log message
422  
- * @param mixed $scope string or array of scopes
  513
+ * @param string|array $scope The scope(s) a log messge is being created in.
  514
+ *    See CakeLog::config() for more information on logging scopes.
423 515
  * @return boolean Success
424 516
  */
425 517
 	public static function notice($message, $scope = array()) {
@@ -430,7 +522,8 @@ public static function notice($message, $scope = array()) {
430 522
  * Convenience method to log debug messages
431 523
  *
432 524
  * @param string $message log message
433  
- * @param mixed $scope string or array of scopes
  525
+ * @param string|array $scope The scope(s) a log messge is being created in.
  526
+ *    See CakeLog::config() for more information on logging scopes.
434 527
  * @return boolean Success
435 528
  */
436 529
 	public static function debug($message, $scope = array()) {
@@ -441,7 +534,8 @@ public static function debug($message, $scope = array()) {
441 534
  * Convenience method to log info messages
442 535
  *
443 536
  * @param string $message log message
444  
- * @param mixed $scope string or array of scopes
  537
+ * @param string|array $scope The scope(s) a log messge is being created in.
  538
+ *    See CakeLog::config() for more information on logging scopes.
445 539
  * @return boolean Success
446 540
  */
447 541
 	public static function info($message, $scope = array()) {
12  lib/Cake/Test/Case/Log/CakeLogTest.php
@@ -201,9 +201,11 @@ public function testLogFileWriting() {
201 201
 	}
202 202
 
203 203
 /**
204  
- * test selective logging
  204
+ * test selective logging by level/type
  205
+ *
  206
+ * @return void
205 207
  */
206  
-	public function testSelectiveLogging() {
  208
+	public function testSelectiveLoggingByLevel() {
207 209
 		if (file_exists(LOGS . 'spam.log')) {
208 210
 			unlink(LOGS . 'spam.log');
209 211
 		}
@@ -245,6 +247,7 @@ public function testSelectiveLogging() {
245 247
 
246 248
 /**
247 249
  * test enable
  250
+ *
248 251
  * @expectedException CakeLogException
249 252
  */
250 253
 	public function testStreamEnable() {
@@ -259,6 +262,7 @@ public function testStreamEnable() {
259 262
 
260 263
 /**
261 264
  * test disable
  265
+ *
262 266
  * @expectedException CakeLogException
263 267
  */
264 268
 	public function testStreamDisable() {
@@ -275,6 +279,7 @@ public function testStreamDisable() {
275 279
 
276 280
 /**
277 281
  * test enabled() invalid stream
  282
+ *
278 283
  * @expectedException CakeLogException
279 284
  */
280 285
 	public function testStreamEnabledInvalid() {
@@ -283,6 +288,7 @@ public function testStreamEnabledInvalid() {
283 288
 
284 289
 /**
285 290
  * test disable invalid stream
  291
+ *
286 292
  * @expectedException CakeLogException
287 293
  */
288 294
 	public function testStreamDisableInvalid() {
@@ -378,6 +384,8 @@ public function testScopedLoggingBC() {
378 384
 
379 385
 /**
380 386
  * test scoped logging
  387
+ *
  388
+ * @return void
381 389
  */
382 390
 	public function testScopedLogging() {
383 391
 		if (file_exists(LOGS . 'shops.log')) {

0 notes on commit 7d9f441

Please sign in to comment.
Something went wrong with that request. Please try again.