Add CLI arguments to control colors in the output

Author: rodrigoprimo

README.md

@@ -172,6 +172,8 @@ directories|files               One or more specific directories or files to exa
 --exclude=<dir1,dir2>           Comma-delimited list of relative paths of directories to
                                 exclude from the scan.
 --ignore-sniffs=<sniff1,sniff2> Comma-delimited list of sniffs to ignore.
+--colors                        Enable colors in console output. (disables auto detection of color support)
+--no-colors                     Disable colors in console output.
 --help                          Print the script help page.
 -V, --version                   Display the current version of this script.
 ```

Scripts/DocCodeExamples/Config.php

@@ -108,6 +108,14 @@ class Config
                 'arg'  => '-V, --version',
                 'desc' => 'Display the current version of this script.',
             ],
+            [
+                'arg'  => '--colors',
+                'desc' => 'Enable colors in console output. (disables auto detection of color support)',
+            ],
+            [
+                'arg'  => '--no-colors',
+                'desc' => 'Disable colors in console output.',
+            ],
         ],
         // phpcs:enable
     ];
@@ -123,6 +131,8 @@ class Config
         '--help',
         '-V',
         '--version',
+        '--colors',
+        '--no-colors',
     ];
 
     /**
@@ -132,8 +142,7 @@ class Config
      */
     public function __construct(Writer $writer)
     {
-        $this->writer      = $writer;
-        $this->showColored = HelpTextFormatter::isColorSupported();
+        $this->writer = $writer;
         $this->processCliCommand();
     }
 
@@ -182,6 +191,14 @@ private function processCliCommand()
 
         $argsFlipped = \array_flip($args);
 
+        if (isset($argsFlipped['--no-colors'])) {
+            $this->showColored = false;
+        } elseif (isset($argsFlipped['--colors'])) {
+            $this->showColored = true;
+        } else {
+            $this->showColored = HelpTextFormatter::isColorSupported();
+        }
+
         if (isset($argsFlipped['--help'])) {
             $helpText = HelpTextFormatter::format($this->helpTexts, $this->showColored);
             $this->writer->toStdout($this->getVersion());

Tests/DocCodeExamples/ConfigTest.php

@@ -12,6 +12,7 @@
 
 use PHPCSDevTools\Scripts\DocCodeExamples\Config;
 use PHPCSDevTools\Scripts\DocCodeExamples\Helper;
+use PHPCSDevTools\Scripts\Utils\HelpTextFormatter;
 use PHPCSDevTools\Tests\TestWriter;
 use Yoast\PHPUnitPolyfills\TestCases\XTestCase;
 
@@ -34,6 +35,7 @@ final class ConfigTest extends XTestCase
         'excludedDirs'  => [],
         'ignoredSniffs' => [],
         'executeCheck'  => true,
+        'showColored'   => null, // Defined in setUpPrerequisites() as the default value depends on the environment.
     ];
 
     /**
@@ -52,7 +54,8 @@ final class ConfigTest extends XTestCase
      */
     public function setUpPrerequisites()
     {
-        $this->writer = new TestWriter();
+        $this->writer                         = new TestWriter();
+        $this->defaultSettings['showColored'] = HelpTextFormatter::isColorSupported();
     }
 
     /**
@@ -350,6 +353,46 @@ public static function dataProcessCliCommand(): array
                     'executeCheck' => false,
                 ],
             ],
+            'Colors argument'                                                                            => [
+                'command'         => './phpcs-check-doc-examples --colors',
+                'expectedChanged' => [
+                    'projectRoot' => $projectRoot,
+                    'targetPaths' => [
+                        $projectRoot,
+                    ],
+                    'showColored' => true,
+                ],
+            ],
+            'No colors argument'                                                                         => [
+                'command'         => './phpcs-check-doc-examples --no-colors',
+                'expectedChanged' => [
+                    'projectRoot' => $projectRoot,
+                    'targetPaths' => [
+                        $projectRoot,
+                    ],
+                    'showColored' => false,
+                ],
+            ],
+            'Both colors and no-colors arguments (no-colors should win)'                                 => [
+                'command'         => './phpcs-check-doc-examples --no-colors --colors',
+                'expectedChanged' => [
+                    'projectRoot' => $projectRoot,
+                    'targetPaths' => [
+                        $projectRoot,
+                    ],
+                    'showColored' => false,
+                ],
+            ],
+            'Both colors and no-colors arguments in reverse order (no-colors should win)'                => [
+                'command'         => './phpcs-check-doc-examples --colors --no-colors',
+                'expectedChanged' => [
+                    'projectRoot' => $projectRoot,
+                    'targetPaths' => [
+                        $projectRoot,
+                    ],
+                    'showColored' => false,
+                ],
+            ],
         ];
 
         // Windows only test: verify that the paths are normalized to use forward slashes.

Tests/DocCodeExamples/EndToEndTest.php

@@ -97,7 +97,12 @@ public static function tearDownFixturesAfterClass()
     public function testScriptBasicExecution(string $cliArgs, int $expectedExitCode, string $expectedStdout, string $expectedStderr)
     {
         $scriptPath = self::maybeConvertDirectorySeparators(self::SCRIPT_PATH);
-        $command    = \sprintf(
+
+        // Force --no-colors to avoid issues with the tests as colors might be auto enabled or
+        // disabled depending on the environment.
+        $cliArgs .= ' --no-colors';
+
+        $command = \sprintf(
             'php %s %s',
             $scriptPath,
             $cliArgs