Use colors when outputting information

Author: rodrigoprimo

Scripts/DocCodeExamples/Check.php

@@ -137,7 +137,13 @@ public function run(): int
         $validationFailedCount = 0;
 
         if (empty($this->xmlFiles)) {
-            $this->writer->toStderr('ERROR: No XML documentation files found.');
+            $message = 'ERROR: No XML documentation files found.';
+
+            if ($this->config->getProperty('showColored') === true) {
+                $message = "\033[31m$message\033[0m";
+            }
+
+            $this->writer->toStderr($message . PHP_EOL);
             return 1;
         }
 
@@ -164,13 +170,21 @@ public function run(): int
         }
 
         if ($exitCode === 0) {
-            $feedback .= ' All code examples are valid.' . PHP_EOL;
-            $this->writer->toStdout($feedback);
+            $feedback .= ' All code examples are valid.';
+
+            if ($this->config->getProperty('showColored') === true) {
+                $feedback = "\033[32m{$feedback}\033[0m";
+            }
         } else {
-            $feedback .= " Found incorrect code examples in {$validationFailedCount}." . PHP_EOL;
-            $this->writer->toStdout($feedback);
+            $feedback .= " Found incorrect code examples in {$validationFailedCount}.";
+
+            if ($this->config->getProperty('showColored') === true) {
+                $feedback = "\033[31m{$feedback}\033[0m";
+            }
         }
 
+        $this->writer->toStdout($feedback . PHP_EOL);
+
         return $exitCode;
     }
 
@@ -187,7 +201,8 @@ protected function getXmlDocValidator(string $xmlDocFilePath): XmlDocValidator
             $this->config->getProperty('projectRoot') . $xmlDocFilePath,
             $this->extractor,
             $this->phpcsConfig,
-            $this->writer
+            $this->writer,
+            $this->config
         );
     }
 }

Scripts/DocCodeExamples/Config.php

@@ -67,6 +67,15 @@ class Config
      */
     protected $executeCheck = true;
 
+    /**
+     * Whether or not to show colored output.
+     *
+     * This is automatically detected.
+     *
+     * @var bool
+     */
+    protected $showColored;
+
     /**
      * Help texts.
      *
@@ -123,7 +132,8 @@ class Config
      */
     public function __construct(Writer $writer)
     {
-        $this->writer = $writer;
+        $this->writer      = $writer;
+        $this->showColored = HelpTextFormatter::isColorSupported();
         $this->processCliCommand();
     }
 
