Added a new RestartableInterface and implemented it where possible.

When one use Monolog in a long process like an AMQP worker with a
`FingersCrossedHandler` or `BufferHandler` there is a drawback: as soon as there
is an AMQP message that generate a log >= error (for example), all next AMQP
messages will output logs, even if theses messages don't generate log where
level >= error.

In the same context there is a drawback for processor that add a Uid to the
logs. The UUID should change for each AMQP messages.

---

This patch address this issue with a new interface: `Restartable` interface.
Side note: `reset()`, `flush()`, `clear()`,  are already used in Monolog. So
basically, one can use the new `restart()` on the `Logger` and on some
`Processor`s.

It's especially useful for

* the `FingersCrossedHandler`: it `close()` the buffer, then it `clear()` the buffer.
* the `BufferHandler`: it `flush()` the buffer, then it `clear()` the buffer.
* the `UidProcessor`: it renew the `uid`.

CHANGELOG.md

@@ -1,3 +1,8 @@
+### 1.24.0
+
+  * Added a `RestartableInterface` in order to restart/clear/flush handler and processor
+    and implement it where possible
+
 ### 1.23.0 (2017-06-19)
 
   * Improved SyslogUdpHandler's support for RFC5424 and added optional `$ident` argument

src/Monolog/Handler/AbstractHandler.php

@@ -11,16 +11,17 @@
 
 namespace Monolog\Handler;
 
-use Monolog\Logger;
 use Monolog\Formatter\FormatterInterface;
 use Monolog\Formatter\LineFormatter;
+use Monolog\Logger;
+use Monolog\RestartableInterface;
 
 /**
  * Base Handler class providing the Handler structure
  *
  * @author Jordi Boggiano <j.boggiano@seld.be>
  */
-abstract class AbstractHandler implements HandlerInterface
+abstract class AbstractHandler implements HandlerInterface, RestartableInterface
 {
     protected $level = Logger::DEBUG;
     protected $bubble = true;
@@ -174,6 +175,17 @@ public function __destruct()
         }
     }
 
+    public function restart()
+    {
+        $this->close();
+
+        foreach ($this->processors as $processor) {
+            if ($processor instanceof RestartableInterface) {
+                $processor->restart();
+            }
+        }
+    }
+
     /**
      * Gets the default formatter.
      *

src/Monolog/Handler/AbstractProcessingHandler.php

@@ -11,6 +11,8 @@
 
 namespace Monolog\Handler;
 
+use Monolog\RestartableInterface;
+
 /**
  * Base Handler class providing the Handler structure
  *

src/Monolog/Handler/BufferHandler.php

@@ -12,6 +12,7 @@
 namespace Monolog\Handler;
 
 use Monolog\Logger;
+use Monolog\RestartableInterface;
 
 /**
  * Buffers all records until closing the handler and then pass them as batch.
@@ -114,4 +115,13 @@ public function clear()
         $this->bufferSize = 0;
         $this->buffer = array();
     }
+
+    public function restart()
+    {
+        parent::restart();
+
+        if ($this->handler instanceof RestartableInterface) {
+            $this->handler->restart();
+        }
+    }
 }

src/Monolog/Handler/FingersCrossedHandler.php

@@ -14,6 +14,7 @@
 use Monolog\Handler\FingersCrossed\ErrorLevelActivationStrategy;
 use Monolog\Handler\FingersCrossed\ActivationStrategyInterface;
 use Monolog\Logger;
+use Monolog\RestartableInterface;
 
 /**
  * Buffers all records until a certain level is reached
@@ -160,4 +161,15 @@ public function clear()
         $this->buffer = array();
         $this->reset();
     }
+
+    public function restart()
+    {
+        parent::restart();
+
+        $this->clear();
+
+        if ($this->handler instanceof RestartableInterface) {
+            $this->handler->restart();
+        }
+    }
 }

src/Monolog/Handler/GroupHandler.php

@@ -12,6 +12,7 @@
 namespace Monolog\Handler;
 
 use Monolog\Formatter\FormatterInterface;
+use Monolog\RestartableInterface;
 
 /**
  * Forwards records to multiple handlers
@@ -90,6 +91,17 @@ public function handleBatch(array $records)
         }
     }
 
+    public function restart()
+    {
+        parent::restart();
+
+        foreach ($this->handlers as $handler) {
+            if ($handler instanceof RestartableInterface) {
+                $handler->restart();
+            }
+        }
+    }
+
     /**
      * {@inheritdoc}
      */

src/Monolog/Handler/HandlerWrapper.php

@@ -11,6 +11,7 @@
 
 namespace Monolog\Handler;
 
+use Monolog\RestartableInterface;
 use Monolog\Formatter\FormatterInterface;
 
 /**
@@ -30,7 +31,7 @@
  *
  * @author Alexey Karapetov <alexey@karapetov.com>
  */
