docs/mwlogger.txt

   1 MWLogger implements a PSR-3 [0] compatible message logging system.
   2
   3 The MWLogger class is actually a thin wrapper around any PSR-3 LoggerInterface
   4 implementation. Named MWLogger instances can be obtained from the
   5 MWLogger::getInstance() static method. MWLogger expects a class implementing
   6 the MWLoggerSpi interface to act as a factory for new MWLogger instances.
   7
   8 The "Spi" in MWLoggerSpi stands for "service provider interface". An SPI is
   9 a API intended to be implemented or extended by a third party. This software
  10 design pattern is intended to enable framework extension and replaceable
  11 components. It is specifically used in the MWLogger service to allow alternate
  12 PSR-3 logging implementations to be easily integrated with MediaWiki.
  13
  14 The MWLogger::getInstance() static method is the means by which most code
  15 acquires an MWLogger instance. This in turn delegates creation of MWLogger
  16 instances to a class implementing the MWLoggerSpi service provider interface.
  17
  18 The service provider interface allows the backend logging library to be
  19 implemented in multiple ways. The $wgMWLoggerDefaultSpi global provides the
  20 classname of the default MWLoggerSpi implementation to be loaded at runtime.
  21 This can either be the name of a class implementing the MWLoggerSpi with
  22 a zero argument constructor or a callable that will return an MWLoggerSpi
  23 instance. Alternately the MWLogger::registerProvider method can be called
  24 to inject an MWLoggerSpi instance into MWLogger and bypass the use of this
  25 configuration variable.
  26
  27 The MWLoggerLegacySpi class implements a service provider to generate
  28 MWLoggerLegacyLogger instances. The MWLoggerLegacyLogger class implements the
  29 PSR-3 logger interface and provides output and configuration equivalent to the
  30 historic logging output of wfDebug, wfDebugLog, wfLogDBError and wfErrorLog.
  31 The MWLoggerLegacySpi class is the default service provider configured in
  32 DefaultSettings.php. It's usage should be transparent for users who are not
  33 ready or do not wish to switch to a alternate logging platform.
  34
  35 The MWLoggerMonologSpi class implements a service provider to generate
  36 MWLogger instances that use the Monolog [1] logging library. See the PHP docs
  37 (or source) for MWLoggerMonologSpi for details on the configuration of this
  38 provider. The default configuration installs a null handler that will silently
  39 discard all logging events. The documentation provided by the class describes
  40 a more feature rich logging configuration.
  41
  42 == Classes ==
  43 ; MWLogger
  44 : PSR-3 compatible logger that wraps any \Psr\Log\LoggerInterface
  45   implementation
  46 ; MWLoggerSpi
  47 : Service provider interface for MWLogger factories
  48 ; MWLoggerNullSpi
  49 : MWLoggerSpi for creating instances that discard all log events
  50 ; MWLoggerLegacySpi
  51 : Service provider for creating MWLoggerLegacyLogger instances
  52 ; MWLoggerLegacyLogger
  53 : PSR-3 logger that mimics the historical output and configuration of wfDebug,
  54   wfErrorLog and other global logging functions.
  55 ; MWLoggerMonologSpi
  56 : MWLoggerSpi for creating instances backed by the monolog logging library
  57 ; MwLoggerMonologHandler
  58 : Monolog handler that replicates the udp2log and file logging
  59   functionality of wfErrorLog()
  60 ; MwLoggerMonologProcessor
  61 : Monolog log processer that adds host: wfHostname() and wiki: wfWikiID()
  62   to all records
  63
  64 == Globals ==
  65 ; $wgMWLoggerDefaultSpi
  66 : Specification for creating the default service provider interface to use
  67   with MWLogger
  68
  69 [0]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md
  70 [1]: https://github.com/Seldaek/monolog