Improve Logger docs and re-order the methods (#169)

Author: theofidry

src/Logger/Logger.php

@@ -19,8 +19,12 @@
 interface Logger
 {
     /**
+     * Logs the configuration before the start of the processing.
+     *
      * @param positive-int        $batchSize
      * @param 0|positive-int|null $numberOfItems
+     * @param string              $itemName      Name of the item; Already in the singular or plural
+     *                                           form.
      */
     public function logConfiguration(
         Configuration $configuration,
@@ -35,15 +39,33 @@ public function logConfiguration(
      */
     public function startProgress(?int $numberOfItems): void;
 
+    /**
+     * @param positive-int|0 $steps
+     */
     public function advance(int $steps = 1): void;
 
+    /**
+     * @param string $itemName Name of the item; Already in the singular or plural form.
+     */
     public function finish(string $itemName): void;
 
-    public function logUnexpectedOutput(string $buffer, string $progressSymbol): void;
+    public function logItemProcessingFailed(string $item, Throwable $throwable): void;
 
+    /**
+     * @param string $commandName Executed command for the child process.To not confuse
+     *                            with the Symfony command name which is just an element of
+     *                            the command.
+     */
     public function logCommandStarted(string $commandName): void;
 
     public function logCommandFinished(): void;
 
-    public function logItemProcessingFailed(string $item, Throwable $throwable): void;
+    /**
+     * Logs the "unexpected" child output. By unexpected is meant that the main
+     * process expects the child to output the progress symbol to communicate its
+     * progression. Any other sort of output is considered "unexpected".
+     *
+     * @param string $buffer Child process output.
+     */
+    public function logUnexpectedOutput(string $buffer, string $progressSymbol): void;
 }

src/Logger/NullLogger.php

@@ -43,7 +43,7 @@ public function finish(string $itemName): void
         // Do nothing.
     }
 
-    public function logUnexpectedOutput(string $buffer, string $progressSymbol): void
+    public function logItemProcessingFailed(string $item, Throwable $throwable): void
     {
         // Do nothing.
     }
@@ -58,7 +58,7 @@ public function logCommandFinished(): void
         // Do nothing.
     }
 
-    public function logItemProcessingFailed(string $item, Throwable $throwable): void
+    public function logUnexpectedOutput(string $buffer, string $progressSymbol): void
     {
         // Do nothing.
     }

src/Logger/StandardLogger.php

@@ -128,20 +128,14 @@ public function finish(string $itemName): void
         unset($this->progressBar);
     }
 
-    public function logUnexpectedOutput(string $buffer, string $progressSymbol): void
+    public function logItemProcessingFailed(string $item, Throwable $throwable): void
     {
-        $this->output->writeln('');
         $this->output->writeln(sprintf(
-            '<comment>%s</comment>',
-            str_pad(
-                ' Process Output ',
-                $this->terminalWidth,
-                '=',
-                STR_PAD_BOTH,
-            ),
+            "Failed to process \"%s\": %s\n%s",
+            $item,
+            $throwable->getMessage(),
+            $throwable->getTraceAsString(),
         ));
-        $this->output->writeln(str_replace($progressSymbol, '', $buffer));
-        $this->output->writeln('');
     }
 
     public function logCommandStarted(string $commandName): void
@@ -154,13 +148,19 @@ public function logCommandFinished(): void
         $this->logger->debug('Command finished');
     }
 
-    public function logItemProcessingFailed(string $item, Throwable $throwable): void
+    public function logUnexpectedOutput(string $buffer, string $progressSymbol): void
     {
+        $this->output->writeln('');
         $this->output->writeln(sprintf(
-            "Failed to process \"%s\": %s\n%s",
-            $item,
-            $throwable->getMessage(),
-            $throwable->getTraceAsString(),
+            '<comment>%s</comment>',
+            str_pad(
+                ' Process Output ',
+                $this->terminalWidth,
+                '=',
+                STR_PAD_BOTH,
+            ),
         ));
+        $this->output->writeln(str_replace($progressSymbol, '', $buffer));
+        $this->output->writeln('');
     }
 }

tests/Logger/DummyLogger.php

@@ -58,7 +58,7 @@ public function finish(string $itemName): void
         ];
     }
 
-    public function logUnexpectedOutput(string $buffer, string $progressSymbol): void
+    public function logItemProcessingFailed(string $item, Throwable $throwable): void
     {
         $this->records[] = [
             __FUNCTION__,
@@ -82,7 +82,7 @@ public function logCommandFinished(): void
         ];
     }
 
-    public function logItemProcessingFailed(string $item, Throwable $throwable): void
+    public function logUnexpectedOutput(string $buffer, string $progressSymbol): void
     {
         $this->records[] = [
             __FUNCTION__,

tests/Logger/FakeLogger.php

@@ -44,7 +44,7 @@ public function finish(string $itemName): void
         throw new DomainException('Unexpected call.');
     }
 
-    public function logUnexpectedOutput(string $buffer, string $progressSymbol): void
+    public function logItemProcessingFailed(string $item, Throwable $throwable): void
     {
         throw new DomainException('Unexpected call.');
     }
@@ -59,7 +59,7 @@ public function logCommandFinished(): void
         throw new DomainException('Unexpected call.');
     }
 
-    public function logItemProcessingFailed(string $item, Throwable $throwable): void
+    public function logUnexpectedOutput(string $buffer, string $progressSymbol): void
     {
         throw new DomainException('Unexpected call.');
     }