feature #57518 Unify how --format is handled by commands (fabpot)

This PR was merged into the 7.2 branch.

Discussion
----------

Unify how --format is handled by commands

| Q             | A
| ------------- | ---
| Branch?       | 7.2
| Bug fix?      | no
| New feature?  | yes <!-- please update src/**/CHANGELOG.md files -->
| Deprecations? | yes <!-- please update UPGRADE-*.md and src/**/CHANGELOG.md files -->
| Issues        | n/a <!-- prefix each issue number with "Fix #", no need to create an issue if none exists, explain below instead -->
| License       | MIT

We have many commands that have a `--format` option. This PR tries to unify the way we handle them:

* Deprecate the `text` format (used only twice) in favor of the more common `txt` one;
* Add auto-completion for `--format` in all commands;
* Add help about the `--format` option in all commands that supports it (in a unified way)

**Side note**: To avoid confusion, I think we should rename the `--format` option for the `uuid:generate` and `ulid:generate` commands as it does something different from the commonly used `--format` option.

Commits
-------

848f855cdf Unify how --format is handle by commands

Author: fabpot

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'];

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'];

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();

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();

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();