From 87332a3e4e5838c97c4e6a6cb65e0c5ddfe6da22 Mon Sep 17 00:00:00 2001 From: Christophe Coevoet Date: Wed, 6 Apr 2011 00:50:18 +0200 Subject: [PATCH] Added phpdoc for all methods and added the typehint for the FormatterInterface --- src/Monolog/Formatter/FormatterInterface.php | 8 +- src/Monolog/Formatter/JsonFormatter.php | 6 +- src/Monolog/Formatter/LineFormatter.php | 10 +- src/Monolog/Handler/AbstractHandler.php | 60 ++++++--- src/Monolog/Handler/BufferHandler.php | 14 +- src/Monolog/Handler/FingersCrossedHandler.php | 13 +- src/Monolog/Handler/HandlerInterface.php | 12 +- src/Monolog/Handler/NullHandler.php | 7 + src/Monolog/Handler/RotatingFileHandler.php | 7 +- src/Monolog/Handler/StreamHandler.php | 4 +- src/Monolog/Handler/SyslogHandler.php | 15 ++- src/Monolog/Handler/TestHandler.php | 4 + src/Monolog/Logger.php | 125 ++++++++++++++++++ src/Monolog/Processor/WebProcessor.php | 10 +- 14 files changed, 247 insertions(+), 48 deletions(-) diff --git a/src/Monolog/Formatter/FormatterInterface.php b/src/Monolog/Formatter/FormatterInterface.php index 7ddd4b43..953bd4c3 100644 --- a/src/Monolog/Formatter/FormatterInterface.php +++ b/src/Monolog/Formatter/FormatterInterface.php @@ -18,5 +18,11 @@ namespace Monolog\Formatter; */ interface FormatterInterface { - function format($record); + /** + * Formats a log record. + * + * @param array $record A record to format + * @return array The record with a formatted message + */ + function format(array $record); } diff --git a/src/Monolog/Formatter/JsonFormatter.php b/src/Monolog/Formatter/JsonFormatter.php index f7889b6c..c6d56f5f 100644 --- a/src/Monolog/Formatter/JsonFormatter.php +++ b/src/Monolog/Formatter/JsonFormatter.php @@ -22,9 +22,13 @@ use Monolog\Logger; */ class JsonFormatter implements FormatterInterface { - public function format($record) + /** + * {@inheritdoc} + */ + public function format(array $record) { $record['message'] = json_encode($record); + return $record; } } diff --git a/src/Monolog/Formatter/LineFormatter.php b/src/Monolog/Formatter/LineFormatter.php index 0d64db3b..cce3e329 100644 --- a/src/Monolog/Formatter/LineFormatter.php +++ b/src/Monolog/Formatter/LineFormatter.php @@ -28,13 +28,20 @@ class LineFormatter implements FormatterInterface protected $format; protected $dateFormat; + /** + * @param string $format The format of the message + * @param string $dateFormat The format of the timestamp: one supported by DateTime::format + */ public function __construct($format = null, $dateFormat = null) { $this->format = $format ?: self::SIMPLE_FORMAT; $this->dateFormat = $dateFormat ?: self::SIMPLE_DATE; } - public function format($record) + /** + * {@inheritdoc} + */ + public function format(array $record) { $vars = $record; $vars['datetime'] = $vars['datetime']->format($this->dateFormat); @@ -56,6 +63,7 @@ class LineFormatter implements FormatterInterface $output = str_replace('%extra.'.$var.'%', $val, $output); } $record['message'] = $output; + return $record; } } diff --git a/src/Monolog/Handler/AbstractHandler.php b/src/Monolog/Handler/AbstractHandler.php index 593b2e8e..d257e689 100644 --- a/src/Monolog/Handler/AbstractHandler.php +++ b/src/Monolog/Handler/AbstractHandler.php @@ -41,12 +41,7 @@ abstract class AbstractHandler implements HandlerInterface } /** - * Checks whether the given record will be handled by this handler - * - * This is mostly done for performance reasons, to avoid calling processors for nothing. - * - * @param array $record - * @return Boolean True if the record can be handled. + * {@inheritdoc} */ public function isHandling(array $record) { @@ -54,13 +49,7 @@ abstract class AbstractHandler implements HandlerInterface } /** - * Handles a record - * - * The return value of this function controls the bubbling process of the handler stack. - * - * @param array $record - * @return Boolean True means that this handler handled the record, and that bubbling is not permitted. - * False means the record was either not processed or that this handler allows bubbling. + * {@inheritdoc} */ public function handle(array $record) { @@ -84,9 +73,7 @@ abstract class AbstractHandler implements HandlerInterface } /** - * Handles a set of records at once - * - * @param array $records array of records + * {@inheritdoc} */ public function handleBatch(array $records) { @@ -104,7 +91,7 @@ abstract class AbstractHandler implements HandlerInterface abstract public function write(array $record); /** - * Closes the log + * Closes the handler. * * This will be called automatically when the object is destroyed */ @@ -112,41 +99,75 @@ abstract class AbstractHandler implements HandlerInterface { } + /** + * {@inheritdoc} + */ public function pushProcessor($callback) { array_unshift($this->processors, $callback); } + /** + * {@inheritdoc} + */ public function popProcessor() { return array_shift($this->processors); } + /** + * {@inheritdoc} + */ public function setFormatter(FormatterInterface $formatter) { $this->formatter = $formatter; } + /** + * {@inheritdoc} + */ public function getFormatter() { return $this->formatter; } + /** + * Sets minimum logging level at which this handler will be triggered. + * + * @param integer $level + */ public function setLevel($level) { $this->level = $level; } + /** + * Gets minimum logging level at which this handler will be triggered. + * + * @return integer + */ public function getLevel() { return $this->level; } + /** + * Sets the bubbling behavior. + * + * @param Boolean $bubble True means that bubbling is not permitted. + * False means that this handler allows bubbling. + */ public function setBubble($bubble) { $this->bubble = $bubble; } + /** + * Gets the bubbling behavior. + * + * @return Boolean True means that bubbling is not permitted. + * False means that this handler allows bubbling. + */ public function getBubble() { return $this->bubble; @@ -157,6 +178,11 @@ abstract class AbstractHandler implements HandlerInterface $this->close(); } + /** + * Gets the default formatter. + * + * @return FormatterInterface + */ protected function getDefaultFormatter() { return new LineFormatter(); diff --git a/src/Monolog/Handler/BufferHandler.php b/src/Monolog/Handler/BufferHandler.php index efc4b25c..64af35e4 100644 --- a/src/Monolog/Handler/BufferHandler.php +++ b/src/Monolog/Handler/BufferHandler.php @@ -29,8 +29,8 @@ class BufferHandler extends AbstractHandler /** * @param HandlerInterface $handler Handler. - * @param int $bufferSize How many entries should be buffered at most, beyond that the oldest items are removed from the buffer. - * @param Boolean $bubble + * @param integer $bufferSize How many entries should be buffered at most, beyond that the oldest items are removed from the buffer. + * @param Boolean $bubble Whether the messages that are handled can bubble up the stack or not */ public function __construct(HandlerInterface $handler, $bufferSize = 0, $bubble = false) { @@ -40,12 +40,7 @@ class BufferHandler extends AbstractHandler } /** - * Handles a record - * - * Records are buffered until closing the handler. - * - * @param array $record Records - * @return Boolean Whether the record was handled + * {@inheritdoc} */ public function handle(array $record) { @@ -57,6 +52,9 @@ class BufferHandler extends AbstractHandler return false === $this->bubble; } + /** + * {@inheritdoc} + */ public function close() { $this->handler->handleBatch($this->buffer); diff --git a/src/Monolog/Handler/FingersCrossedHandler.php b/src/Monolog/Handler/FingersCrossedHandler.php index 93d05d02..f8c0c513 100644 --- a/src/Monolog/Handler/FingersCrossedHandler.php +++ b/src/Monolog/Handler/FingersCrossedHandler.php @@ -32,9 +32,9 @@ class FingersCrossedHandler extends AbstractHandler /** * @param callback|HandlerInterface $handler Handler or factory callback($record, $fingersCrossedHandler). - * @param int $actionLevel The level at which this handler is triggered. + * @param int $actionLevel The minimum logging level at which this handler will be triggered * @param int $bufferSize How many entries should be buffered at most, beyond that the oldest items are removed from the buffer. - * @param Boolean $bubble + * @param Boolean $bubble Whether the messages that are handled can bubble up the stack or not */ public function __construct($handler, $actionLevel = Logger::WARNING, $bufferSize = 0, $bubble = false) { @@ -45,13 +45,7 @@ class FingersCrossedHandler extends AbstractHandler } /** - * Handles a record - * - * Records are buffered until one of them matches the actionLevel. From then - * on, unless reset() is called, all records are passed to the wrapped handler. - * - * @param array $record Records - * @return Boolean Whether the record was handled + * {@inheritdoc} */ public function handle(array $record) { @@ -76,6 +70,7 @@ class FingersCrossedHandler extends AbstractHandler } else { $this->handler->handle($record); } + return false === $this->bubble; } diff --git a/src/Monolog/Handler/HandlerInterface.php b/src/Monolog/Handler/HandlerInterface.php index 7833fa83..24f82d7e 100644 --- a/src/Monolog/Handler/HandlerInterface.php +++ b/src/Monolog/Handler/HandlerInterface.php @@ -21,7 +21,9 @@ use Monolog\Formatter\FormatterInterface; interface HandlerInterface { /** - * Checks whether the handler handles the record. + * Checks whether the given record will be handled by this handler. + * + * This is mostly done for performance reasons, to avoid calling processors for nothing. * * @return Boolean */ @@ -30,16 +32,18 @@ interface HandlerInterface /** * Handles a record. * + * The return value of this function controls the bubbling process of the handler stack. + * * @param array $record The record to handle - * @return Boolean Whether the handler stops the propagation in the stack or not. + * @return Boolean True means that this handler handled the record, and that bubbling is not permitted. + * False means the record was either not processed or that this handler allows bubbling. */ function handle(array $record); /** - * Handles a set of records. + * Handles a set of records at once. * * @param array $records The records to handle (an array of record arrays) - * @return Boolean Whether the handler stops the propagation in the stack or not. */ function handleBatch(array $records); diff --git a/src/Monolog/Handler/NullHandler.php b/src/Monolog/Handler/NullHandler.php index 154f38f5..d014c363 100644 --- a/src/Monolog/Handler/NullHandler.php +++ b/src/Monolog/Handler/NullHandler.php @@ -23,14 +23,21 @@ use Monolog\Logger; */ class NullHandler extends AbstractHandler { + /** + * {@inheritdoc} + */ public function handle(array $record) { if ($record['level'] < $this->level) { return false; } + return false === $this->bubble; } + /** + * {@inheritdoc} + */ public function write(array $record) { } diff --git a/src/Monolog/Handler/RotatingFileHandler.php b/src/Monolog/Handler/RotatingFileHandler.php index 10b2db3a..68ec2654 100644 --- a/src/Monolog/Handler/RotatingFileHandler.php +++ b/src/Monolog/Handler/RotatingFileHandler.php @@ -30,8 +30,8 @@ class RotatingFileHandler extends StreamHandler /** * @param string $filename * @param integer $maxFiles The maximal amount of files to keep (0 means unlimited) - * @param integer $level - * @param Boolean $bubble + * @param integer $level The minimum logging level at which this handler will be triggered + * @param Boolean $bubble Whether the messages that are handled can bubble up the stack or not */ public function __construct($filename, $maxFiles = 0, $level = Logger::DEBUG, $bubble = true) { @@ -61,7 +61,8 @@ class RotatingFileHandler extends StreamHandler if (null === $this->mustRotate) { $this->mustRotate = !file_exists($this->url); } - return parent::write($record); + + parent::write($record); } /** diff --git a/src/Monolog/Handler/StreamHandler.php b/src/Monolog/Handler/StreamHandler.php index 1f26583f..0cc9ed6e 100644 --- a/src/Monolog/Handler/StreamHandler.php +++ b/src/Monolog/Handler/StreamHandler.php @@ -28,8 +28,8 @@ class StreamHandler extends AbstractHandler /** * @param string $stream - * @param integer $level - * @param Boolean $bubble + * @param integer $level The minimum logging level at which this handler will be triggered + * @param Boolean $bubble Whether the messages that are handled can bubble up the stack or not */ public function __construct($stream, $level = Logger::DEBUG, $bubble = true) { diff --git a/src/Monolog/Handler/SyslogHandler.php b/src/Monolog/Handler/SyslogHandler.php index dee90c07..820930bb 100644 --- a/src/Monolog/Handler/SyslogHandler.php +++ b/src/Monolog/Handler/SyslogHandler.php @@ -30,7 +30,7 @@ use Monolog\Logger; class SyslogHandler extends AbstractHandler { /** - * Translate Monolog log levels to syslog log priorities. + * Translates Monolog log levels to syslog log priorities. */ private $logLevels = array( Logger::DEBUG => LOG_DEBUG, @@ -56,6 +56,13 @@ class SyslogHandler extends AbstractHandler 'uucp' => LOG_UUCP, ); + /** + * + * @param string $ident + * @param mixed $facility + * @param integer $level The minimum logging level at which this handler will be triggered + * @param Boolean $bubble Whether the messages that are handled can bubble up the stack or not + */ public function __construct($ident, $facility = LOG_USER, $level = Logger::DEBUG, $bubble = true) { parent::__construct($level, $bubble); @@ -83,11 +90,17 @@ class SyslogHandler extends AbstractHandler } } + /** + * {@inheritdoc} + */ public function write(array $record) { syslog($this->logLevels[$record['level']], (string) $record['message']); } + /** + * {@inheritdoc} + */ public function close() { closelog(); diff --git a/src/Monolog/Handler/TestHandler.php b/src/Monolog/Handler/TestHandler.php index 6816373d..ea70e196 100644 --- a/src/Monolog/Handler/TestHandler.php +++ b/src/Monolog/Handler/TestHandler.php @@ -82,9 +82,13 @@ class TestHandler extends AbstractHandler return true; } } + return false; } + /** + * {@inheritdoc} + */ public function write(array $record) { $this->recordsByLevel[$record['level']][] = $record; diff --git a/src/Monolog/Logger.php b/src/Monolog/Logger.php index a1cfa244..31ad4349 100644 --- a/src/Monolog/Logger.php +++ b/src/Monolog/Logger.php @@ -64,16 +64,29 @@ class Logger protected $processors = array(); + /** + * @param string $name The logging channel + */ public function __construct($name) { $this->name = $name; } + /** + * Pushes an handler on the stack. + * + * @param HandlerInterface $handler + */ public function pushHandler(HandlerInterface $handler) { array_unshift($this->handlers, $handler); } + /** + * Pops an handler from the stack + * + * @return HandlerInterface + */ public function popHandler() { if (!$this->handlers) { @@ -82,11 +95,21 @@ class Logger return array_shift($this->handlers); } + /** + * Adds a processor in the stack. + * + * @param callable $callback + */ public function pushProcessor($callback) { array_unshift($this->processors, $callback); } + /** + * Removes the processor on top of the stack and returns it. + * + * @return callable + */ public function popProcessor() { if (!$this->processors) { @@ -95,6 +118,13 @@ class Logger return array_shift($this->processors); } + /** + * Adds a log record. + * + * @param integer $level The logging level + * @param string $message The log message + * @return Boolean Whether the record has been processed + */ public function addRecord($level, $message) { if (!$this->handlers) { @@ -128,29 +158,60 @@ class Logger false === $this->handlers[$handlerKey]->handle($record)) { $handlerKey++; } + return true; } + /** + * Adds a log record at the DEBUG level. + * + * @param string $message The log message + * @return Boolean Whether the record has been processed + */ public function addDebug($message) { return $this->addRecord(self::DEBUG, $message); } + /** + * Adds a log record at the INFO level. + * + * @param string $message The log message + * @return Boolean Whether the record has been processed + */ public function addInfo($message) { return $this->addRecord(self::INFO, $message); } + /** + * Adds a log record at the WARNING level. + * + * @param string $message The log message + * @return Boolean Whether the record has been processed + */ public function addWarning($message) { return $this->addRecord(self::WARNING, $message); } + /** + * Adds a log record at the ERROR level. + * + * @param string $message The log message + * @return Boolean Whether the record has been processed + */ public function addError($message) { return $this->addRecord(self::ERROR, $message); } + /** + * Gets the name of the logging level. + * + * @param integer $level + * @return string + */ public static function getLevelName($level) { return self::$levels[$level]; @@ -158,41 +219,105 @@ class Logger // ZF Logger Compat + /** + * Adds a log record at the DEBUG level. + * + * This method allows to have an esay ZF compatibility. + * + * @param string $message The log message + * @return Boolean Whether the record has been processed + */ public function debug($message) { return $this->addRecord(self::DEBUG, $message); } + /** + * Adds a log record at the INFO level. + * + * This method allows to have an esay ZF compatibility. + * + * @param string $message The log message + * @return Boolean Whether the record has been processed + */ public function info($message) { return $this->addRecord(self::INFO, $message); } + /** + * Adds a log record at the INFO level. + * + * This method allows to have an esay ZF compatibility. + * + * @param string $message The log message + * @return Boolean Whether the record has been processed + */ public function notice($message) { return $this->addRecord(self::INFO, $message); } + /** + * Adds a log record at the WARNING level. + * + * This method allows to have an esay ZF compatibility. + * + * @param string $message The log message + * @return Boolean Whether the record has been processed + */ public function warn($message) { return $this->addRecord(self::WARNING, $message); } + /** + * Adds a log record at the ERROR level. + * + * This method allows to have an esay ZF compatibility. + * + * @param string $message The log message + * @return Boolean Whether the record has been processed + */ public function err($message) { return $this->addRecord(self::ERROR, $message); } + /** + * Adds a log record at the ERROR level. + * + * This method allows to have an esay ZF compatibility. + * + * @param string $message The log message + * @return Boolean Whether the record has been processed + */ public function crit($message) { return $this->addRecord(self::ERROR, $message); } + /** + * Adds a log record at the ERROR level. + * + * This method allows to have an esay ZF compatibility. + * + * @param string $message The log message + * @return Boolean Whether the record has been processed + */ public function alert($message) { return $this->addRecord(self::ERROR, $message); } + /** + * Adds a log record at the ERROR level. + * + * This method allows to have an esay ZF compatibility. + * + * @param string $message The log message + * @return Boolean Whether the record has been processed + */ public function emerg($message) { return $this->addRecord(self::ERROR, $message); diff --git a/src/Monolog/Processor/WebProcessor.php b/src/Monolog/Processor/WebProcessor.php index 6bc94ebb..d999f2ee 100644 --- a/src/Monolog/Processor/WebProcessor.php +++ b/src/Monolog/Processor/WebProcessor.php @@ -11,6 +11,8 @@ namespace Monolog\Processor; +use Monolog\Handler\HandlerInterface; + /** * Injects url/method and remote IP of the current web request in all records * @@ -18,7 +20,12 @@ namespace Monolog\Processor; */ class WebProcessor { - public function __invoke($record, $handler) + /** + * @param array $record + * @param HandlerInterface $handler + * @return array + */ + public function __invoke(array $record, HandlerInterface $handler) { $record['extra'] = array_merge( $record['extra'], @@ -28,6 +35,7 @@ class WebProcessor 'method' => $_SERVER['REQUEST_METHOD'], ) ); + return $record; } }