-class HandlerWrapper implements HandlerInterface
+class HandlerWrapper implements HandlerInterface, RestartableInterface
 {
     /**
      * @var HandlerInterface
@@ -105,4 +106,11 @@ public function getFormatter()
     {
         return $this->handler->getFormatter();
     }
+
+    public function restart()
+    {
+        if ($this->handler instanceof RestartableInterface) {
+            return $this->handler->restart();
+        }
+    }
 }

src/Monolog/Logger.php

@@ -24,7 +24,7 @@
  *
  * @author Jordi Boggiano <j.boggiano@seld.be>
  */
-class Logger implements LoggerInterface
+class Logger implements LoggerInterface, RestartableInterface
 {
     /**
      * Detailed debug information
@@ -344,6 +344,21 @@ public function addRecord($level, $message, array $context = array())
         return true;
     }
 
+    public function restart()
+    {
+        foreach ($this->handlers as $handler) {
+            if ($handler instanceof RestartableInterface) {
+                $handler->restart();
+            }
+        }
+
+        foreach ($this->processors as $processor) {
+            if ($processor instanceof RestartableInterface) {
+                $processor->restart();
+            }
+        }
+    }
+
     /**
      * Adds a log record at the DEBUG level.
      *

src/Monolog/Processor/UidProcessor.php

@@ -11,12 +11,14 @@
 
 namespace Monolog\Processor;
 
+use Monolog\RestartableInterface;
+
 /**
  * Adds a unique identifier into records
  *
  * @author Simon Mönch <sm@webfactory.de>
  */
-class UidProcessor
+class UidProcessor implements RestartableInterface
 {
     private $uid;
 
@@ -26,7 +28,8 @@ public function __construct($length = 7)
             throw new \InvalidArgumentException('The uid length must be an integer between 1 and 32');
         }
 
-        $this->uid = substr(hash('md5', uniqid('', true)), 0, $length);
+
+        $this->uid = $this->generateUid($length);
     }
 
     public function __invoke(array $record)
@@ -43,4 +46,14 @@ public function getUid()
     {
         return $this->uid;
     }
+
+    public function restart()
+    {
+        $this->uid = $this->generateUid(strlen($this->uid));
+    }
+
+    private function generateUid($length)
+    {
+        return substr(hash('md5', uniqid('', true)), 0, $length);
+    }
 }

src/Monolog/RestartableInterface.php

@@ -0,0 +1,25 @@
+<?php
+
+/*
+ * This file is part of the Monolog package.
+ *
+ * (c) Jordi Boggiano <j.boggiano@seld.be>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Monolog;
+
+/**
+ * Handler or Processor implementing this interface will be restarted when Logger::restart is called.
+ *
+ * Restarting an Handler or a Processor usually means cleaning all buffers or
+ * reseting in its internal state.
+ *
+ * @author Grégoire Pineau <lyrixx@lyrixx.info>
+ */
+interface RestartableInterface
+{
+    public function restart();
+}

tests/Monolog/LoggerTest.php

@@ -545,4 +545,76 @@ public function useMicrosecondTimestampsProvider()
             'without microseconds' => array(false, PHP_VERSION_ID >= 70100 ? 'assertNotSame' : 'assertSame'),
         );
     }
+
+    public function testRestart()
+    {
+        $logger = new Logger('app');
+
+        $testHandler = new Handler\TestHandler();
+        $bufferHandler = new Handler\BufferHandler($testHandler);
+        $groupHandler = new Handler\GroupHandler(array($bufferHandler));
+        $fingersCrossedHandler = new Handler\FingersCrossedHandler($groupHandler);
+
+        $logger->pushHandler($fingersCrossedHandler);
+
+        $processorUid1 = new Processor\UidProcessor(10);
+        $uid1 = $processorUid1->getUid();
+        $groupHandler->pushProcessor($processorUid1);
+
+        $processorUid2 = new Processor\UidProcessor(5);
+        $uid2 = $processorUid2->getUid();
+        $logger->pushProcessor($processorUid2);
+
+        $getProperty = function ($object, $property) {
+            $reflectionProperty = new \ReflectionProperty(get_class($object), $property);
+            $reflectionProperty->setAccessible(true);
+
+            return $reflectionProperty->getValue($object);
+        };
+        $assertBufferOfBufferHandlerEmpty = function () use ($getProperty, $bufferHandler) {
+            $this->assertEmpty($getProperty($bufferHandler, 'buffer'));
+        };
+        $assertBuffersEmpty = function() use ($assertBufferOfBufferHandlerEmpty, $getProperty, $fingersCrossedHandler) {
+            $assertBufferOfBufferHandlerEmpty();
+            $this->assertEmpty($getProperty($fingersCrossedHandler, 'buffer'));
+        };
+
+        $logger->debug('debug');
+        $logger->restart();
+        $assertBuffersEmpty();
+        $this->assertFalse($testHandler->hasDebugRecords());
+        $this->assertFalse($testHandler->hasErrorRecords());
+        $this->assertNotSame($uid1, $uid1 = $processorUid1->getUid());
+        $this->assertNotSame($uid2, $uid2 = $processorUid2->getUid());
+
+        $logger->debug('debug');
+        $logger->error('error');
+        $logger->restart();
+        $assertBuffersEmpty();
+        $this->assertTrue($testHandler->hasDebugRecords());
+        $this->assertTrue($testHandler->hasErrorRecords());
+        $this->assertNotSame($uid1, $uid1 = $processorUid1->getUid());
+        $this->assertNotSame($uid2, $uid2 = $processorUid2->getUid());
+
+        $logger->info('info');
+        $this->assertNotEmpty($getProperty($fingersCrossedHandler, 'buffer'));
+        $assertBufferOfBufferHandlerEmpty();
+        $this->assertFalse($testHandler->hasInfoRecords());
+
+        $logger->restart();
+        $assertBuffersEmpty();
+        $this->assertFalse($testHandler->hasInfoRecords());
+        $this->assertNotSame($uid1, $uid1 = $processorUid1->getUid());
+        $this->assertNotSame($uid2, $uid2 = $processorUid2->getUid());
+
+        $logger->notice('notice');
+        $logger->emergency('emergency');
+        $logger->restart();
+        $assertBuffersEmpty();
+        $this->assertFalse($testHandler->hasInfoRecords());
+        $this->assertTrue($testHandler->hasNoticeRecords());
+        $this->assertTrue($testHandler->hasEmergencyRecords());
+        $this->assertNotSame($uid1, $processorUid1->getUid());
+        $this->assertNotSame($uid2, $processorUid2->getUid());
+    }
 }