Context Navigation

← Previous Revision
Latest Revision
Next Revision →
Annotate
Revision Log

guide.txt @ 1349

Revision 1349, 54.7 KB checked in by niltonneto, 15 years ago (diff)
Ticket #561 - Inclusão do módulo Workflow faltante nessa versão.
Property svn:executable set to ``*

Line
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:

Note: See TracBrowser for help on using the repository browser.

Context Navigation

source: branches/1.2/workflow/inc/log/docs/guide.txt @ 1349

Download in other formats: