/vendor/monolog/monolog/doc/usage.md

https://bitbucket.org/larryg/powerhut · Markdown · 158 lines · 116 code · 42 blank · 0 comment · 0 complexity · 6a064d506bbc75afaa0e71f25db0a94f MD5 · raw file

  1. Using Monolog
  2. =============
  3. Installation
  4. ------------
  5. Monolog is available on Packagist ([monolog/monolog](http://packagist.org/packages/monolog/monolog))
  6. and as such installable via [Composer](http://getcomposer.org/).
  7. If you do not use Composer, you can grab the code from GitHub, and use any
  8. PSR-0 compatible autoloader (e.g. the [Symfony2 ClassLoader component](https://github.com/symfony/ClassLoader))
  9. to load Monolog classes.
  10. Configuring a logger
  11. --------------------
  12. Here is a basic setup to log to a file and to firephp on the DEBUG level:
  13. ```php
  14. <?php
  15. use Monolog\Logger;
  16. use Monolog\Handler\StreamHandler;
  17. use Monolog\Handler\FirePHPHandler;
  18. // Create the logger
  19. $logger = new Logger('my_logger');
  20. // Now add some handlers
  21. $logger->pushHandler(new StreamHandler(__DIR__.'/my_app.log', Logger::DEBUG));
  22. $logger->pushHandler(new FirePHPHandler());
  23. // You can now use your logger
  24. $logger->addInfo('My logger is now ready');
  25. ```
  26. Let's explain it. The first step is to create the logger instance which will
  27. be used in your code. The argument is a channel name, which is useful when
  28. you use several loggers (see below for more details about it).
  29. The logger itself does not know how to handle a record. It delegates it to
  30. some handlers. The code above registers two handlers in the stack to allow
  31. handling records in two different ways.
  32. Note that the FirePHPHandler is called first as it is added on top of the
  33. stack. This allows you to temporarily add a logger with bubbling disabled if
  34. you want to override other configured loggers.
  35. Adding extra data in the records
  36. --------------------------------
  37. Monolog provides two different ways to add extra informations along the simple
  38. textual message.
  39. ### Using the logging context
  40. The first way is the context, allowing to pass an array of data along the
  41. record:
  42. ```php
  43. <?php
  44. $logger->addInfo('Adding a new user', array('username' => 'Seldaek'));
  45. ```
  46. Simple handlers (like the StreamHandler for instance) will simply format
  47. the array to a string but richer handlers can take advantage of the context
  48. (FirePHP is able to display arrays in pretty way for instance).
  49. ### Using processors
  50. The second way is to add extra data for all records by using a processor.
  51. Processors can be any callable. They will get the record as parameter and
  52. must return it after having eventually changed the `extra` part of it. Let's
  53. write a processor adding some dummy data in the record:
  54. ```php
  55. <?php
  56. $logger->pushProcessor(function ($record) {
  57. $record['extra']['dummy'] = 'Hello world!';
  58. return $record;
  59. });
  60. ```
  61. Monolog provides some built-in processors that can be used in your project.
  62. Look at the README file for the list.
  63. > Tip: processors can also be registered on a specific handler instead of
  64. the logger to apply only for this handler.
  65. Leveraging channels
  66. -------------------
  67. Channels are a great way to identify to which part of the application a record
  68. is related. This is useful in big applications (and is leveraged by
  69. MonologBundle in Symfony2).
  70. Picture two loggers sharing a handler that writes to a single log file.
  71. Channels would allow you to identify the logger that issued every record.
  72. You can easily grep through the log files filtering this or that channel.
  73. ```php
  74. <?php
  75. use Monolog\Logger;
  76. use Monolog\Handler\StreamHandler;
  77. use Monolog\Handler\FirePHPHandler;
  78. // Create some handlers
  79. $stream = new StreamHandler(__DIR__.'/my_app.log', Logger::DEBUG);
  80. $firephp = new FirePHPHandler();
  81. // Create the main logger of the app
  82. $logger = new Logger('my_logger');
  83. $logger->pushHandler($stream);
  84. $logger->pushHandler($firephp);
  85. // Create a logger for the security-related stuff with a different channel
  86. $securityLogger = new Logger('security');
  87. $securityLogger->pushHandler($stream);
  88. $securityLogger->pushHandler($firephp);
  89. ```
  90. Customizing log format
  91. ----------------------
  92. In Monolog it's easy to customize the format of the logs written into files,
  93. sockets, mails, databases and other handlers. Most of the handlers use the
  94. ```php
  95. $record['formatted']
  96. ```
  97. value to be automatically put into the log device. This value depends on the
  98. formatter settings. You can choose between predefined formatter classes or
  99. write your own (e.g. a multiline text file for human-readable output).
  100. To configure a predefined formatter class, just set it as the handler's field:
  101. ```php
  102. // the default date format is "Y-m-d H:i:s"
  103. $dateFormat = "Y n j, g:i a";
  104. // the default output format is "[%datetime%] %channel%.%level_name%: %message% %context% %extra%\n"
  105. $output = "%datetime% > %level_name% > %message% %context% %extra%\n";
  106. // finally, create a formatter
  107. $formatter = new LineFormatter($output, $dateFormat);
  108. // Create a handler
  109. $stream = new StreamHandler(__DIR__.'/my_app.log', Logger::DEBUG);
  110. $stream->setFormatter($formatter);
  111. // bind it to a logger object
  112. $securityLogger = new Logger('security');
  113. $securityLogger->pushHandler($stream);
  114. ```
  115. You may also reuse the same formatter between multiple handlers and share those
  116. handlers between multiple loggers.