* The following libraries are now required:
** psr/log
This library provides the interfaces set by the PSR-3 standard (http://www.php-fig.org/psr/psr-3/)
- which are used by MediaWiki interally by the MWLogger class.
+ which are used by MediaWiki internally via the MWLoggerFactory class.
See the structured logging RfC (https://www.mediawiki.org/wiki/Requests_for_comment/Structured_logging)
for more background information.
** cssjanus/cssjanus
'MWFunction' => __DIR__ . '/includes/utils/MWFunction.php',
'MWHookException' => __DIR__ . '/includes/Hooks.php',
'MWHttpRequest' => __DIR__ . '/includes/HttpFunctions.php',
- 'MWLogger' => __DIR__ . '/includes/debug/logger/Logger.php',
+ 'MWLoggerFactory' => __DIR__ . '/includes/debug/logger/Factory.php',
'MWLoggerLegacyLogger' => __DIR__ . '/includes/debug/logger/legacy/Logger.php',
'MWLoggerLegacySpi' => __DIR__ . '/includes/debug/logger/legacy/Spi.php',
'MWLoggerMonologHandler' => __DIR__ . '/includes/debug/logger/monolog/Handler.php',
-MWLogger implements a PSR-3 [0] compatible message logging system.
+MWLoggerFactory implements a PSR-3 [0] compatible message logging system.
-The MWLogger class is actually a thin wrapper around any PSR-3 LoggerInterface
-implementation. Named MWLogger instances can be obtained from the
-MWLogger::getInstance() static method. MWLogger expects a class implementing
-the MWLoggerSpi interface to act as a factory for new MWLogger instances.
+Named Psr\Log\LoggerInterface instances can be obtained from the
+MWLoggerFactory::getInstance() static method. MWLoggerFactory expects a class
+implementing the MWLoggerSpi interface to act as a factory for new
+Psr\Log\LoggerInterface instances.
-The "Spi" in MWLoggerSpi stands for "service provider interface". An SPI is
-a API intended to be implemented or extended by a third party. This software
+The "Spi" in MWLoggerSpi stands for "service provider interface". A SPI is
+an API intended to be implemented or extended by a third party. This software
design pattern is intended to enable framework extension and replaceable
-components. It is specifically used in the MWLogger service to allow alternate
-PSR-3 logging implementations to be easily integrated with MediaWiki.
+components. It is specifically used in the MWLoggerFactory service to allow
+alternate PSR-3 logging implementations to be easily integrated with
+MediaWiki.
-The MWLogger::getInstance() static method is the means by which most code
-acquires an MWLogger instance. This in turn delegates creation of MWLogger
-instances to a class implementing the MWLoggerSpi service provider interface.
+The MWLoggerFactory::getInstance() static method is the means by which most
+code acquires a Psr\Log\LoggerInterface instance. This in turn delegates
+creation of Psr\Log\LoggerInterface instances to a class implementing the
+MWLoggerSpi service provider interface.
The service provider interface allows the backend logging library to be
implemented in multiple ways. The $wgMWLoggerDefaultSpi global provides the
classname of the default MWLoggerSpi implementation to be loaded at runtime.
This can either be the name of a class implementing the MWLoggerSpi with
a zero argument constructor or a callable that will return an MWLoggerSpi
-instance. Alternately the MWLogger::registerProvider method can be called
-to inject an MWLoggerSpi instance into MWLogger and bypass the use of this
-configuration variable.
+instance. Alternately the MWLoggerFactory::registerProvider method can be
+called to inject an MWLoggerSpi instance into MWLoggerFactory and bypass the
+use of this configuration variable.
The MWLoggerLegacySpi class implements a service provider to generate
MWLoggerLegacyLogger instances. The MWLoggerLegacyLogger class implements the
ready or do not wish to switch to a alternate logging platform.
The MWLoggerMonologSpi class implements a service provider to generate
-MWLogger instances that use the Monolog [1] logging library. See the PHP docs
-(or source) for MWLoggerMonologSpi for details on the configuration of this
-provider. The default configuration installs a null handler that will silently
-discard all logging events. The documentation provided by the class describes
-a more feature rich logging configuration.
+Psr\Log\LoggerInterface instances that use the Monolog [1] logging library.
+See the PHP docs (or source) for MWLoggerMonologSpi for details on the
+configuration of this provider. The default configuration installs a null
+handler that will silently discard all logging events. The documentation
+provided by the class describes a more feature rich logging configuration.
== Classes ==
-; MWLogger
-: PSR-3 compatible logger that wraps any \Psr\Log\LoggerInterface
- implementation
+; MWLoggerFactory
+: Factory for Psr\Log\LoggerInterface loggers
; MWLoggerSpi
-: Service provider interface for MWLogger factories
+: Service provider interface for MWLoggerFactory
; MWLoggerNullSpi
: MWLoggerSpi for creating instances that discard all log events
; MWLoggerLegacySpi
== Globals ==
; $wgMWLoggerDefaultSpi
: Specification for creating the default service provider interface to use
- with MWLogger
+ with MWLoggerFactory
[0]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md
[1]: https://github.com/Seldaek/monolog
$wgDebugLogGroups = array();
/**
- * Default service provider for creating MWLogger instances.
+ * Default service provider for creating Psr\Log\LoggerInterface instances.
*
* The value should be an array suitable for use with
* ObjectFactory::getObjectFromSpec(). The created object is expected to
* implement the MWLoggerSpi interface. See ObjectFactory for additional
* details.
*
- * Alternately the MWLogger::registerProvider method can be called to inject
- * an MWLoggerSpi instance into MWLogger and bypass the use of this
- * configuration variable entirely.
+ * Alternately the MWLoggerFactory::registerProvider method can be called to
+ * inject an MWLoggerSpi instance into MWLoggerFactory and bypass the use of
+ * this configuration variable entirely.
*
* @since 1.25
* @var array $wgMWLoggerDefaultSpi
$context['prefix'] = $wgDebugLogPrefix;
}
- $logger = MWLogger::getInstance( 'wfDebug' );
+ $logger = MWLoggerFactory::getInstance( 'wfDebug' );
$logger->debug( $text, $context );
}
MWDebug::debugMsg( "[{$logGroup}] {$text}\n" );
}
- $logger = MWLogger::getInstance( $logGroup );
+ $logger = MWLoggerFactory::getInstance( $logGroup );
$context['private'] = ( $dest === 'private' );
$logger->info( $text, $context );
}
* @param array $context Additional logging context data
*/
function wfLogDBError( $text, array $context = array() ) {
- $logger = MWLogger::getInstance( 'wfLogDBError' );
+ $logger = MWLoggerFactory::getInstance( 'wfLogDBError' );
$logger->error( trim( $text ), $context );
}
*/
function wfErrorLog( $text, $file, array $context = array() ) {
wfDeprecated( __METHOD__, '1.25' );
- $logger = MWLogger::getInstance( 'wfErrorLog' );
+ $logger = MWLoggerFactory::getInstance( 'wfErrorLog' );
$context['destination'] = $file;
$logger->info( trim( $text ), $context );
}
$ctx['output'] = $profiler->getOutput();
- $log = MWLogger::getInstance( 'profileoutput' );
+ $log = MWLoggerFactory::getInstance( 'profileoutput' );
$log->info( "Elapsed: {elapsed}; URL: <{url}>\n{output}", $ctx );
}
--- /dev/null
+<?php
+/**
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * http://www.gnu.org/copyleft/gpl.html
+ *
+ * @file
+ */
+
+
+/**
+ * PSR-3 logger instance factory.
+ *
+ * Creation of \Psr\Log\LoggerInterface instances is managed via the
+ * MWLoggerFactory::getInstance() static method which in turn delegates to the
+ * currently registered service provider.
+ *
+ * A service provider is any class implementing the MWLoggerSpi interface.
+ * There are two possible methods of registering a service provider. The
+ * MWLoggerFactory::registerProvider() static method can be called at any time
+ * to change the service provider. If MWLoggerFactory::getInstance() is called
+ * before any service provider has been registered, it will attempt to use the
+ * $wgMWLoggerDefaultSpi global to bootstrap MWLoggerSpi registration.
+ * $wgMWLoggerDefaultSpi is expected to be an array usable by
+ * ObjectFactory::getObjectFromSpec() to create a class.
+ *
+ * @see MWLoggerSpi
+ * @since 1.25
+ * @author Bryan Davis <bd808@wikimedia.org>
+ * @copyright © 2014 Bryan Davis and Wikimedia Foundation.
+ */
+class MWLoggerFactory {
+
+ /**
+ * Service provider.
+ * @var MWLoggerSpi $spi
+ */
+ private static $spi;
+
+
+ /**
+ * Register a service provider to create new \Psr\Log\LoggerInterface
+ * instances.
+ *
+ * @param MWLoggerSpi $provider Provider to register
+ */
+ public static function registerProvider( MWLoggerSpi $provider ) {
+ self::$spi = $provider;
+ }
+
+
+ /**
+ * Get the registered service provider.
+ *
+ * If called before any service provider has been registered, it will
+ * attempt to use the $wgMWLoggerDefaultSpi global to bootstrap
+ * MWLoggerSpi registration. $wgMWLoggerDefaultSpi is expected to be an
+ * array usable by ObjectFactory::getObjectFromSpec() to create a class.
+ *
+ * @return MWLoggerSpi
+ * @see registerProvider()
+ * @see ObjectFactory::getObjectFromSpec()
+ */
+ public static function getProvider() {
+ if ( self::$spi === null ) {
+ global $wgMWLoggerDefaultSpi;
+ $provider = ObjectFactory::getObjectFromSpec(
+ $wgMWLoggerDefaultSpi
+ );
+ self::registerProvider( $provider );
+ }
+ return self::$spi;
+ }
+
+
+ /**
+ * Get a named logger instance from the currently configured logger factory.
+ *
+ * @param string $channel Logger channel (name)
+ * @return \Psr\Log\LoggerInterface
+ */
+ public static function getInstance( $channel ) {
+ if ( !interface_exists( '\Psr\Log\LoggerInterface' ) ) {
+ $message = <<<TXT
+MediaWiki requires the <a href="https://github.com/php-fig/log">PSR-3 logging library</a> to be present. This library is not embedded directly in MediaWiki's git repository and must be installed separately by the end user.
+
+Please see <a href="https://www.mediawiki.org/wiki/Download_from_Git#Fetch_external_libraries">mediawiki.org</a> for help on installing the required components.
+TXT;
+ echo $message;
+ trigger_error( $message, E_USER_ERROR );
+ die( 1 );
+ }
+
+ return self::getProvider()->getLogger( $channel );
+ }
+
+
+ /**
+ * Construction of utility class is not allowed.
+ */
+ private function __construct() {
+ // no-op
+ }
+}
+++ /dev/null
-<?php
-/**
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
- * http://www.gnu.org/copyleft/gpl.html
- *
- * @file
- */
-
-if ( !interface_exists( '\Psr\Log\LoggerInterface' ) ) {
- $message = <<<TXT
-MediaWiki requires the <a href="https://github.com/php-fig/log">PSR-3 logging library</a> to be present. This library is not embedded directly in MediaWiki's git repository and must be installed separately by the end user.
-
-Please see <a href="https://www.mediawiki.org/wiki/Download_from_Git#Fetch_external_libraries">mediawiki.org</a> for help on installing the required components.
-TXT;
- echo $message;
- trigger_error( $message, E_USER_ERROR );
- die( 1 );
-}
-
-/**
- * PSR-3 logging service.
- *
- * This class provides a service interface for logging system events. The
- * MWLogger class itself is intended to be a thin wrapper around another PSR-3
- * compliant logging library. Creation of MWLogger instances is managed via
- * the MWLogger::getInstance() static method which in turn delegates to the
- * currently registered service provider.
- *
- * A service provider is any class implementing the MWLoggerSpi interface.
- * There are two possible methods of registering a service provider. The
- * MWLogger::registerProvider() static method can be called at any time to
- * change the service provider. If MWLogger::getInstance() is called before
- * any service provider has been registered, it will attempt to use the
- * $wgMWLoggerDefaultSpi global to bootstrap MWLoggerSpi registration.
- * $wgMWLoggerDefaultSpi is expected to be an array usable by
- * ObjectFactory::getObjectFromSpec() to create a class.
- *
- * @see MWLoggerSpi
- * @since 1.25
- * @author Bryan Davis <bd808@wikimedia.org>
- * @copyright © 2014 Bryan Davis and Wikimedia Foundation.
- */
-class MWLogger implements \Psr\Log\LoggerInterface {
-
- /**
- * Service provider.
- * @var MWLoggerSpi $spi
- */
- protected static $spi;
-
-
- /**
- * Wrapped PSR-3 logger instance.
- *
- * @var \Psr\Log\LoggerInterface $delegate
- */
- protected $delegate;
-
-
- /**
- * @param \Psr\Log\LoggerInterface $logger
- */
- public function __construct( \Psr\Log\LoggerInterface $logger ) {
- $this->delegate = $logger;
- }
-
-
- /**
- * Logs with an arbitrary level.
- *
- * @param string|int $level
- * @param string $message
- * @param array $context
- */
- public function log( $level, $message, array $context = array() ) {
- $this->delegate->log( $level, $message, $context );
- }
-
-
- /**
- * System is unusable.
- *
- * @param string $message
- * @param array $context
- */
- public function emergency( $message, array $context = array() ) {
- $this->log( \Psr\Log\LogLevel::EMERGENCY, $message, $context );
- }
-
-
- /**
- * Action must be taken immediately.
- *
- * Example: Entire website down, database unavailable, etc. This should
- * trigger the SMS alerts and wake you up.
- *
- * @param string $message
- * @param array $context
- */
- public function alert( $message, array $context = array() ) {
- $this->log( \Psr\Log\LogLevel::ALERT, $message, $context );
- }
-
-
- /**
- * Critical conditions.
- *
- * Example: Application component unavailable, unexpected exception.
- *
- * @param string $message
- * @param array $context
- */
- public function critical( $message, array $context = array( ) ) {
- $this->log( \Psr\Log\LogLevel::CRITICAL, $message, $context );
- }
-
-
- /**
- * Runtime errors that do not require immediate action but should typically
- * be logged and monitored.
- *
- * @param string $message
- * @param array $context
- */
- public function error( $message, array $context = array( ) ) {
- $this->log( \Psr\Log\LogLevel::ERROR, $message, $context );
- }
-
-
- /**
- * Exceptional occurrences that are not errors.
- *
- * Example: Use of deprecated APIs, poor use of an API, undesirable things
- * that are not necessarily wrong.
- *
- * @param string $message
- * @param array $context
- */
- public function warning( $message, array $context = array() ) {
- $this->log( \Psr\Log\LogLevel::WARNING, $message, $context );
- }
-
-
- /**
- * Normal but significant events.
- *
- * @param string $message
- * @param array $context
- */
- public function notice( $message, array $context = array() ) {
- $this->log( \Psr\Log\LogLevel::NOTICE, $message, $context );
- }
-
-
- /**
- * Interesting events.
- *
- * Example: User logs in, SQL logs.
- *
- * @param string $message
- * @param array $context
- */
- public function info( $message, array $context = array() ) {
- $this->log( \Psr\Log\LogLevel::INFO, $message, $context );
- }
-
-
- /**
- * Detailed debug information.
- *
- * @param string $message
- * @param array $context
- */
- public function debug( $message, array $context = array() ) {
- $this->log( \Psr\Log\LogLevel::DEBUG, $message, $context );
- }
-
-
- /**
- * Register a service provider to create new MWLogger instances.
- *
- * @param MWLoggerSpi $provider Provider to register
- */
- public static function registerProvider( MWLoggerSpi $provider ) {
- self::$spi = $provider;
- }
-
-
- /**
- * Get the registered service provider.
- *
- * If called before any service provider has been registered, it will
- * attempt to use the $wgMWLoggerDefaultSpi global to bootstrap
- * MWLoggerSpi registration. $wgMWLoggerDefaultSpi is expected to be an
- * array usable by ObjectFactory::getObjectFromSpec() to create a class.
- *
- * @return MWLoggerSpi
- * @see registerProvider()
- * @see ObjectFactory::getObjectFromSpec()
- */
- public static function getProvider() {
- if ( self::$spi === null ) {
- global $wgMWLoggerDefaultSpi;
- $provider = ObjectFactory::getObjectFromSpec(
- $wgMWLoggerDefaultSpi
- );
- self::registerProvider( $provider );
- }
- return self::$spi;
- }
-
- /**
- * Get a named logger instance from the currently configured logger factory.
- *
- * @param string $channel Logger channel (name)
- * @return MWLogger
- */
- public static function getInstance( $channel ) {
- return self::getProvider()->getLogger( $channel );
- }
-
-}
* @file
*/
+
/**
- * MWLogger service provider that creates \Psr\Log\NullLogger instances.
- * A NullLogger silently discards all log events sent to it.
+ * MWLoggerFactory service provider that creates \Psr\Log\NullLogger
+ * instances. A NullLogger silently discards all log events sent to it.
*
* Usage:
* @code
* );
* @endcode
*
- * @see MWLogger
+ * @see MWLoggerFactory
* @since 1.25
* @author Bryan Davis <bd808@wikimedia.org>
* @copyright © 2014 Bryan Davis and Wikimedia Foundation.
* Get a logger instance.
*
* @param string $channel Logging channel
- * @return MWLogger Logger instance
+ * @return \Psr\Log\NullLogger Logger instance
*/
public function getLogger( $channel ) {
return $this->singleton;
*/
/**
- * Service provider interface for MWLogger implementation libraries.
+ * Service provider interface for \Psr\Log\LoggerInterface implementation
+ * libraries.
*
* MediaWiki can be configured to use a class implementing this interface to
- * create new MWLogger instances via either the $wgMWLoggerDefaultSpi global
- * variable or code that constructs an instance and registeres it via the
- * MWLogger::registerProvider() static method.
+ * create new \Psr\Log\LoggerInterface instances via either the
+ * $wgMWLoggerDefaultSpi global variable or code that constructs an instance
+ * and registers it via the MWLoggerFactory::registerProvider() static method.
*
- * @see MWLogger
+ * @see MWLoggerFactory
* @since 1.25
* @author Bryan Davis <bd808@wikimedia.org>
* @copyright © 2014 Bryan Davis and Wikimedia Foundation.
* Get a logger instance.
*
* @param string $channel Logging channel
- * @return MWLogger Logger instance
+ * @return \Psr\Log\LoggerInterface Logger instance
*/
public function getLogger( $channel );
* See documentation in DefaultSettings.php for detailed explanations of each
* variable.
*
- * @see MWLogger
+ * @see MWLoggerFactory
* @since 1.25
* @author Bryan Davis <bd808@wikimedia.org>
* @copyright © 2014 Bryan Davis and Wikimedia Foundation.
*/
/**
- * MWLogger service provider that creates MWLoggerLegacyLogger instances.
+ * MWLoggerFactory service provider that creates MWLoggerLegacyLogger
+ * instances.
*
* Usage:
* @code
* );
* @endcode
*
- * @see MWLogger
+ * @see MWLoggerFactory
* @since 1.25
* @author Bryan Davis <bd808@wikimedia.org>
* @copyright © 2014 Bryan Davis and Wikimedia Foundation.
* Get a logger instance.
*
* @param string $channel Logging channel
- * @return MWLogger Logger instance
+ * @return \Psr\Log\LoggerInterface Logger instance
*/
public function getLogger( $channel ) {
if ( !isset( $this->singletons[$channel] ) ) {
* 'class' => 'MWLoggerMonologSamplingHandler',
* 'args' => array(
* function() {
- * return MWLogger::getProvider()->getHandler( 'some-handler');
+ * return MWLoggerFactory::getProvider()->getHandler( 'some-handler');
* },
* 2, // emit logs with a 1:2 chance
* ),
*/
/**
- * MWLogger service provider that creates loggers implemented by Monolog.
+ * MWLoggerFactory service provider that creates loggers implemented by
+ * Monolog.
*
* Configured using an array of configuration data with the keys 'loggers',
* 'processors', 'handlers' and 'formatters'.
* section.
*
* Configuration will most typically be provided in the $wgMWLoggerDefaultSpi
- * global configuration variable used by MWLogger to construct its default SPI
- * provider:
+ * global configuration variable used by MWLoggerFactory to construct its
+ * default SPI provider:
* @code
* $wgMWLoggerDefaultSpi = array(
* 'class' => 'MWLoggerMonologSpi',
* name will return the cached instance.
*
* @param string $channel Logging channel
- * @return MWLogger Logger instance
+ * @return \Psr\Log\LoggerInterface Logger instance
*/
public function getLogger( $channel ) {
if ( !isset( $this->singletons['loggers'][$channel] ) ) {
$this->config['loggers']['@default'];
$monolog = $this->createLogger( $channel, $spec );
- $this->singletons['loggers'][$channel] = new MWLogger( $monolog );
+ $this->singletons['loggers'][$channel] = $monolog;
}
return $this->singletons['loggers'][$channel];