Unify how --format is handle by commands

fabpot · Jun 26, 2024 · 848f855 · 848f855
1 parent ce67e41
commit 848f855
Show file tree

Hide file tree

Showing 19 changed files with 107 additions and 32 deletions.
diff --git a/src/Symfony/Bridge/Twig/Command/DebugCommand.php b/src/Symfony/Bridge/Twig/Command/DebugCommand.php
@@ -57,7 +57,7 @@ protected function configure(): void
             ->setDefinition([
                 new InputArgument('name', InputArgument::OPTIONAL, 'The template name'),
                 new InputOption('filter', null, InputOption::VALUE_REQUIRED, 'Show details for all entries matching this filter'),
-                new InputOption('format', null, InputOption::VALUE_REQUIRED, \sprintf('The output format ("%s")', implode('", "', $this->getAvailableFormatOptions())), 'text'),
+                new InputOption('format', null, InputOption::VALUE_REQUIRED, \sprintf('The output format ("%s")', implode('", "', $this->getAvailableFormatOptions())), 'txt'),
             ])
             ->setHelp(<<<'EOF'
 The <info>%command.name%</info> command outputs a list of twig functions,
@@ -93,8 +93,14 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             throw new InvalidArgumentException(\sprintf('Argument "name" not supported, it requires the Twig loader "%s".', FilesystemLoader::class));
         }
 
-        match ($input->getOption('format')) {
-            'text' => $name ? $this->displayPathsText($io, $name) : $this->displayGeneralText($io, $filter),
+        $format = $input->getOption('format');
+        if ('text' === $format) {
+            trigger_deprecation('symfony/twig-bridge', '7.2', 'The "text" format is deprecated, use "txt" instead.');
+
+            $format = 'txt';
+        }
+        match ($format) {
+            'txt' => $name ? $this->displayPathsText($io, $name) : $this->displayGeneralText($io, $filter),
             'json' => $name ? $this->displayPathsJson($io, $name) : $this->displayGeneralJson($io, $filter),
             default => throw new InvalidArgumentException(\sprintf('Supported formats are "%s".', implode('", "', $this->getAvailableFormatOptions()))),
         };
@@ -582,8 +588,9 @@ private function getFileLink(string $absolutePath): string
         return (string) $this->fileLinkFormatter?->format($absolutePath, 1);
     }
 
+    /** @return string[] */
     private function getAvailableFormatOptions(): array
     {
-        return ['text', 'json'];
+        return ['txt', 'json'];
     }
 }
diff --git a/src/Symfony/Bridge/Twig/Command/LintCommand.php b/src/Symfony/Bridge/Twig/Command/LintCommand.php
@@ -71,8 +71,10 @@ protected function configure(): void
 Or of a whole directory:
 
   <info>php %command.full_name% dirname</info>
-  <info>php %command.full_name% dirname --format=json</info>
 
+The <info>--format</info> option specifies the format of the command output:
+
+  <info>php %command.full_name% dirname --format=json</info>
 EOF
             )
         ;
@@ -280,6 +282,7 @@ public function complete(CompletionInput $input, CompletionSuggestions $suggesti
         }
     }
 
+    /** @return string[] */
     private function getAvailableFormatOptions(): array
     {
         return ['txt', 'json', 'github'];

diff --git a/src/Symfony/Bridge/Twig/Tests/Command/DebugCommandTest.php b/src/Symfony/Bridge/Twig/Tests/Command/DebugCommandTest.php
@@ -314,7 +314,7 @@ public function testComplete(array $input, array $expectedSuggestions)
     public static function provideCompletionSuggestions(): iterable
     {
         yield 'name' => [['email'], []];
-        yield 'option --format' => [['--format', ''], ['text', 'json']];
+        yield 'option --format' => [['--format', ''], ['txt', 'json']];
     }
 
     private function createCommandTester(array $paths = [], array $bundleMetadata = [], ?string $defaultPath = null, bool $useChainLoader = false, array $globals = []): CommandTester

diff --git a/src/Symfony/Bridge/Twig/composer.json b/src/Symfony/Bridge/Twig/composer.json
@@ -17,6 +17,7 @@
     ],
     "require": {
         "php": ">=8.2",
+        "symfony/deprecation-contracts": "^2.5|^3",
         "symfony/translation-contracts": "^2.5|^3",
         "twig/twig": "^3.9"
     },