@@ -173,7 +183,7 @@ private function processCliCommand()
         $argsFlipped = \array_flip($args);
 
         if (isset($argsFlipped['--help'])) {
-            $helpText = HelpTextFormatter::format($this->helpTexts, HelpTextFormatter::isColorSupported());
+            $helpText = HelpTextFormatter::format($this->helpTexts, $this->showColored);
             $this->writer->toStdout($this->getVersion());
             $this->writer->toStdout($helpText);
             $this->executeCheck = false;

Scripts/DocCodeExamples/XmlDocValidator.php

@@ -73,6 +73,13 @@ class XmlDocValidator
      */
     private $writer;
 
+    /**
+     * Configuration as passed on the command line.
+     *
+     * @var \PHPCSDevTools\Scripts\DocCodeExamples\Config
+     */
+    private $config;
+
     /**
      * Whether the first error message for this XML file has been displayed or not. Used to control
      * when to display a header for the error messages with the XML file name.
@@ -88,6 +95,7 @@ class XmlDocValidator
      * @param CodeBlocksExtractor $extractor   CodeBlocksExtractor instance.
      * @param PHPCSConfig         $phpcsConfig PHPCS configuration object.
      * @param Writer              $writer      A helper object to write output.
+     * @param Config              $config      Configuration as passed on the command line.
      *
      * @throws \RuntimeException If the XML file doesn't exist, the file name or directory structure
      *                           is invalid, or the standard is not installed in PHPCS.
@@ -96,7 +104,8 @@ public function __construct(
         string $xmlDocFile,
         CodeBlocksExtractor $extractor,
         PHPCSConfig $phpcsConfig,
-        Writer $writer
+        Writer $writer,
+        Config $config
     ) {
         if (!\file_exists($xmlDocFile)) {
             throw new \RuntimeException("The XML file \"{$xmlDocFile}\" does not exist.");
@@ -105,12 +114,13 @@ public function __construct(
         $this->extractor   = $extractor;
         $this->phpcsConfig = $phpcsConfig;
         $this->writer      = $writer;
+        $this->config      = $config;
         $this->path        = $xmlDocFile;
         $pathInfo          = \pathinfo($this->path);
 
         if (\substr($pathInfo['basename'], -12) !== 'Standard.xml') {
             throw new \RuntimeException(
-                "The XML file \"{$pathInfo['basename']}\" is invalid. File names should end in \"Standard.xml\"."
+                "ERROR: The XML file \"{$pathInfo['basename']}\" is invalid. File names should end in \"Standard.xml\"."
             );
         }
 
@@ -119,7 +129,7 @@ public function __construct(
 
         if (\count($dirs) < 3 || $dirs[\count($dirs) - 2] !== 'Docs') {
             throw new \RuntimeException(
-                'Invalid directory structure in the XML file path. Expected: '
+                'ERROR: Invalid directory structure in the XML file path. Expected: '
                 . '{STANDARD_NAME}/Docs/{CATEGORY_NAME}/' . $pathInfo['basename'] . '.'
             );
         }
@@ -130,7 +140,7 @@ public function __construct(
 
         if (Standards::isInstalledStandard($this->standard) === false) {
             throw new \RuntimeException(
-                "The standard \"{$this->standard}\" is not installed in PHPCS."
+                "ERROR: The standard \"{$this->standard}\" is not installed in PHPCS."
             );
         }
     }
@@ -230,7 +240,7 @@ private function verifyCodeBlock(CodeBlock $codeBlock, bool $isExpectedToBeValid
             // @phpstan-ignore function.resultUnused (maybe a PHPStan false positive?)
             \token_get_all($codeBlockContent, \TOKEN_PARSE);
         } catch (\Throwable $e) {
-            $message  = 'ERROR: There is a syntax error in the code block.' . \PHP_EOL;
+            $message  = 'There is a syntax error in the code block.' . \PHP_EOL;
             $message .= $e->getMessage() . \PHP_EOL;
             $this->displayErrorMessage(
                 $this->prepareCodeBlockErrorMessage($message, $codeBlock)
@@ -248,7 +258,7 @@ private function verifyCodeBlock(CodeBlock $codeBlock, bool $isExpectedToBeValid
         $file->process();
 
         if ($isExpectedToBeValid === true && ($file->getErrorCount() !== 0 || $file->getWarningCount() !== 0)) {
-            $message = 'ERROR: Code block is valid and PHPCS should have returned nothing, ' .
+            $message = 'Code block is valid and PHPCS should have returned nothing, ' .
                        'but instead it returned an error.';
             $this->displayErrorMessage(
                 $this->prepareCodeBlockErrorMessage($message, $codeBlock)
@@ -257,7 +267,7 @@ private function verifyCodeBlock(CodeBlock $codeBlock, bool $isExpectedToBeValid
         }
 
         if ($isExpectedToBeValid === false && ($file->getErrorCount() === 0 && $file->getWarningCount() === 0)) {
-            $message = 'ERROR: Code block is invalid and PHPCS should have returned an error message, ' .
+            $message = 'Code block is invalid and PHPCS should have returned an error message, ' .
                        'but instead it returned nothing.';
             $this->displayErrorMessage(
                 $this->prepareCodeBlockErrorMessage($message, $codeBlock)
@@ -278,7 +288,13 @@ private function verifyCodeBlock(CodeBlock $codeBlock, bool $isExpectedToBeValid
      */
     private function prepareCodeBlockErrorMessage(string $message, CodeBlock $codeBlock): string
     {
-        $errorMessage  = $message . \PHP_EOL;
+        $errorPrefix = 'ERROR: ';
+
+        if ($this->config->getProperty('showColored') === true) {
+            $errorPrefix = "\033[31m{$errorPrefix}\033[0m";
+        }
+
+        $errorMessage  = $errorPrefix . $message . \PHP_EOL;
         $errorMessage .= "Code block title: \"{$codeBlock->title}\"" . \PHP_EOL;
         $errorMessage .= "Code block content: \"{$codeBlock->content}\"" . \PHP_EOL;
 
@@ -296,7 +312,13 @@ private function prepareCodeBlockErrorMessage(string $message, CodeBlock $codeBl
     private function displayErrorMessage(string $message)
     {
         if ($this->firstErrorMessageDisplayed === false) {
-            $this->writer->toStderr("Errors found while processing {$this->path}" . \PHP_EOL . \PHP_EOL);
+            $errorHeader = "Errors found while processing {$this->path}";
+
+            if ($this->config->getProperty('showColored') === true) {
+                $errorHeader = "\033[31m{$errorHeader}\033[0m";
+            }
+
+            $this->writer->toStderr($errorHeader . \PHP_EOL . \PHP_EOL);
         }
 
         $this->firstErrorMessageDisplayed = true;