[795] | 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: |
---|