diff --git a/src/Symfony/Bundle/FrameworkBundle/Command/ConfigDebugCommand.php b/src/Symfony/Bundle/FrameworkBundle/Command/ConfigDebugCommand.php
@@ -41,9 +41,6 @@ class ConfigDebugCommand extends AbstractConfigCommand
 {
     protected function configure(): void
     {
-        $commentedHelpFormats = array_map(fn ($format) => \sprintf('<comment>%s</comment>', $format), $this->getAvailableFormatOptions());
-        $helpFormats = implode('", "', $commentedHelpFormats);
-
         $this
             ->setDefinition([
                 new InputArgument('name', InputArgument::OPTIONAL, 'The bundle name or the extension alias'),
@@ -60,8 +57,7 @@ protected function configure(): void
   <info>php %command.full_name% framework</info>
   <info>php %command.full_name% FrameworkBundle</info>
 
-The <info>--format</info> option specifies the format of the configuration,
-these are "{$helpFormats}".
+The <info>--format</info> option specifies the format of the command output:
 
   <info>php %command.full_name% framework --format=json</info>
 
@@ -268,6 +264,7 @@ private static function buildPathsCompletion(array $paths, string $prefix = ''):
         return $completionPaths;
     }
 
+    /** @return string[] */
     private function getAvailableFormatOptions(): array
     {
         return ['txt', 'yaml', 'json'];

diff --git a/src/Symfony/Bundle/FrameworkBundle/Command/ConfigDumpReferenceCommand.php b/src/Symfony/Bundle/FrameworkBundle/Command/ConfigDumpReferenceCommand.php
@@ -39,9 +39,6 @@ class ConfigDumpReferenceCommand extends AbstractConfigCommand
 {
     protected function configure(): void
     {
-        $commentedHelpFormats = array_map(fn ($format) => \sprintf('<comment>%s</comment>', $format), $this->getAvailableFormatOptions());
-        $helpFormats = implode('", "', $commentedHelpFormats);
-
         $this
             ->setDefinition([
                 new InputArgument('name', InputArgument::OPTIONAL, 'The Bundle name or the extension alias'),
@@ -57,10 +54,9 @@ protected function configure(): void
   <info>php %command.full_name% framework</info>
   <info>php %command.full_name% FrameworkBundle</info>
 
-The <info>--format</info> option specifies the format of the configuration,
-these are "{$helpFormats}".
+The <info>--format</info> option specifies the format of the command output:
 
-  <info>php %command.full_name% FrameworkBundle --format=xml</info>
+  <info>php %command.full_name% FrameworkBundle --format=json</info>
 
 For dumping a specific option, add its path as second argument (only available for the yaml format):
 
@@ -181,6 +177,7 @@ private function getAvailableBundles(): array
         return $bundles;
     }
 
+    /** @return string[] */
     private function getAvailableFormatOptions(): array
     {
         return ['yaml', 'xml'];

diff --git a/src/Symfony/Bundle/FrameworkBundle/Command/ContainerDebugCommand.php b/src/Symfony/Bundle/FrameworkBundle/Command/ContainerDebugCommand.php
@@ -106,6 +106,9 @@ protected function configure(): void
 
   <info>php %command.full_name% --show-hidden</info>
 
+The <info>--format</info> option specifies the format of the command output:
+
+  <info>php %command.full_name% --format=json</info>
 EOF
             )
         ;
@@ -358,6 +361,7 @@ public function filterToServiceTypes(string $serviceId): bool
         return class_exists($serviceId) || interface_exists($serviceId, false);
     }
 
+    /** @return string[] */
     private function getAvailableFormatOptions(): array
     {
         return (new DescriptorHelper())->getFormats();

diff --git a/src/Symfony/Bundle/FrameworkBundle/Command/EventDispatcherDebugCommand.php b/src/Symfony/Bundle/FrameworkBundle/Command/EventDispatcherDebugCommand.php
@@ -60,6 +60,10 @@ protected function configure(): void
 To get specific listeners for an event, specify its name:
 
   <info>php %command.full_name% kernel.request</info>
+
+The <info>--format</info> option specifies the format of the command output:
+
+  <info>php %command.full_name% --format=json</info>
 EOF
             )
         ;
@@ -153,6 +157,7 @@ private function searchForEvent(EventDispatcherInterface $dispatcher, string $ne
         return $output;
     }
 
+    /** @return string[] */
     private function getAvailableFormatOptions(): array
     {
         return (new DescriptorHelper())->getFormats();

diff --git a/src/Symfony/Bundle/FrameworkBundle/Command/RouterDebugCommand.php b/src/Symfony/Bundle/FrameworkBundle/Command/RouterDebugCommand.php
@@ -61,6 +61,9 @@ protected function configure(): void
 
   <info>php %command.full_name%</info>
 
+The <info>--format</info> option specifies the format of the command output:
+
+  <info>php %command.full_name% --format=json</info>
 EOF
             )
         ;
@@ -164,6 +167,7 @@ private function findRouteContaining(string $name, RouteCollection $routes): Rou
         return $foundRoutes;
     }
 
+    /** @return string[] */
     private function getAvailableFormatOptions(): array
     {
         return (new DescriptorHelper())->getFormats();

diff --git a/src/Symfony/Component/AssetMapper/Command/ImportMapAuditCommand.php b/src/Symfony/Component/AssetMapper/Command/ImportMapAuditCommand.php
@@ -15,6 +15,8 @@
 use Symfony\Component\AssetMapper\ImportMap\ImportMapPackageAuditVulnerability;
 use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Completion\CompletionInput;
+use Symfony\Component\Console\Completion\CompletionSuggestions;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
@@ -41,12 +43,19 @@ public function __construct(
 
     protected function configure(): void
     {
-        $this->addOption(
-            name: 'format',
-            mode: InputOption::VALUE_REQUIRED,
-            description: \sprintf('The output format ("%s")', implode(', ', $this->getAvailableFormatOptions())),
-            default: 'txt',
-        );
+        $this
+            ->addOption(
+                name: 'format',
+                mode: InputOption::VALUE_REQUIRED,
+                description: \sprintf('The output format ("%s")', implode(', ', $this->getAvailableFormatOptions())),
+                default: 'txt',
+            )
+            ->setHelp(<<<'EOT'
+The <info>--format</info> option specifies the format of the command output:
+
+  <info>php %command.full_name% --format=json</info>
+EOT
+            );
     }
 
     protected function initialize(InputInterface $input, OutputInterface $output): void
@@ -180,6 +189,14 @@ private function displayJson(array $audit): int
         return 0 < array_sum($json['summary']) ? self::FAILURE : self::SUCCESS;
     }
 
+    public function complete(CompletionInput $input, CompletionSuggestions $suggestions): void
+    {
+        if ($input->mustSuggestOptionValuesFor('format')) {
+            $suggestions->suggestValues($this->getAvailableFormatOptions());
+        }
+    }
+
+    /** @return string[] */
     private function getAvailableFormatOptions(): array
     {
         return ['txt', 'json'];

diff --git a/src/Symfony/Component/AssetMapper/Command/ImportMapOutdatedCommand.php b/src/Symfony/Component/AssetMapper/Command/ImportMapOutdatedCommand.php
@@ -15,6 +15,8 @@
 use Symfony\Component\AssetMapper\ImportMap\PackageUpdateInfo;
 use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Completion\CompletionInput;
+use Symfony\Component\Console\Completion\CompletionSuggestions;
 use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
@@ -59,6 +61,10 @@ protected function configure(): void
 Or specific packages only:
 
    <info>php %command.full_name% <packages></info>
+
+The <info>--format</info> option specifies the format of the command output:
+
+  <info>php %command.full_name% --format=json</info>
 EOT
             );
     }
@@ -99,6 +105,14 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         return Command::FAILURE;
     }
 
+    public function complete(CompletionInput $input, CompletionSuggestions $suggestions): void
+    {
+        if ($input->mustSuggestOptionValuesFor('format')) {
+            $suggestions->suggestValues($this->getAvailableFormatOptions());
+        }
+    }
+
+    /** @return string[] */
     private function getAvailableFormatOptions(): array
     {
         return ['txt', 'json'];

diff --git a/src/Symfony/Component/Form/Command/DebugCommand.php b/src/Symfony/Component/Form/Command/DebugCommand.php
@@ -272,6 +272,7 @@ private function completeOptions(string $class, CompletionSuggestions $suggestio
         $suggestions->suggestValues($resolvedType->getOptionsResolver()->getDefinedOptions());
     }
 
+    /** @return string[] */
     private function getAvailableFormatOptions(): array
     {
         return (new DescriptorHelper())->getFormats();

diff --git a/src/Symfony/Component/Messenger/Command/StatsCommand.php b/src/Symfony/Component/Messenger/Command/StatsCommand.php
@@ -14,6 +14,8 @@
 use Psr\Container\ContainerInterface;
 use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Completion\CompletionInput;
+use Symfony\Component\Console\Completion\CompletionSuggestions;
 use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
@@ -38,10 +40,9 @@ public function __construct(
 
     protected function configure(): void
     {
-        $outputFormats = implode(', ', $this->getAvailableFormatOptions());
         $this
             ->addArgument('transport_names', InputArgument::IS_ARRAY | InputArgument::OPTIONAL, 'List of transports\' names')
-            ->addOption('format', '', InputOption::VALUE_REQUIRED, 'The output format, e.g.: '.$outputFormats, 'text', $this->getAvailableFormatOptions())
+            ->addOption('format', '', InputOption::VALUE_REQUIRED, \sprintf('The output format ("%s")', implode('", "', $this->getAvailableFormatOptions())), 'txt')
             ->setHelp(<<<EOF
 The <info>%command.name%</info> command counts the messages for all the transports:
 
@@ -51,8 +52,7 @@ protected function configure(): void
 
     <info>php %command.full_name% <transportNames></info>
 
-The <info>--format</info> option specifies the format of command output,
-these are "{$outputFormats}".
+The <info>--format</info> option specifies the format of the command output:
 
   <info>php %command.full_name% --format=json</info>
 EOF
@@ -65,6 +65,11 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $io = new SymfonyStyle($input, $output instanceof ConsoleOutputInterface ? $output->getErrorOutput() : $output);
 
         $format = $input->getOption('format');
+        if ('text' === $format) {
+            trigger_deprecation('symfony/messenger', '7.2', 'The "text" format is deprecated, use "txt" instead.');
+
+            $format = 'txt';
+        }
         if (!\in_array($format, $this->getAvailableFormatOptions(), true)) {
             throw new InvalidArgumentException('Invalid output format.');
         }
@@ -94,7 +99,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         }
 
         match ($format) {
-            'text' => $this->outputText($io, $outputTable, $uncountableTransports),
+            'txt' => $this->outputText($io, $outputTable, $uncountableTransports),
             'json' => $this->outputJson($io, $outputTable, $uncountableTransports),
         };
 
@@ -127,14 +132,21 @@ private function outputJson(SymfonyStyle $io, array $outputTable, array $uncount
     private function formatSupportsWarnings(string $format): bool
     {
         return match ($format) {
-            'text' => true,
+            'txt' => true,
             'json' => false,
         };
     }
 
+    public function complete(CompletionInput $input, CompletionSuggestions $suggestions): void
+    {
+        if ($input->mustSuggestOptionValuesFor('format')) {
+            $suggestions->suggestValues($this->getAvailableFormatOptions());
+        }
+    }
+
     /** @return string[] */
     private function getAvailableFormatOptions(): array
     {
-        return ['text', 'json'];
+        return ['txt', 'json'];
     }
 }
diff --git a/src/Symfony/Component/Messenger/composer.json b/src/Symfony/Component/Messenger/composer.json
@@ -18,7 +18,8 @@
     "require": {
         "php": ">=8.2",
         "psr/log": "^1|^2|^3",
-        "symfony/clock": "^6.4|^7.0"
+        "symfony/clock": "^6.4|^7.0",
+        "symfony/deprecation-contracts": "^2.5|^3"
     },
     "require-dev": {
         "psr/cache": "^1.0|^2.0|^3.0",

diff --git a/src/Symfony/Component/Translation/Command/XliffLintCommand.php b/src/Symfony/Component/Translation/Command/XliffLintCommand.php
@@ -72,6 +72,9 @@ protected function configure(): void
 Or of a whole directory:
 
   <info>php %command.full_name% dirname</info>
+
+The <info>--format</info> option specifies the format of the command output:
+
   <info>php %command.full_name% dirname --format=json</info>
 
 EOF
@@ -277,6 +280,7 @@ public function complete(CompletionInput $input, CompletionSuggestions $suggesti
         }
     }
 
+    /** @return string[] */
     private function getAvailableFormatOptions(): array
     {
         return ['txt', 'json', 'github'];

diff --git a/src/Symfony/Component/Translation/Tests/Command/XliffLintCommandTest.php b/src/Symfony/Component/Translation/Tests/Command/XliffLintCommandTest.php
@@ -136,8 +136,10 @@ public function testGetHelp()
 Or of a whole directory:
 
   <info>php %command.full_name% dirname</info>
-  <info>php %command.full_name% dirname --format=json</info>
 
+The <info>--format</info> option specifies the format of the command output:
+
+  <info>php %command.full_name% dirname --format=json</info>
 EOF;
 
         $this->assertStringContainsString($expected, $command->getHelp());