1 | ================= |
---|
2 | The Log Package |
---|
3 | ================= |
---|
4 | |
---|
5 | -------------------- |
---|
6 | User Documentation |
---|
7 | -------------------- |
---|
8 | |
---|
9 | :Author: Jon Parise |
---|
10 | :Contact: jon@php.net |
---|
11 | :Date: $Date: 2008/11/19 05:12:26 $ |
---|
12 | :Revision: $Revision: 1.41 $ |
---|
13 | |
---|
14 | .. contents:: Contents |
---|
15 | .. section-numbering:: |
---|
16 | |
---|
17 | Using Log Handlers |
---|
18 | ================== |
---|
19 | |
---|
20 | The Log package is implemented as a framework that supports the notion of |
---|
21 | backend-specific log handlers. The base logging object (defined by the `Log |
---|
22 | class`_) is primarily an abstract interface to the currently configured |
---|
23 | handler. |
---|
24 | |
---|
25 | A wide variety of handlers are distributed with the Log package, and, should |
---|
26 | none of them fit your application's needs, it's easy to `write your own`__. |
---|
27 | |
---|
28 | .. _Log class: http://cvs.php.net/viewvc.cgi/pear/Log/Log.php |
---|
29 | __ `Custom Handlers`_ |
---|
30 | |
---|
31 | Creating a Log Object |
---|
32 | --------------------- |
---|
33 | There are three ways to create Log objects: |
---|
34 | |
---|
35 | - Using the ``Log::factory()`` method |
---|
36 | - Using the ``Log::singleton()`` method |
---|
37 | - Direct instantiation |
---|
38 | |
---|
39 | The Factory Method |
---|
40 | ~~~~~~~~~~~~~~~~~~ |
---|
41 | The ``Log::factory()`` method implements the `Factory Pattern`_. It allows |
---|
42 | for the parameterized construction of concrete Log instances at runtime. The |
---|
43 | first parameter to the ``Log::factory()`` method indicates the name of the |
---|
44 | concrete handler to create. The rest of the parameters will be passed on to |
---|
45 | the handler's constructor (see `Configuring a Handler`_ below). |
---|
46 | |
---|
47 | The new ``Log`` instance is returned by reference. |
---|
48 | |
---|
49 | :: |
---|
50 | |
---|
51 | require_once 'Log.php'; |
---|
52 | |
---|
53 | $console = &Log::factory('console', '', 'TEST'); |
---|
54 | $console->log('Logging to the console.'); |
---|
55 | |
---|
56 | $file = &Log::factory('file', 'out.log', 'TEST'); |
---|
57 | $file->log('Logging to out.log.'); |
---|
58 | |
---|
59 | .. _Factory Pattern: http://wikipedia.org/wiki/Factory_method_pattern |
---|
60 | |
---|
61 | The Singleton Method |
---|
62 | ~~~~~~~~~~~~~~~~~~~~ |
---|
63 | The ``Log::singleton()`` method implements the `Singleton Pattern`_. The |
---|
64 | singleton pattern ensures that only a single instance of a given log type and |
---|
65 | configuration is ever created. This has two benefits: first, it prevents |
---|
66 | duplicate ``Log`` instances from being constructed, and, second, it gives all |
---|
67 | of your code access to the same ``Log`` instance. The latter is especially |
---|
68 | important when logging to files because only a single file handler will need |
---|
69 | to be managed. |
---|
70 | |
---|
71 | The ``Log::singleton()`` method's parameters match the ``Log::factory()`` |
---|
72 | method. The new ``Log`` instance is returned by reference. |
---|
73 | |
---|
74 | :: |
---|
75 | |
---|
76 | require_once 'Log.php'; |
---|
77 | |
---|
78 | /* Same construction parameters */ |
---|
79 | $a = &Log::singleton('console', '', 'TEST'); |
---|
80 | $b = &Log::singleton('console', '', 'TEST'); |
---|
81 | |
---|
82 | if ($a === $b) { |
---|
83 | echo '$a and $b point to the same Log instance.' . "\n"; |
---|
84 | } |
---|
85 | |
---|
86 | /* Different construction parameters */ |
---|
87 | $c = &Log::singleton('console', '', 'TEST1'); |
---|
88 | $d = &Log::singleton('console', '', 'TEST2'); |
---|
89 | |
---|
90 | if ($c !== $d) { |
---|
91 | echo '$c and $d point to different Log instances.' . "\n"; |
---|
92 | } |
---|
93 | |
---|
94 | .. _Singleton Pattern: http://wikipedia.org/wiki/Singleton_pattern |
---|
95 | |
---|
96 | Direct Instantiation |
---|
97 | ~~~~~~~~~~~~~~~~~~~~ |
---|
98 | It is also possible to directly instantiate concrete ``Log`` handler |
---|
99 | instances. However, this method is **not recommended** because it creates a |
---|
100 | tighter coupling between your application code and the Log package than is |
---|
101 | necessary. Use of `the factory method`_ or `the singleton method`_ is |
---|
102 | preferred. |
---|
103 | |
---|
104 | |
---|
105 | Configuring a Handler |
---|
106 | --------------------- |
---|
107 | A log handler's configuration is determined by the arguments used in its |
---|
108 | construction. Here's an overview of those parameters:: |
---|
109 | |
---|
110 | /* Using the factory method ... */ |
---|
111 | &Log::factory($handler, $name, $ident, $conf, $maxLevel); |
---|
112 | |
---|
113 | /* Using the singleton method ... */ |
---|
114 | &Log::singleton($handler, $name, $ident, $conf, $maxLevel); |
---|
115 | |
---|
116 | /* Using direct instantiation ... */ |
---|
117 | new Log_handler($name, $ident, $conf, $maxLevel); |
---|
118 | |
---|
119 | +---------------+-----------+-----------------------------------------------+ |
---|
120 | | Parameter | Type | Description | |
---|
121 | +===============+===========+===============================================+ |
---|
122 | | ``$handler`` | String | The type of Log handler to construct. This | |
---|
123 | | | | parameter is only available when `the factory | |
---|
124 | | | | method`_ or `the singleton method`_ are used. | |
---|
125 | +---------------+-----------+-----------------------------------------------+ |
---|
126 | | ``$name`` | String | The name of the log resource to which the | |
---|
127 | | | | events will be logged. The use of this value | |
---|
128 | | | | is determined by the handler's implementation.| |
---|
129 | | | | It defaults to an empty string. | |
---|
130 | +---------------+-----------+-----------------------------------------------+ |
---|
131 | | ``$ident`` | String | An identification string that will be included| |
---|
132 | | | | in all log events logged by this handler. | |
---|
133 | | | | This value defaults to an empty string and can| |
---|
134 | | | | be changed at runtime using the ``setIdent()``| |
---|
135 | | | | method. | |
---|
136 | +---------------+-----------+-----------------------------------------------+ |
---|
137 | | ``$conf`` | Array | Associative array of key-value pairs that are | |
---|
138 | | | | used to specify any handler-specific settings.| |
---|
139 | +---------------+-----------+-----------------------------------------------+ |
---|
140 | | ``$level`` | Integer | Log messages up to and including this level. | |
---|
141 | | | | This value defaults to ``PEAR_LOG_DEBUG``. | |
---|
142 | | | | See `Log Levels`_ and `Log Level Masks`_. | |
---|
143 | +---------------+-----------+-----------------------------------------------+ |
---|
144 | |
---|
145 | |
---|
146 | Logging an Event |
---|
147 | ---------------- |
---|
148 | Events are logged using the ``log()`` method:: |
---|
149 | |
---|
150 | $logger->log('Message', PEAR_LOG_NOTICE); |
---|
151 | |
---|
152 | The first argument contains the log event's message. Even though the event is |
---|
153 | always logged as a string, it is possible to pass an object to the ``log()`` |
---|
154 | method. If the object implements a ``getString()`` method, a ``toString()`` |
---|
155 | method or Zend Engine 2's special ``__toString()`` casting method, it will be |
---|
156 | used to determine the object's string representation. Otherwise, the |
---|
157 | `serialized`_ form of the object will be logged. |
---|
158 | |
---|
159 | The second, optional argument specifies the log event's priority. See the |
---|
160 | `Log Levels`_ table for the complete list of priorities. The default priority |
---|
161 | is PEAR_LOG_INFO. |
---|
162 | |
---|
163 | The ``log()`` method will return ``true`` if the event was successfully |
---|
164 | logged. |
---|
165 | |
---|
166 | "Shortcut" methods are also available for logging an event at a specific log |
---|
167 | level. See the `Log Levels`_ table for the complete list. |
---|
168 | |
---|
169 | .. _serialized: http://www.php.net/serialize |
---|
170 | |
---|
171 | |
---|
172 | Log Levels |
---|
173 | ---------- |
---|
174 | This table is ordered by highest priority (``PEAR_LOG_EMERG``) to lowest |
---|
175 | priority (``PEAR_LOG_DEBUG``). |
---|
176 | |
---|
177 | +-----------------------+---------------+-----------------------------------+ |
---|
178 | | Level | Shortcut | Description | |
---|
179 | +=======================+===============+===================================+ |
---|
180 | | ``PEAR_LOG_EMERG`` | ``emerg()`` | System is unusable | |
---|
181 | +-----------------------+---------------+-----------------------------------+ |
---|
182 | | ``PEAR_LOG_ALERT`` | ``alert()`` | Immediate action required | |
---|
183 | +-----------------------+---------------+-----------------------------------+ |
---|
184 | | ``PEAR_LOG_CRIT`` | ``crit()`` | Critical conditions | |
---|
185 | +-----------------------+---------------+-----------------------------------+ |
---|
186 | | ``PEAR_LOG_ERR`` | ``err()`` | Error conditions | |
---|
187 | +-----------------------+---------------+-----------------------------------+ |
---|
188 | | ``PEAR_LOG_WARNING`` | ``warning()`` | Warning conditions | |
---|
189 | +-----------------------+---------------+-----------------------------------+ |
---|
190 | | ``PEAR_LOG_NOTICE`` | ``notice()`` | Normal but significant | |
---|
191 | +-----------------------+---------------+-----------------------------------+ |
---|
192 | | ``PEAR_LOG_INFO`` | ``info()`` | Informational | |
---|
193 | +-----------------------+---------------+-----------------------------------+ |
---|
194 | | ``PEAR_LOG_DEBUG`` | ``debug()`` | Debug-level messages | |
---|
195 | +-----------------------+---------------+-----------------------------------+ |
---|
196 | |
---|
197 | |
---|
198 | Log Level Masks |
---|
199 | --------------- |
---|
200 | Defining a log level mask allows you to include and/or exclude specific levels |
---|
201 | of events from being logged. The ``$level`` construction parameter (see |
---|
202 | `Configuring a Handler`_) uses this mechanism to exclude log events below a |
---|
203 | certain priority, and it's possible to define more complex masks once the Log |
---|
204 | object has been constructed. |
---|
205 | |
---|
206 | Each priority has a specific mask associated with it. To compute a priority's |
---|
207 | mask, use the static ``Log::MASK()`` method:: |
---|
208 | |
---|
209 | $mask = Log::MASK(PEAR_LOG_INFO); |
---|
210 | |
---|
211 | To compute the mask for all priorities up to, and including, a certain level, |
---|
212 | use the ``Log::MAX()`` static method:: |
---|
213 | |
---|
214 | $mask = Log::MAX(PEAR_LOG_INFO); |
---|
215 | |
---|
216 | To compute the mask for all priorities greater than or equal to a certain |
---|
217 | level, use the ``Log::MIN()`` static method:: |
---|
218 | |
---|
219 | $mask = Log::MIN(PEAR_LOG_INFO); |
---|
220 | |
---|
221 | The apply the mask, use the ``setMask()`` method:: |
---|
222 | |
---|
223 | $logger->setMask($mask); |
---|
224 | |
---|
225 | Masks can be be combined using bitwise operations. To restrict logging to |
---|
226 | only those events marked as ``PEAR_LOG_NOTICE`` or ``PEAR_LOG_DEBUG``:: |
---|
227 | |
---|
228 | $mask = Log::MASK(PEAR_LOG_NOTICE) | Log::MASK(PEAR_LOG_DEBUG); |
---|
229 | $logger->setMask($mask); |
---|
230 | |
---|
231 | For convenience, two special masks are predefined: ``PEAR_LOG_NONE`` and |
---|
232 | ``PEAR_LOG_ALL``. ``PEAR_LOG_ALL`` is especially useful for excluding only |
---|
233 | specific priorities:: |
---|
234 | |
---|
235 | $mask = PEAR_LOG_ALL ^ Log::MASK(PEAR_LOG_NOTICE); |
---|
236 | $logger->setMask($mask); |
---|
237 | |
---|
238 | It is also possible to retrieve and modify a Log object's existing mask:: |
---|
239 | |
---|
240 | $mask = $logger->getMask() | Log::MASK(PEAR_LOG_INFO); |
---|
241 | $logger->setMask($mask); |
---|
242 | |
---|
243 | |
---|
244 | Log Line Format |
---|
245 | --------------- |
---|
246 | Most log handlers support configurable line formats. The following is a list |
---|
247 | of special tokens that will be expanded at runtime with contextual information |
---|
248 | related to the log event. Each token has an alternate shorthand notation, as |
---|
249 | well. |
---|
250 | |
---|
251 | +------------------+-----------+--------------------------------------------+ |
---|
252 | | Token | Alternate | Description | |
---|
253 | +==================+===========+============================================+ |
---|
254 | | ``%{timestamp}`` | ``%1$s`` | Timestamp. This is often configurable. | |
---|
255 | +------------------+-----------+--------------------------------------------+ |
---|
256 | | ``%{ident}`` | ``%2$s`` | The log handler's identification string. | |
---|
257 | +------------------+-----------+--------------------------------------------+ |
---|
258 | | ``%{priority}`` | ``%3$s`` | The log event's priority. | |
---|
259 | +------------------+-----------+--------------------------------------------+ |
---|
260 | | ``%{message}`` | ``%4$s`` | The log event's message text. | |
---|
261 | +------------------+-----------+--------------------------------------------+ |
---|
262 | | ``%{file}`` | ``%5$s`` | The full filename of the logging file. | |
---|
263 | +------------------+-----------+--------------------------------------------+ |
---|
264 | | ``%{line}`` | ``%6$s`` | The line number on which the event occured.| |
---|
265 | +------------------+-----------+--------------------------------------------+ |
---|
266 | | ``%{function}`` | ``%7$s`` | The function from which the event occurred.| |
---|
267 | +------------------+-----------+--------------------------------------------+ |
---|
268 | | ``%{class}`` | ``%8$s`` | The class in which the event occurred. | |
---|
269 | +------------------+-----------+--------------------------------------------+ |
---|
270 | |
---|
271 | |
---|
272 | Flushing Log Events |
---|
273 | ------------------- |
---|
274 | Some log handlers (such as `the console handler`_) support explicit |
---|
275 | "buffering". When buffering is enabled, log events won't actually be written |
---|
276 | to the output stream until the handler is closed. Other handlers (such as |
---|
277 | `the file handler`_) support implicit buffering because they use the operating |
---|
278 | system's IO routines, which may buffer the output. |
---|
279 | |
---|
280 | It's possible to force these handlers to flush their output, however, by |
---|
281 | calling their ``flush()`` method:: |
---|
282 | |
---|
283 | $conf = array('buffering' => true); |
---|
284 | $logger = &Log::singleton('console', '', 'test', $conf); |
---|
285 | |
---|
286 | for ($i = 0; $i < 10; $i++) { |
---|
287 | $logger->log('This event will be buffered.'); |
---|
288 | } |
---|
289 | |
---|
290 | /* Flush all of the buffered log events. */ |
---|
291 | $logger->flush(); |
---|
292 | |
---|
293 | for ($i = 0; $i < 10; $i++) { |
---|
294 | $logger->log('This event will be buffered.'); |
---|
295 | } |
---|
296 | |
---|
297 | /* Implicitly flush the buffered events on close. */ |
---|
298 | $logger->close(); |
---|
299 | |
---|
300 | At this time, the ``flush()`` method is only implemented by `the console |
---|
301 | handler`_, `the file handler`_, `the Firebug handler`_, and `the mail |
---|
302 | handler`_. |
---|
303 | |
---|
304 | |
---|
305 | Standard Log Handlers |
---|
306 | ===================== |
---|
307 | |
---|
308 | The Console Handler |
---|
309 | ------------------- |
---|
310 | The Console handler outputs log events directly to the console. It supports |
---|
311 | output buffering and configurable string formats. |
---|
312 | |
---|
313 | Configuration |
---|
314 | ~~~~~~~~~~~~~ |
---|
315 | +-------------------+-----------+---------------+---------------------------+ |
---|
316 | | Parameter | Type | Default | Description | |
---|
317 | +===================+===========+===============+===========================+ |
---|
318 | | ``stream`` | File | STDOUT_ | The output stream to use. | |
---|
319 | +-------------------+-----------+---------------+---------------------------+ |
---|
320 | | ``buffering`` | Boolean | False | Should the output be | |
---|
321 | | | | | buffered until shutdown? | |
---|
322 | +-------------------+-----------+---------------+---------------------------+ |
---|
323 | | ``lineFormat`` | String | ``%1$s %2$s | `Log line format`_ | |
---|
324 | | | | [%3$s] %4$s`` | specification. | |
---|
325 | +-------------------+-----------+---------------+---------------------------+ |
---|
326 | | ``timeFormat`` | String | ``%b %d | Time stamp format | |
---|
327 | | | | %H:%M:%S`` | (for strftime_). | |
---|
328 | +-------------------+-----------+---------------+---------------------------+ |
---|
329 | |
---|
330 | .. _STDOUT: http://www.php.net/wrappers.php |
---|
331 | .. _strftime: http://www.php.net/strftime |
---|
332 | |
---|
333 | Example |
---|
334 | ~~~~~~~ |
---|
335 | :: |
---|
336 | |
---|
337 | $logger = &Log::singleton('console', '', 'ident'); |
---|
338 | for ($i = 0; $i < 10; $i++) { |
---|
339 | $logger->log("Log entry $i"); |
---|
340 | } |
---|
341 | |
---|
342 | |
---|
343 | The Display Handler |
---|
344 | ------------------- |
---|
345 | The Display handler simply prints the log events back to the browser. It |
---|
346 | respects the ``error_prepend_string`` and ``error_append_string`` `error |
---|
347 | handling values`_ and is useful when `logging from standard error handlers`_. |
---|
348 | |
---|
349 | Configuration |
---|
350 | ~~~~~~~~~~~~~ |
---|
351 | +-------------------+-----------+---------------+---------------------------+ |
---|
352 | | Parameter | Type | Default | Description | |
---|
353 | +===================+===========+===============+===========================+ |
---|
354 | | ``lineFormat`` | String | ``<b>%3$s</b>:| `Log line format`_ | |
---|
355 | | | | %4$s`` | specification. | |
---|
356 | +-------------------+-----------+---------------+---------------------------+ |
---|
357 | | ``timeFormat`` | String | ``%b %d | Time stamp format | |
---|
358 | | | | %H:%M:%S`` | (for strftime_). | |
---|
359 | +-------------------+-----------+---------------+---------------------------+ |
---|
360 | | ``error_prepend`` | String | PHP INI value | This string will be | |
---|
361 | | | | | prepended to the line | |
---|
362 | | | | | format. | |
---|
363 | +-------------------+-----------+---------------+---------------------------+ |
---|
364 | | ``error_append`` | String | PHP INI value | This string will be | |
---|
365 | | | | | appended to the line | |
---|
366 | | | | | format. | |
---|
367 | +-------------------+-----------+---------------+---------------------------+ |
---|
368 | | ``linebreak`` | String | ``<br />\n`` | This string is used to | |
---|
369 | | | | | represent a line break. | |
---|
370 | +-------------------+-----------+---------------+---------------------------+ |
---|
371 | |
---|
372 | .. _error handling values: http://www.php.net/errorfunc |
---|
373 | |
---|
374 | Example |
---|
375 | ~~~~~~~ |
---|
376 | :: |
---|
377 | |
---|
378 | $conf = array('error_prepend' => '<font color="#ff0000"><tt>', |
---|
379 | 'error_append' => '</tt></font>'); |
---|
380 | $logger = &Log::singleton('display', '', '', $conf, PEAR_LOG_DEBUG); |
---|
381 | for ($i = 0; $i < 10; $i++) { |
---|
382 | $logger->log("Log entry $i"); |
---|
383 | } |
---|
384 | |
---|
385 | |
---|
386 | The Error_Log Handler |
---|
387 | --------------------- |
---|
388 | The Error_Log handler sends log events to PHP's `error_log()`_ function. |
---|
389 | |
---|
390 | Configuration |
---|
391 | ~~~~~~~~~~~~~ |
---|
392 | +-------------------+-----------+---------------+---------------------------+ |
---|
393 | | Parameter | Type | Default | Description | |
---|
394 | +===================+===========+===============+===========================+ |
---|
395 | | ``destination`` | String | '' `(empty)` | Optional destination value| |
---|
396 | | | | | for `error_log()`_. See | |
---|
397 | | | | | `Error_Log Types`_ for | |
---|
398 | | | | | more details. | |
---|
399 | +-------------------+-----------+---------------+---------------------------+ |
---|
400 | | ``extra_headers`` | String | '' `(empty)` | Additional headers to pass| |
---|
401 | | | | | to the `mail()`_ function | |
---|
402 | | | | | when the | |
---|
403 | | | | | ``PEAR_LOG_TYPE_MAIL`` | |
---|
404 | | | | | type is specified. | |
---|
405 | +-------------------+-----------+---------------+---------------------------+ |
---|
406 | | ``lineFormat`` | String | ``%2$s: %4$s``| `Log line format`_ | |
---|
407 | | | | | specification. | |
---|
408 | +-------------------+-----------+---------------+---------------------------+ |
---|
409 | | ``timeFormat`` | String | ``%b %d | Time stamp format | |
---|
410 | | | | %H:%M:%S`` | (for strftime_). | |
---|
411 | +-------------------+-----------+---------------+---------------------------+ |
---|
412 | |
---|
413 | Error_Log Types |
---|
414 | ~~~~~~~~~~~~~~~ |
---|
415 | All of the available log types are detailed in the `error_log()`_ section of |
---|
416 | the PHP manual. For your convenience, the Log package also defines the |
---|
417 | following constants that can be used for the ``$name`` handler construction |
---|
418 | parameter. |
---|
419 | |
---|
420 | +---------------------------+-----------------------------------------------+ |
---|
421 | | Constant | Description | |
---|
422 | +===========================+===============================================+ |
---|
423 | | ``PEAR_LOG_TYPE_SYSTEM`` | Log events are sent to PHP's system logger, | |
---|
424 | | | which uses the operating system's logging | |
---|
425 | | | mechanism or a file (depending on the value | |
---|
426 | | | of the `error_log configuration directive`_). | |
---|
427 | +---------------------------+-----------------------------------------------+ |
---|
428 | | ``PEAR_LOG_TYPE_MAIL`` | Log events are sent via email to the address | |
---|
429 | | | specified in the ``destination`` value. | |
---|
430 | +---------------------------+-----------------------------------------------+ |
---|
431 | | ``PEAR_LOG_TYPE_DEBUG`` | Log events are sent through PHP's debugging | |
---|
432 | | | connection. This will only work if | |
---|
433 | | | `remote debugging`_ has been enabled. The | |
---|
434 | | | ``destination`` value is used to specify the | |
---|
435 | | | host name or IP address of the target socket. | |
---|
436 | +---------------------------+-----------------------------------------------+ |
---|
437 | | ``PEAR_LOG_TYPE_FILE`` | Log events will be appended to the file named | |
---|
438 | | | by the ``destination`` value. | |
---|
439 | +---------------------------+-----------------------------------------------+ |
---|
440 | |
---|
441 | .. _error_log(): http://www.php.net/error_log |
---|
442 | .. _mail(): http://www.php.net/mail |
---|
443 | .. _error_log configuration directive: http://www.php.net/errorfunc#ini.error-log |
---|
444 | .. _remote debugging: http://www.php.net/install.configure#install.configure.enable-debugger |
---|
445 | |
---|
446 | Example |
---|
447 | ~~~~~~~ |
---|
448 | :: |
---|
449 | |
---|
450 | $logger = &Log::singleton('error_log', PEAR_LOG_TYPE_SYSTEM, 'ident'); |
---|
451 | for ($i = 0; $i < 10; $i++) { |
---|
452 | $logger->log("Log entry $i"); |
---|
453 | } |
---|
454 | |
---|
455 | |
---|
456 | The File Handler |
---|
457 | ---------------- |
---|
458 | The File handler writes log events to a text file using configurable string |
---|
459 | formats. |
---|
460 | |
---|
461 | Configuration |
---|
462 | ~~~~~~~~~~~~~ |
---|
463 | +-------------------+-----------+---------------+---------------------------+ |
---|
464 | | Parameter | Type | Default | Description | |
---|
465 | +===================+===========+===============+===========================+ |
---|
466 | | ``append`` | Boolean | True | Should new log entries be | |
---|
467 | | | | | append to an existing log | |
---|
468 | | | | | file, or should the a new | |
---|
469 | | | | | log file overwrite an | |
---|
470 | | | | | existing one? | |
---|
471 | +-------------------+-----------+---------------+---------------------------+ |
---|
472 | | ``locking`` | Boolean | False | Should advisory file | |
---|
473 | | | | | locking (using flock_) be | |
---|
474 | | | | | used? | |
---|
475 | +-------------------+-----------+---------------+---------------------------+ |
---|
476 | | ``mode`` | Integer | 0644 | Octal representation of | |
---|
477 | | | | | the log file's permissions| |
---|
478 | | | | | mode. | |
---|
479 | +-------------------+-----------+---------------+---------------------------+ |
---|
480 | | ``dirmode`` | Integer | 0755 | Octal representation of | |
---|
481 | | | | | the file permission mode | |
---|
482 | | | | | that will be used when | |
---|
483 | | | | | creating directories that | |
---|
484 | | | | | do not already exist. | |
---|
485 | +-------------------+-----------+---------------+---------------------------+ |
---|
486 | | ``eol`` | String | OS default | The end-on-line character | |
---|
487 | | | | | sequence. | |
---|
488 | +-------------------+-----------+---------------+---------------------------+ |
---|
489 | | ``lineFormat`` | String | ``%1$s %2$s | `Log line format`_ | |
---|
490 | | | | [%3$s] %4$s`` | specification. | |
---|
491 | +-------------------+-----------+---------------+---------------------------+ |
---|
492 | | ``timeFormat`` | String | ``%b %d | Time stamp format | |
---|
493 | | | | %H:%M:%S`` | (for strftime_). | |
---|
494 | +-------------------+-----------+---------------+---------------------------+ |
---|
495 | |
---|
496 | .. _flock: http://www.php.net/flock |
---|
497 | .. _strftime: http://www.php.net/strftime |
---|
498 | |
---|
499 | The file handler will only attempt to set the ``mode`` value if it was |
---|
500 | responsible for creating the file. |
---|
501 | |
---|
502 | Example |
---|
503 | ~~~~~~~ |
---|
504 | :: |
---|
505 | |
---|
506 | $conf = array('mode' => 0600, 'timeFormat' => '%X %x'); |
---|
507 | $logger = &Log::singleton('file', 'out.log', 'ident', $conf); |
---|
508 | for ($i = 0; $i < 10; $i++) { |
---|
509 | $logger->log("Log entry $i"); |
---|
510 | } |
---|
511 | |
---|
512 | |
---|
513 | The Firebug Handler |
---|
514 | ------------------- |
---|
515 | The Firebug handler outputs log events to the Firebug_ console. It supports |
---|
516 | output buffering and configurable string formats. |
---|
517 | |
---|
518 | Configuration |
---|
519 | ~~~~~~~~~~~~~ |
---|
520 | +-------------------+-----------+---------------+---------------------------+ |
---|
521 | | Parameter | Type | Default | Description | |
---|
522 | +===================+===========+===============+===========================+ |
---|
523 | | ``buffering`` | Boolean | False | Should the output be | |
---|
524 | | | | | buffered until shutdown? | |
---|
525 | +-------------------+-----------+---------------+---------------------------+ |
---|
526 | | ``lineFormat`` | String | ``%2$s [%3$s] | `Log line format`_ | |
---|
527 | | | | %4$s`` | specification. | |
---|
528 | +-------------------+-----------+---------------+---------------------------+ |
---|
529 | | ``timeFormat`` | String | ``%b %d | Time stamp format | |
---|
530 | | | | %H:%M:%S`` | (for strftime_). | |
---|
531 | +-------------------+-----------+---------------+---------------------------+ |
---|
532 | |
---|
533 | .. _Firebug: http://www.getfirebug.com/ |
---|
534 | .. _strftime: http://www.php.net/strftime |
---|
535 | |
---|
536 | Example |
---|
537 | ~~~~~~~ |
---|
538 | :: |
---|
539 | |
---|
540 | $logger = &Log::singleton('firebug', '', 'ident'); |
---|
541 | for ($i = 0; $i < 10; $i++) { |
---|
542 | $logger->log("Log entry $i"); |
---|
543 | } |
---|
544 | |
---|
545 | |
---|
546 | The Mail Handler |
---|
547 | ---------------- |
---|
548 | |
---|
549 | The Mail handler aggregates a session's log events and sends them in the body |
---|
550 | of an email message using either the `PEAR Mail`_ package or PHP's native |
---|
551 | `mail()`_ function. |
---|
552 | |
---|
553 | If an empty ``mailBackend`` value is specified, the `mail()`_ function will be |
---|
554 | used instead of the `PEAR Mail`_ package. |
---|
555 | |
---|
556 | Multiple recipients can be specified by separating their email addresses with |
---|
557 | commas in the ``$name`` construction parameter. |
---|
558 | |
---|
559 | Configuration |
---|
560 | ~~~~~~~~~~~~~ |
---|
561 | +-------------------+-----------+---------------+---------------------------+ |
---|
562 | | Parameter | Type | Default | Description | |
---|
563 | +===================+===========+===============+===========================+ |
---|
564 | | ``from`` | String | sendmail_from | Value for the message's | |
---|
565 | | | | INI value | ``From:`` header. | |
---|
566 | +-------------------+-----------+---------------+---------------------------+ |
---|
567 | | ``subject`` | String | ``[Log_mail] | Value for the message's | |
---|
568 | | | | Log message`` | ``Subject:`` header. | |
---|
569 | +-------------------+-----------+---------------+---------------------------+ |
---|
570 | | ``preamble`` | String | `` `(empty)` | Preamble for the message. | |
---|
571 | +-------------------+-----------+---------------+---------------------------+ |
---|
572 | | ``lineFormat`` | String | ``%1$s %2$s | `Log line format`_ | |
---|
573 | | | | [%3$s] %4$s`` | specification. | |
---|
574 | +-------------------+-----------+---------------+---------------------------+ |
---|
575 | | ``timeFormat`` | String | ``%b %d | Time stamp format | |
---|
576 | | | | %H:%M:%S`` | (for strftime_). | |
---|
577 | +-------------------+-----------+---------------+---------------------------+ |
---|
578 | | ``mailBackend`` | String | `` `(empty)` | Name of the Mail package | |
---|
579 | | | | | backend to use. | |
---|
580 | +-------------------+-----------+---------------+---------------------------+ |
---|
581 | | ``mailParams`` | Array | `(empty)` | Array of parameters that | |
---|
582 | | | | | will be passed to the | |
---|
583 | | | | | Mail package backend. | |
---|
584 | +-------------------+-----------+---------------+---------------------------+ |
---|
585 | |
---|
586 | .. _PEAR Mail: http://pear.php.net/package/Mail |
---|
587 | .. _mail(): http://www.php.net/mail |
---|
588 | |
---|
589 | Example |
---|
590 | ~~~~~~~ |
---|
591 | :: |
---|
592 | |
---|
593 | $conf = array('subject' => 'Important Log Events'); |
---|
594 | $logger = &Log::singleton('mail', 'webmaster@example.com', 'ident', $conf); |
---|
595 | for ($i = 0; $i < 10; $i++) { |
---|
596 | $logger->log("Log entry $i"); |
---|
597 | } |
---|
598 | |
---|
599 | |
---|
600 | The MDB2 Handler |
---|
601 | ---------------- |
---|
602 | The MDB2 handler is similar to `the SQL (DB) handler`_, but instead of using |
---|
603 | the PEAR DB package, it uses the `MDB2 database abstraction package`_. |
---|
604 | |
---|
605 | Configuration |
---|
606 | ~~~~~~~~~~~~~ |
---|
607 | +-------------------+-----------+---------------+---------------------------+ |
---|
608 | | Parameter | Type | Default | Description | |
---|
609 | +===================+===========+===============+===========================+ |
---|
610 | | ``dsn`` | Mixed | '' `(empty)` | A `Data Source Name`_. | |
---|
611 | | | | | |required| | |
---|
612 | +-------------------+-----------+---------------+---------------------------+ |
---|
613 | | ``options`` | Array | ``persistent``| An array of `MDB2`_ | |
---|
614 | | | | | options. | |
---|
615 | +-------------------+-----------+---------------+---------------------------+ |
---|
616 | | ``db`` | Object | NULL | An existing `MDB2`_ | |
---|
617 | | | | | object. If specified, | |
---|
618 | | | | | this object will be used, | |
---|
619 | | | | | and ``dsn`` will be | |
---|
620 | | | | | ignored. | |
---|
621 | +-------------------+-----------+---------------+---------------------------+ |
---|
622 | | ``sequence`` | String | ``log_id`` | The name of the sequence | |
---|
623 | | | | | to use when generating | |
---|
624 | | | | | unique event IDs. Under | |
---|
625 | | | | | many databases, this will | |
---|
626 | | | | | be used as the name of | |
---|
627 | | | | | the sequence table. | |
---|
628 | +-------------------+-----------+---------------+---------------------------+ |
---|
629 | | ``identLimit`` | Integer | 16 | The maximum length of the | |
---|
630 | | | | | ``ident`` string. | |
---|
631 | | | | | **Changing this value may | |
---|
632 | | | | | require updates to the SQL| |
---|
633 | | | | | schema, as well.** | |
---|
634 | +-------------------+-----------+---------------+---------------------------+ |
---|
635 | | ``singleton`` | Boolean | false | Is true, use a singleton | |
---|
636 | | | | | database object using | |
---|
637 | | | | | `MDB2::singleton()`_. | |
---|
638 | +-------------------+-----------+---------------+---------------------------+ |
---|
639 | |
---|
640 | .. _MDB2: http://pear.php.net/package/MDB2 |
---|
641 | .. _MDB2 database abstraction package: MDB2_ |
---|
642 | .. _MDB2::singleton(): http://pear.php.net/package/MDB2/docs/latest/MDB2/MDB2.html#methodsingleton |
---|
643 | |
---|
644 | The Null Handler |
---|
645 | ---------------- |
---|
646 | The Null handler simply consumes log events (akin to sending them to |
---|
647 | ``/dev/null``). `Log level masks`_ are respected, and the event will still be |
---|
648 | sent to any registered `log observers`_. |
---|
649 | |
---|
650 | Example |
---|
651 | ~~~~~~~ |
---|
652 | :: |
---|
653 | |
---|
654 | $logger = &Log::singleton('null'); |
---|
655 | for ($i = 0; $i < 10; $i++) { |
---|
656 | $logger->log("Log entry $i"); |
---|
657 | } |
---|
658 | |
---|
659 | |
---|
660 | The SQL (DB) Handler |
---|
661 | -------------------- |
---|
662 | |
---|
663 | The SQL handler sends log events to a database using `PEAR's DB abstraction |
---|
664 | layer`_. |
---|
665 | |
---|
666 | **Note:** Due to the constraints of the default database schema, the SQL |
---|
667 | handler limits the length of the ``$ident`` string to sixteen (16) characters. |
---|
668 | This limit can be adjusted using the ``identLimit`` configuration parameter. |
---|
669 | |
---|
670 | The Log Table |
---|
671 | ~~~~~~~~~~~~~ |
---|
672 | The default SQL table used by this handler looks like this:: |
---|
673 | |
---|
674 | CREATE TABLE log_table ( |
---|
675 | id INT NOT NULL, |
---|
676 | logtime TIMESTAMP NOT NULL, |
---|
677 | ident CHAR(16) NOT NULL, |
---|
678 | priority INT NOT NULL, |
---|
679 | message VARCHAR(200), |
---|
680 | PRIMARY KEY (id) |
---|
681 | ); |
---|
682 | |
---|
683 | This is the "lowest common denominator" that should work across all SQL |
---|
684 | compliant database. You may want to make database- or site-specific changes |
---|
685 | to this schema to support your specific needs, however. For example, |
---|
686 | `PostgreSQL`_ users may prefer to use a ``TEXT`` type for the ``message`` |
---|
687 | field. |
---|
688 | |
---|
689 | .. _PostgreSQL: http://www.postgresql.org/ |
---|
690 | |
---|
691 | Configuration |
---|
692 | ~~~~~~~~~~~~~ |
---|
693 | +-------------------+-----------+---------------+---------------------------+ |
---|
694 | | Parameter | Type | Default | Description | |
---|
695 | +===================+===========+===============+===========================+ |
---|
696 | | ``dsn`` | Mixed | '' `(empty)` | A `Data Source Name`_. | |
---|
697 | | | | | |required| | |
---|
698 | +-------------------+-----------+---------------+---------------------------+ |
---|
699 | | ``sql`` | String | |sql-default| | SQL insertion statement. | |
---|
700 | +-------------------+-----------+---------------+---------------------------+ |
---|
701 | | ``options`` | Array | ``persistent``| An array of `DB`_ options.| |
---|
702 | +-------------------+-----------+---------------+---------------------------+ |
---|
703 | | ``db`` | Object | NULL | An existing `DB`_ object. | |
---|
704 | | | | | If specified, this object | |
---|
705 | | | | | will be used, and ``dsn`` | |
---|
706 | | | | | will be ignored. | |
---|
707 | +-------------------+-----------+---------------+---------------------------+ |
---|
708 | | ``sequence`` | String | ``log_id`` | The name of the sequence | |
---|
709 | | | | | to use when generating | |
---|
710 | | | | | unique event IDs. Under | |
---|
711 | | | | | many databases, this will | |
---|
712 | | | | | be used as the name of | |
---|
713 | | | | | the sequence table. | |
---|
714 | +-------------------+-----------+---------------+---------------------------+ |
---|
715 | | ``identLimit`` | Integer | 16 | The maximum length of the | |
---|
716 | | | | | ``ident`` string. | |
---|
717 | | | | | **Changing this value may | |
---|
718 | | | | | require updates to the SQL| |
---|
719 | | | | | schema, as well.** | |
---|
720 | +-------------------+-----------+---------------+---------------------------+ |
---|
721 | |
---|
722 | The name of the database table to which the log entries will be written is |
---|
723 | specified using the ``$name`` construction parameter (see `Configuring a |
---|
724 | Handler`_). |
---|
725 | |
---|
726 | .. |sql-default| replace:: ``INSERT INTO $table (id, logtime, ident, priority, message) VALUES(?, CURRENT_TIMESTAMP, ?, ?, ?)`` |
---|
727 | |
---|
728 | .. _DB: http://pear.php.net/package/DB |
---|
729 | .. _PEAR's DB abstraction layer: DB_ |
---|
730 | .. _Data Source Name: http://pear.php.net/manual/en/package.database.db.intro-dsn.php |
---|
731 | |
---|
732 | Examples |
---|
733 | ~~~~~~~~ |
---|
734 | Using a `Data Source Name`_ to create a new database connection:: |
---|
735 | |
---|
736 | $conf = array('dsn' => 'pgsql://jon@localhost+unix/logs'); |
---|
737 | $logger = &Log::singleton('sql', 'log_table', 'ident', $conf); |
---|
738 | for ($i = 0; $i < 10; $i++) { |
---|
739 | $logger->log("Log entry $i"); |
---|
740 | } |
---|
741 | |
---|
742 | Using an existing `DB`_ object:: |
---|
743 | |
---|
744 | require_once 'DB.php'; |
---|
745 | $db = &DB::connect('pgsql://jon@localhost+unix/logs'); |
---|
746 | |
---|
747 | $conf['db'] = $db; |
---|
748 | $logger = &Log::singleton('sql', 'log_table', 'ident', $conf); |
---|
749 | for ($i = 0; $i < 10; $i++) { |
---|
750 | $logger->log("Log entry $i"); |
---|
751 | } |
---|
752 | |
---|
753 | |
---|
754 | The Sqlite Handler |
---|
755 | ------------------ |
---|
756 | :Author: Bertrand Mansion |
---|
757 | |
---|
758 | The Sqlite handler sends log events to an Sqlite database using the `native |
---|
759 | PHP sqlite functions`_. |
---|
760 | |
---|
761 | It is faster than `the SQL (DB) handler`_ because requests are made directly |
---|
762 | to the database without using an abstraction layer. It is also interesting to |
---|
763 | note that Sqlite database files can be moved, copied, and deleted on your |
---|
764 | system just like any other files, which makes log management easier. Last but |
---|
765 | not least, using a database to log your events allows you to use SQL queries |
---|
766 | to create reports and statistics. |
---|
767 | |
---|
768 | When using a database and logging a lot of events, it is recommended to split |
---|
769 | the database into smaller databases. This is allowed by Sqlite, and you can |
---|
770 | later use the Sqlite `ATTACH`_ statement to query your log database files |
---|
771 | globally. |
---|
772 | |
---|
773 | If the database does not exist when the log is opened, sqlite will try to |
---|
774 | create it automatically. If the log table does not exist, it will also be |
---|
775 | automatically created. The table creation uses the following SQL request:: |
---|
776 | |
---|
777 | CREATE TABLE log_table ( |
---|
778 | id INTEGER PRIMARY KEY NOT NULL, |
---|
779 | logtime NOT NULL, |
---|
780 | ident CHAR(16) NOT NULL, |
---|
781 | priority INT NOT NULL, |
---|
782 | message |
---|
783 | ); |
---|
784 | |
---|
785 | Configuration |
---|
786 | ~~~~~~~~~~~~~ |
---|
787 | +-------------------+-----------+---------------+---------------------------+ |
---|
788 | | Parameter | Type | Default | Description | |
---|
789 | +===================+===========+===============+===========================+ |
---|
790 | | ``filename`` | String | '' `(empty)` | Path to an Sqlite | |
---|
791 | | | | | database. |required| | |
---|
792 | +-------------------+-----------+---------------+---------------------------+ |
---|
793 | | ``mode`` | Integer | 0666 | Octal mode used to open | |
---|
794 | | | | | the database. | |
---|
795 | +-------------------+-----------+---------------+---------------------------+ |
---|
796 | | ``persistent`` | Boolean | false | Use a persistent | |
---|
797 | | | | | connection. | |
---|
798 | +-------------------+-----------+---------------+---------------------------+ |
---|
799 | |
---|
800 | An already opened database connection can also be passed as parameter instead |
---|
801 | of the above configuration. In this case, closing the database connection is |
---|
802 | up to the user. |
---|
803 | |
---|
804 | .. _native PHP sqlite functions: http://www.php.net/sqlite |
---|
805 | .. _ATTACH: http://www.sqlite.org/lang.html#attach |
---|
806 | |
---|
807 | Examples |
---|
808 | ~~~~~~~~ |
---|
809 | Using a configuration to create a new database connection:: |
---|
810 | |
---|
811 | $conf = array('filename' => 'log.db', 'mode' => 0666, 'persistent' => true); |
---|
812 | $logger =& Log::factory('sqlite', 'log_table', 'ident', $conf); |
---|
813 | $logger->log('logging an event', PEAR_LOG_WARNING); |
---|
814 | |
---|
815 | Using an existing connection:: |
---|
816 | |
---|
817 | $db = sqlite_open('log.db', 0666, $error); |
---|
818 | $logger =& Log::factory('sqlite', 'log_table', 'ident', $db); |
---|
819 | $logger->log('logging an event', PEAR_LOG_WARNING); |
---|
820 | sqlite_close($db); |
---|
821 | |
---|
822 | |
---|
823 | The Syslog Handler |
---|
824 | ------------------ |
---|
825 | The Syslog handler sends log events to the system logging service (syslog on |
---|
826 | Unix-like environments or the Event Log on Windows systems). The events are |
---|
827 | sent using PHP's `syslog()`_ function. |
---|
828 | |
---|
829 | Configuration |
---|
830 | ~~~~~~~~~~~~~ |
---|
831 | +-------------------+-----------+---------------+---------------------------+ |
---|
832 | | Parameter | Type | Default | Description | |
---|
833 | +===================+===========+===============+===========================+ |
---|
834 | | ``inherit`` | Boolean | false | Inherit the current syslog| |
---|
835 | | | | | connection for this | |
---|
836 | | | | | process, or start a new | |
---|
837 | | | | | one via `openlog()`_? | |
---|
838 | +-------------------+-----------+---------------+---------------------------+ |
---|
839 | |
---|
840 | Facilities |
---|
841 | ~~~~~~~~~~ |
---|
842 | +-------------------+-------------------------------------------------------+ |
---|
843 | | Constant | Category Description | |
---|
844 | +===================+=======================================================+ |
---|
845 | | ``LOG_AUTH`` | Security / authorization messages; ``LOG_AUTHPRIV`` is| |
---|
846 | | | preferred on systems where it is defined. | |
---|
847 | +-------------------+-------------------------------------------------------+ |
---|
848 | | ``LOG_AUTHPRIV`` | Private security / authorization messages | |
---|
849 | +-------------------+-------------------------------------------------------+ |
---|
850 | | ``LOG_CRON`` | Clock daemon (``cron`` and ``at``) | |
---|
851 | +-------------------+-------------------------------------------------------+ |
---|
852 | | ``LOG_DAEMON`` | System daemon processes | |
---|
853 | +-------------------+-------------------------------------------------------+ |
---|
854 | | ``LOG_KERN`` | Kernel messages | |
---|
855 | +-------------------+-------------------------------------------------------+ |
---|
856 | | ``LOG_LOCAL0`` .. | Reserved for local use; **not** available under | |
---|
857 | | ``LOG_LOCAL7`` | Windows. | |
---|
858 | +-------------------+-------------------------------------------------------+ |
---|
859 | | ``LOG_LPR`` | Printer subsystem | |
---|
860 | +-------------------+-------------------------------------------------------+ |
---|
861 | | ``LOG_MAIL`` | Mail subsystem | |
---|
862 | +-------------------+-------------------------------------------------------+ |
---|
863 | | ``LOG_NEWS`` | USENET news subsystem | |
---|
864 | +-------------------+-------------------------------------------------------+ |
---|
865 | | ``LOG_SYSLOG`` | Internal syslog messages | |
---|
866 | +-------------------+-------------------------------------------------------+ |
---|
867 | | ``LOG_USER`` | Generic user-level messages | |
---|
868 | +-------------------+-------------------------------------------------------+ |
---|
869 | | ``LOG_UUCP`` | UUCP subsystem | |
---|
870 | +-------------------+-------------------------------------------------------+ |
---|
871 | |
---|
872 | .. _syslog(): http://www.php.net/syslog |
---|
873 | .. _openlog(): http://www.php.net/openlog |
---|
874 | |
---|
875 | Example |
---|
876 | ~~~~~~~ |
---|
877 | :: |
---|
878 | |
---|
879 | $logger = &Log::singleton('syslog', LOG_LOCAL0, 'ident'); |
---|
880 | for ($i = 0; $i < 10; $i++) { |
---|
881 | $logger->log("Log entry $i"); |
---|
882 | } |
---|
883 | |
---|
884 | |
---|
885 | The Window Handler |
---|
886 | ------------------ |
---|
887 | The Window handler sends log events to a separate browser window. The |
---|
888 | original idea for this handler was inspired by Craig Davis' Zend.com article |
---|
889 | entitled `"JavaScript Power PHP Debugging"`_. |
---|
890 | |
---|
891 | Configuration |
---|
892 | ~~~~~~~~~~~~~ |
---|
893 | +-------------------+-----------+---------------+---------------------------+ |
---|
894 | | Parameter | Type | Default | Description | |
---|
895 | +===================+===========+===============+===========================+ |
---|
896 | | ``title`` | String | ``Log Output | The title of the output | |
---|
897 | | | | Window`` | window. | |
---|
898 | +-------------------+-----------+---------------+---------------------------+ |
---|
899 | | ``styles`` | Array | `ROY G BIV`_ | Mapping of log priorities | |
---|
900 | | | | (high to low) | to CSS styles. | |
---|
901 | +-------------------+-----------+---------------+---------------------------+ |
---|
902 | |
---|
903 | **Note:** The Window handler may not work reliably when PHP's `output |
---|
904 | buffering`_ system is enabled. |
---|
905 | |
---|
906 | .. _"JavaScript Power PHP Debugging": http://www.zend.com/zend/tut/tutorial-DebugLib.php |
---|
907 | .. _ROY G BIV: http://www.cis.rit.edu/ |
---|
908 | .. _output buffering: http://www.php.net/outcontrol |
---|
909 | |
---|
910 | Example |
---|
911 | ~~~~~~~ |
---|
912 | :: |
---|
913 | |
---|
914 | $conf = array('title' => 'Sample Log Output'); |
---|
915 | $logger = &Log::singleton('win', 'LogWindow', 'ident', $conf); |
---|
916 | for ($i = 0; $i < 10; $i++) { |
---|
917 | $logger->log("Log entry $i"); |
---|
918 | } |
---|
919 | |
---|
920 | |
---|
921 | Composite Handlers |
---|
922 | ================== |
---|
923 | It is often useful to log events to multiple handlers. The Log package |
---|
924 | provides a compositing system that marks this task trivial. |
---|
925 | |
---|
926 | Start by creating the individual log handlers:: |
---|
927 | |
---|
928 | $console = &Log::singleton('console', '', 'TEST'); |
---|
929 | $file = &Log::singleton('file', 'out.log', 'TEST'); |
---|
930 | |
---|
931 | Then, construct a composite handler and add the individual handlers as |
---|
932 | children of the composite:: |
---|
933 | |
---|
934 | $composite = &Log::singleton('composite'); |
---|
935 | $composite->addChild($console); |
---|
936 | $composite->addChild($file); |
---|
937 | |
---|
938 | The composite handler implements the standard ``Log`` interface so you can use |
---|
939 | it just like any of the other handlers:: |
---|
940 | |
---|
941 | $composite->log('This event will be logged to both handlers.'); |
---|
942 | |
---|
943 | Children can be removed from the composite when they're not longer needed:: |
---|
944 | |
---|
945 | $composite->removeChild($file); |
---|
946 | |
---|
947 | |
---|
948 | Log Observers |
---|
949 | ============= |
---|
950 | Log observers provide an implementation of the `observer pattern`_. In the |
---|
951 | content of the Log package, they provide a mechanism by which you can examine |
---|
952 | (i.e. observe) each event as it is logged. This allows the implementation of |
---|
953 | special behavior based on the contents of a log event. For example, the |
---|
954 | observer code could send an alert email if a log event contained the string |
---|
955 | ``PANIC``. |
---|
956 | |
---|
957 | Creating a log observer involves implementing a subclass of the |
---|
958 | ``Log_observer`` class. The subclass must override the base class's |
---|
959 | ``notify()`` method. This method is passed a hash containing the event's |
---|
960 | priority and event. The subclass's implementation is free to act upon this |
---|
961 | information in any way it likes. |
---|
962 | |
---|
963 | Log observers are attached to ``Log`` instances via the ``attach()`` method:: |
---|
964 | |
---|
965 | $observer = &Log_observer::factory('yourType'); |
---|
966 | $logger->attach($observer); |
---|
967 | |
---|
968 | Observers can be detached using the ``detach()`` method:: |
---|
969 | |
---|
970 | $logger->detach($observer); |
---|
971 | |
---|
972 | At this time, no concrete ``Log_observer`` implementations are distributed |
---|
973 | with the Log package. |
---|
974 | |
---|
975 | .. _observer pattern: http://wikipedia.org/wiki/Observer_pattern |
---|
976 | |
---|
977 | |
---|
978 | Logging From Standard Error Handlers |
---|
979 | ==================================== |
---|
980 | |
---|
981 | Logging PHP Errors |
---|
982 | ------------------ |
---|
983 | PHP's default error handler can be overridden using the `set_error_handler()`_ |
---|
984 | function. The custom error handling function can use a global Log instance to |
---|
985 | log the PHP errors. |
---|
986 | |
---|
987 | **Note:** Fatal PHP errors cannot be handled by a custom error handler at this |
---|
988 | time. |
---|
989 | |
---|
990 | :: |
---|
991 | |
---|
992 | function errorHandler($code, $message, $file, $line) |
---|
993 | { |
---|
994 | global $logger; |
---|
995 | |
---|
996 | /* Map the PHP error to a Log priority. */ |
---|
997 | switch ($code) { |
---|
998 | case E_WARNING: |
---|
999 | case E_USER_WARNING: |
---|
1000 | $priority = PEAR_LOG_WARNING; |
---|
1001 | break; |
---|
1002 | case E_NOTICE: |
---|
1003 | case E_USER_NOTICE: |
---|
1004 | $priority = PEAR_LOG_NOTICE; |
---|
1005 | break; |
---|
1006 | case E_ERROR: |
---|
1007 | case E_USER_ERROR: |
---|
1008 | $priority = PEAR_LOG_ERR; |
---|
1009 | break; |
---|
1010 | default: |
---|
1011 | $priority = PEAR_LOG_INFO; |
---|
1012 | } |
---|
1013 | |
---|
1014 | $logger->log($message . ' in ' . $file . ' at line ' . $line, |
---|
1015 | $priority); |
---|
1016 | } |
---|
1017 | |
---|
1018 | set_error_handler('errorHandler'); |
---|
1019 | trigger_error('This is an information log message.', E_USER_NOTICE); |
---|
1020 | |
---|
1021 | .. _set_error_handler(): http://www.php.net/set_error_handler |
---|
1022 | |
---|
1023 | Logging PHP Assertions |
---|
1024 | ---------------------- |
---|
1025 | PHP allows user-defined `assert()`_ callback handlers. The assertion callback |
---|
1026 | is configured using the `assert_options()`_ function. |
---|
1027 | |
---|
1028 | :: |
---|
1029 | |
---|
1030 | function assertCallback($file, $line, $message) |
---|
1031 | { |
---|
1032 | global $logger; |
---|
1033 | |
---|
1034 | $logger->log($message . ' in ' . $file . ' at line ' . $line, |
---|
1035 | PEAR_LOG_ALERT); |
---|
1036 | } |
---|
1037 | |
---|
1038 | assert_options(ASSERT_CALLBACK, 'assertCallback'); |
---|
1039 | assert(false); |
---|
1040 | |
---|
1041 | .. _assert(): http://www.php.net/assert |
---|
1042 | .. _assert_options(): http://www.php.net/assert_options |
---|
1043 | |
---|
1044 | Logging PHP Exceptions |
---|
1045 | ---------------------- |
---|
1046 | PHP 5 and later support the concept of `exceptions`_. A custom exception |
---|
1047 | handler can be assigned using the `set_exception_handler()`_ function. |
---|
1048 | |
---|
1049 | :: |
---|
1050 | |
---|
1051 | function exceptionHandler($exception) |
---|
1052 | { |
---|
1053 | global $logger; |
---|
1054 | |
---|
1055 | $logger->log($exception->getMessage(), PEAR_LOG_ALERT); |
---|
1056 | } |
---|
1057 | |
---|
1058 | set_exception_handler('exceptionHandler'); |
---|
1059 | throw new Exception('Uncaught Exception'); |
---|
1060 | |
---|
1061 | .. _exceptions: http://www.php.net/exceptions |
---|
1062 | .. _set_exception_handler(): http://www.php.net/set_exception_handler |
---|
1063 | |
---|
1064 | Logging PEAR Errors |
---|
1065 | ------------------- |
---|
1066 | The Log package can be used with `PEAR::setErrorHandling()`_'s |
---|
1067 | ``PEAR_ERROR_CALLBACK`` mechanism by writing an error handling function that |
---|
1068 | uses a global Log instance. Here's an example:: |
---|
1069 | |
---|
1070 | function errorHandler($error) |
---|
1071 | { |
---|
1072 | global $logger; |
---|
1073 | |
---|
1074 | $message = $error->getMessage(); |
---|
1075 | |
---|
1076 | if (!empty($error->backtrace[1]['file'])) { |
---|
1077 | $message .= ' (' . $error->backtrace[1]['file']; |
---|
1078 | if (!empty($error->backtrace[1]['line'])) { |
---|
1079 | $message .= ' at line ' . $error->backtrace[1]['line']; |
---|
1080 | } |
---|
1081 | $message .= ')'; |
---|
1082 | } |
---|
1083 | |
---|
1084 | $logger->log($message, $error->code); |
---|
1085 | } |
---|
1086 | |
---|
1087 | PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, 'errorHandler'); |
---|
1088 | PEAR::raiseError('This is an information log message.', PEAR_LOG_INFO); |
---|
1089 | |
---|
1090 | .. _PEAR::setErrorHandling(): http://pear.php.net/manual/en/core.pear.pear.seterrorhandling.php |
---|
1091 | |
---|
1092 | |
---|
1093 | Custom Handlers |
---|
1094 | =============== |
---|
1095 | There are times when the standard handlers aren't a perfect match for your |
---|
1096 | needs. In those situations, the solution might be to write a custom handler. |
---|
1097 | |
---|
1098 | Using a Custom Handler |
---|
1099 | ---------------------- |
---|
1100 | Using a custom Log handler is very simple. Once written (see `Writing New |
---|
1101 | Handlers`_ and `Extending Existing Handlers`_ below), you have the choice of |
---|
1102 | placing the file in your PEAR installation's main ``Log/`` directory (usually |
---|
1103 | something like ``/usr/local/lib/php/Log`` or ``C:\php\pear\Log``), where it |
---|
1104 | can be found and use by any PHP application on the system, or placing the file |
---|
1105 | somewhere in your application's local hierarchy and including it before the |
---|
1106 | the custom Log object is constructed. |
---|
1107 | |
---|
1108 | Method 1: Handler in the Standard Location |
---|
1109 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
1110 | After copying the handler file to your PEAR installation's ``Log/`` directory, |
---|
1111 | simply treat the handler as if it were part of the standard distributed. If |
---|
1112 | your handler is named ``custom`` (and therefore implemented by a class named |
---|
1113 | ``Log_custom``):: |
---|
1114 | |
---|
1115 | require_once 'Log.php'; |
---|
1116 | |
---|
1117 | $logger = &Log::factory('custom', '', 'CUSTOM'); |
---|
1118 | |
---|
1119 | |
---|
1120 | Method 2: Handler in a Custom Location |
---|
1121 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
1122 | If you prefer storing your handler in your application's local hierarchy, |
---|
1123 | you'll need to include that file before you can create a Log instance based on |
---|
1124 | it. |
---|
1125 | |
---|
1126 | :: |
---|
1127 | |
---|
1128 | require_once 'Log.php'; |
---|
1129 | require_once 'LocalHandlers/custom.php'; |
---|
1130 | |
---|
1131 | $logger = &Log::factory('custom', '', 'CUSTOM'); |
---|
1132 | |
---|
1133 | |
---|
1134 | Writing New Handlers |
---|
1135 | -------------------- |
---|
1136 | Writing a new Log handler is as simple as authoring a new class that extends |
---|
1137 | the ``Log`` class and that implements a relatively small set of standard |
---|
1138 | methods. |
---|
1139 | |
---|
1140 | Every handler's class name must start with ``Log_`` in order for it to be |
---|
1141 | recognized by the Log package. |
---|
1142 | |
---|
1143 | :: |
---|
1144 | |
---|
1145 | class Log_custom extends Log |
---|
1146 | |
---|
1147 | The handler's constructor will be called with four parameters. These values |
---|
1148 | are discussed in detail in the `Configuring a Handler`_ section. |
---|
1149 | |
---|
1150 | :: |
---|
1151 | |
---|
1152 | Log_custom($name, $ident = '', $conf = array(), $level = PEAR_LOG_DEBUG) |
---|
1153 | |
---|
1154 | The constructor is responsible for configuring the handler based on these |
---|
1155 | values. Handler-specific parameters are passed as part of the ``$conf`` |
---|
1156 | array. At a minimum, the handler's constructor must set the following values |
---|
1157 | defined by the ``Log`` base class:: |
---|
1158 | |
---|
1159 | $this->_id = md5(microtime()); |
---|
1160 | $this->_name = $name; |
---|
1161 | $this->_ident = $ident; |
---|
1162 | $this->_mask = Log::UPTO($level); |
---|
1163 | |
---|
1164 | The `Handler Methods`_ section below details the various standard methods that |
---|
1165 | can be implemented by a log handler. The `Utility Methods`_ section describes |
---|
1166 | some useful utility methods provided by the ``Log`` base class which may be |
---|
1167 | useful when implementing a log handler. |
---|
1168 | |
---|
1169 | |
---|
1170 | Extending Existing Handlers |
---|
1171 | --------------------------- |
---|
1172 | Extending existing handlers is very similar to `writing new handlers`_ with |
---|
1173 | the exception that, instead of inheriting from the ``Log`` base class |
---|
1174 | directly, the handler extends an existing handler's class. This is a useful |
---|
1175 | way of adding some custom behavior to an existing handler without writing an |
---|
1176 | entirely new class (in the spirit of object-oriented programming). |
---|
1177 | |
---|
1178 | For example, `the mail handler`_ could be extended to support sending messages |
---|
1179 | with MIME-encoded attachments simply by authoring a new ``Log_mail_mime`` |
---|
1180 | class with a compliant constructor and a custom ``log()`` method. The rest of |
---|
1181 | the standard methods would fall back on the ``Log_mail`` base class's |
---|
1182 | implementations. |
---|
1183 | |
---|
1184 | Obviously, the specific details involved in extending an existing handler |
---|
1185 | require a good working understanding of that handler's implementation. |
---|
1186 | |
---|
1187 | |
---|
1188 | Handler Methods |
---|
1189 | --------------- |
---|
1190 | |
---|
1191 | bool open() |
---|
1192 | ~~~~~~~~~~~ |
---|
1193 | The ``open()`` method is called to open the log resource for output. Handlers |
---|
1194 | can call ``open()`` immediately upon construction or lazily at runtime |
---|
1195 | (perhaps when the first log event is received). |
---|
1196 | |
---|
1197 | The ``Log`` base class provides a protected ``$_opened`` member variable which |
---|
1198 | should be set to ``true`` when the log handler is opened and ``false`` when it |
---|
1199 | is closed. Handler methods can inspect this value to determine whether or not |
---|
1200 | the handler is currently open and ready for output. |
---|
1201 | |
---|
1202 | If the ``open()`` method fails to ready the handler for output, it should |
---|
1203 | return ``false`` and set ``$this->_opened`` to ``false``. |
---|
1204 | |
---|
1205 | bool close() |
---|
1206 | ~~~~~~~~~~~~ |
---|
1207 | The ``close()`` method is called to close the log resource. This method is |
---|
1208 | the analog of the ``open()`` method. It should be safe to call ``close()`` |
---|
1209 | even when the handler is not open for output. |
---|
1210 | |
---|
1211 | If the ``close()`` method fails to close the handler, it should return |
---|
1212 | ``false``. Otherwise, it should return ``true``. The ``$this->_opened`` |
---|
1213 | flag should also be updated appropriately. |
---|
1214 | |
---|
1215 | bool flush() |
---|
1216 | ~~~~~~~~~~~~ |
---|
1217 | The ``flush()`` method flushes any buffered log events, as described in |
---|
1218 | `Flushing Log Events`_. The implementation of this method will be largely |
---|
1219 | handler-specific. If the handler does not support buffered output, |
---|
1220 | implementing this method is not necessary; the ``Log`` class's ``flush()`` |
---|
1221 | method will be called instead. |
---|
1222 | |
---|
1223 | bool log($message, $priority = null) |
---|
1224 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
1225 | The ``log()`` method is the core of every log handler. It is called whenever |
---|
1226 | the user wishes to log an event. The implementation of this method is very |
---|
1227 | handler-specific. It should return ``true`` or ``false``, depending on |
---|
1228 | whether or not the message was successfully logged by the handler. |
---|
1229 | |
---|
1230 | The ``log()`` implementation should be sure to call `_announce()`__ whenever |
---|
1231 | an event is successfully logged. |
---|
1232 | |
---|
1233 | .. __: `void _announce($event)`_ |
---|
1234 | |
---|
1235 | Utility Methods |
---|
1236 | --------------- |
---|
1237 | These utility methods are provided by the ``Log`` base class and provide |
---|
1238 | common, useful functionality to handler implementations. |
---|
1239 | |
---|
1240 | string _extractMessage($message) |
---|
1241 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
1242 | This method returns the string representation of the provided message data. |
---|
1243 | |
---|
1244 | If ``$message`` is an object, ``_extractMessage()`` will attempt to extract |
---|
1245 | the message text using a known method (such as a `PEAR_Error`_ object's |
---|
1246 | `getMessage()`_ method). If a known method, cannot be found, the serialized |
---|
1247 | representation of the object will be returned. |
---|
1248 | |
---|
1249 | If the message data is already a string, it will be returned unchanged. |
---|
1250 | |
---|
1251 | .. _PEAR_Error: http://pear.php.net/manual/en/core.pear.pear-error.php |
---|
1252 | .. _getMessage(): http://pear.php.net/manual/en/core.pear.pear-error.getmessage.php |
---|
1253 | |
---|
1254 | string _format($format, $timestamp, $priority, $message) |
---|
1255 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
1256 | This method produces a formatted log line based on a format string and a set |
---|
1257 | of `tokens`_ representing the current log record and state. |
---|
1258 | |
---|
1259 | .. _tokens: `Log Line Format`_ |
---|
1260 | |
---|
1261 | bool _isMasked($priority) |
---|
1262 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
1263 | This method checks if the given priority is included in the handler's current |
---|
1264 | level mask. This is useful for determining whether or not a log event should |
---|
1265 | be written to the handler's log. |
---|
1266 | |
---|
1267 | void _announce($event) |
---|
1268 | ~~~~~~~~~~~~~~~~~~~~~~ |
---|
1269 | This method informs any registered `log observers`_ that a new event has been |
---|
1270 | logged. ``$event`` is an array containing two named elements:: |
---|
1271 | |
---|
1272 | array('priority' => $priority, 'message' => $message) |
---|
1273 | |
---|
1274 | ``_announce()`` should be called from a handler's `log()`_ method whenever an |
---|
1275 | event is successfully logged. Otherwise, registered observers will never |
---|
1276 | become aware of the event. |
---|
1277 | |
---|
1278 | .. _log(): `bool log($message, $priority = null)`_ |
---|
1279 | |
---|
1280 | .. |required| replace:: **[required]** |
---|
1281 | |
---|
1282 | .. vim: tabstop=4 shiftwidth=4 softtabstop=4 expandtab textwidth=78 ft=rst: |
---|