[Console] Add of hidden and deprecation option flags

symfony · flkasper · Mar 25, 2024 · Mar 29, 2024 · Mar 31, 2024 · Apr 6, 2024
commit 2cf5da95e0ee185d104dc7d0128021f130e58f2f
diff --git a/src/Symfony/Component/Console/.editorconfig b/src/Symfony/Component/Console/.editorconfig
@@ -0,0 +1,7 @@
+; Unix-style newlines
+[Tests/Fixtures/*.{json,md,rst,txt}]
+trim_trailing_whitespace = false
+
+[Tests/Fixtures/*.xml]
+trim_trailing_whitespace = false
+indent_size = 2
@@ -11,6 +11,8 @@ CHANGELOG
 ---

 * Add `ArgvInput::getRawTokens()`
+ * Add `InputOption::HIDDEN` flag to hide options
+ * Add `InputOption::DEPRECATED` flag to mark options as deprecated

 7.0
 ---

@@ -235,7 +235,8 @@ public function run(InputInterface $input, OutputInterface $output): int

        // bind the input against the command specific arguments/options
        try {
-            $input->bind($this->getDefinition());
+            $inputDefinition = $this->getDefinition();
+            $input->bind($inputDefinition);
        } catch (ExceptionInterface $e) {
            if (!$this->ignoreValidationErrors) {
                throw $e;
@@ -273,6 +274,10 @@ public function run(InputInterface $input, OutputInterface $output): int

        $input->validate();

+        if (isset($inputDefinition)) {
-        if (isset($inputDefinition)) {
+        if ($inputDefinition) {
-        if (isset($inputDefinition)) {
+        if ($inputDefinition) {
+            $this->printDeprecationMessages($inputDefinition, $input, $output);
+        }
+
        if ($this->code) {
            $statusCode = ($this->code)($input, $output);
        } else {
@@ -648,6 +653,28 @@ public function getHelper(string $name): HelperInterface
        return $this->helperSet->get($name);
    }

+    private function printDeprecationMessages(InputDefinition $inputDefinition, InputInterface $input, OutputInterface $output): void
+    {
+        $deprecationMessages = [];
+        foreach ($inputDefinition->getOptions() as $inputOption) {
+            if ($inputOption->isDeprecated()) {
+                try {
+                    $optionName = $inputOption->getName();
+                    $optionValue = $input->getOption($optionName);
+                    if (isset($optionValue) && $optionValue !== $inputOption->getDefault()) {
+                        $deprecationMessages[] = sprintf('The option "--%s" is deprecated.', $optionName);
+                    }
+                } catch (\InvalidArgumentException $exception) {
+                    // option not used, ignore
+                }
+            }
+        }
+        if (!empty($deprecationMessages)) {
+            $formatter = $this->getHelper('formatter');
+            $output->writeln($formatter->formatBlock($deprecationMessages, 'fg=black;bg=yellow', true));
+        }
+    }
+
    /**
     * Validates a command name.
     *

@@ -37,6 +37,7 @@ protected function configure(): void
                new InputArgument('command_name', InputArgument::OPTIONAL, 'The command name', 'help', fn () => array_keys((new ApplicationDescription($this->getApplication()))->getCommands())),
                new InputOption('format', null, InputOption::VALUE_REQUIRED, 'The output format (txt, xml, json, or md)', 'txt', fn () => (new DescriptorHelper())->getFormats()),
                new InputOption('raw', null, InputOption::VALUE_NONE, 'To output raw command help'),
+                new InputOption('show-hidden-options', null, InputOption::VALUE_NONE | InputOption::HIDDEN, 'Show hidden options'),
            ])
            ->setDescription('Display help for a command')
            ->setHelp(<<<'EOF'
@@ -67,6 +68,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
        $helper->describe($output, $this->command, [
            'format' => $input->getOption('format'),
            'raw_text' => $input->getOption('raw'),
+            'show-hidden-options' => $input->getOption('show-hidden-options'),
        ]);

        unset($this->command);

@@ -198,11 +198,17 @@ private function getOptionFromToken(string $optionToken): ?InputOption

        if ('-' === ($optionToken[1] ?? ' ')) {
            // long option name
-            return $this->definition->hasOption($optionName) ? $this->definition->getOption($optionName) : null;
+            if ($this->definition->hasOption($optionName) && !$this->definition->getOption($optionName)->isHidden()) {
+                return $this->definition->getOption($optionName);
+            }
+            return null;
        }

        // short option name
-        return $this->definition->hasShortcut($optionName[0]) ? $this->definition->getOptionForShortcut($optionName[0]) : null;
+        if ($this->definition->hasShortcut($optionName[0]) && !$this->definition->getOptionForShortcut($optionName[0])->isHidden()) {
+            return $this->definition->getOptionForShortcut($optionName[0]);
+        }
+        return null;
    }

    /**

@@ -58,7 +58,9 @@ public function suggestValues(array $values): static
     */
    public function suggestOption(InputOption $option): static
    {
-        $this->optionSuggestions[] = $option;
+        if (!$option->isHidden()) {
+            $this->optionSuggestions[] = $option;
+        }

        return $this;
    }

@@ -42,6 +42,24 @@ public function describe(OutputInterface $output, object $object, array $options
        };
    }

+    /**
+     * Filter hidden options from list.
+     * @param array<string,InputOption> $inputOptions
+     * @return array<string,InputOption>
+     */
+    protected function removeHiddenOptions(array $inputOptions, array $options = []): array
+    {
+        return array_filter($inputOptions, fn(InputOption $option) => !$this->skipHiddenOption($option, $options));
+    }
+
+    /**
+     * Should InputOption be skipped?
+     */
+    protected function skipHiddenOption(InputOption $inputOption, array $options = []): bool
+    {
+        return $inputOption->isHidden() && !($options['show-hidden-options'] ?? false);
+    }
+
    protected function write(string $content, bool $decorated = false): void
    {
        $this->output->write($content, false, $decorated ? OutputInterface::OUTPUT_NORMAL : OutputInterface::OUTPUT_RAW);

@@ -33,6 +33,9 @@ protected function describeInputArgument(InputArgument $argument, array $options

    protected function describeInputOption(InputOption $option, array $options = []): void
    {
+        if ($this->skipHiddenOption($option, $options)) {
+            return;
+        }
        $this->writeData($this->getInputOptionData($option), $options);
        if ($option->isNegatable()) {
            $this->writeData($this->getInputOptionData($option, true), $options);
@@ -41,12 +44,12 @@ protected function describeInputOption(InputOption $option, array $options = [])

    protected function describeInputDefinition(InputDefinition $definition, array $options = []): void
    {
-        $this->writeData($this->getInputDefinitionData($definition), $options);
+        $this->writeData($this->getInputDefinitionData($definition, $options), $options);
    }

    protected function describeCommand(Command $command, array $options = []): void
    {
-        $this->writeData($this->getCommandData($command, $options['short'] ?? false), $options);
+        $this->writeData($this->getCommandData($command, $options), $options);
    }

    protected function describeApplication(Application $application, array $options = []): void
@@ -56,7 +59,7 @@ protected function describeApplication(Application $application, array $options
        $commands = [];

        foreach ($description->getCommands() as $command) {
-            $commands[] = $this->getCommandData($command, $options['short'] ?? false);
+            $commands[] = $this->getCommandData($command, $options);
        }

        $data = [];
@@ -101,34 +104,40 @@ private function getInputArgumentData(InputArgument $argument): array

    private function getInputOptionData(InputOption $option, bool $negated = false): array
    {
-        return $negated ? [
-            'name' => '--no-'.$option->getName(),
+        $data = $negated ? [
+            'name' => '--no-' . $option->getName(),
            'shortcut' => '',
            'accept_value' => false,
            'is_value_required' => false,
            'is_multiple' => false,
-            'description' => 'Negate the "--'.$option->getName().'" option',
+            'is_deprecated' => $option->isDeprecated(),
+            'description' => 'Negate the "--' . $option->getName() . '" option',
            'default' => false,
        ] : [
-            'name' => '--'.$option->getName(),
-            'shortcut' => $option->getShortcut() ? '-'.str_replace('|', '|-', $option->getShortcut()) : '',
+            'name' => '--' . $option->getName(),
+            'shortcut' => $option->getShortcut() ? '-' . str_replace('|', '|-', $option->getShortcut()) : '',
            'accept_value' => $option->acceptValue(),
            'is_value_required' => $option->isValueRequired(),
            'is_multiple' => $option->isArray(),
+            'is_deprecated' => $option->isDeprecated(),
            'description' => preg_replace('/\s*[\r\n]\s*/', ' ', $option->getDescription()),
            'default' => \INF === $option->getDefault() ? 'INF' : $option->getDefault(),
        ];
+        if (!$option->isDeprecated()) {
+            unset($data['is_deprecated']);
+        }
+        return $data;
    }

-    private function getInputDefinitionData(InputDefinition $definition): array
+    private function getInputDefinitionData(InputDefinition $definition, array $options): array
    {
        $inputArguments = [];
        foreach ($definition->getArguments() as $name => $argument) {
            $inputArguments[$name] = $this->getInputArgumentData($argument);
        }

        $inputOptions = [];
-        foreach ($definition->getOptions() as $name => $option) {
+        foreach ($this->removeHiddenOptions($definition->getOptions(), $options) as $name => $option) {
            $inputOptions[$name] = $this->getInputOptionData($option);
            if ($option->isNegatable()) {
                $inputOptions['no-'.$name] = $this->getInputOptionData($option, true);
@@ -138,8 +147,10 @@ private function getInputDefinitionData(InputDefinition $definition): array
        return ['arguments' => $inputArguments, 'options' => $inputOptions];
    }

-    private function getCommandData(Command $command, bool $short = false): array
+    private function getCommandData(Command $command, array $options = []): array
    {
+        $short = $options['short'] ?? false;
+
        $data = [
            'name' => $command->getName(),
            'description' => $command->getDescription(),
@@ -155,7 +166,7 @@ private function getCommandData(Command $command, bool $short = false): array
            $data += [
                'usage' => array_merge([$command->getSynopsis()], $command->getUsages(), $command->getAliases()),
                'help' => $command->getProcessedHelp(),
-                'definition' => $this->getInputDefinitionData($command->getDefinition()),
+                'definition' => $this->getInputDefinitionData($command->getDefinition(), $options),
            ];
        }


@@ -70,6 +70,7 @@ protected function describeInputOption(InputOption $option, array $options = [])
            .'* Accept value: '.($option->acceptValue() ? 'yes' : 'no')."\n"
            .'* Is value required: '.($option->isValueRequired() ? 'yes' : 'no')."\n"
            .'* Is multiple: '.($option->isArray() ? 'yes' : 'no')."\n"
+            .($option->isDeprecated() ? ('* Is deprecated: yes'."\n") : '')
            .'* Is negatable: '.($option->isNegatable() ? 'yes' : 'no')."\n"
            .'* Default: `'.str_replace("\n", '', var_export($option->getDefault(), true)).'`'
        );
@@ -81,19 +82,20 @@ protected function describeInputDefinition(InputDefinition $definition, array $o
            $this->write('### Arguments');
            foreach ($definition->getArguments() as $argument) {
                $this->write("\n\n");
-                $this->describeInputArgument($argument);
+                $this->describeInputArgument($argument, $options);
            }
        }

-        if (\count($definition->getOptions()) > 0) {
+        $inputOptions = $this->removeHiddenOptions($definition->getOptions(), $options);
+        if (!empty($inputOptions)) {
            if ($showArguments) {
                $this->write("\n\n");
            }

            $this->write('### Options');
-            foreach ($definition->getOptions() as $option) {
+            foreach ($inputOptions as $option) {
                $this->write("\n\n");
-                $this->describeInputOption($option);
+                $this->describeInputOption($option, $options);
            }
        }
    }
@@ -128,9 +130,9 @@ protected function describeCommand(Command $command, array $options = []): void
        }

        $definition = $command->getDefinition();
-        if ($definition->getOptions() || $definition->getArguments()) {
+        if ($this->removeHiddenOptions($definition->getOptions(), $options) || $definition->getArguments()) {
            $this->write("\n\n");
-            $this->describeInputDefinition($definition);
+            $this->describeInputDefinition($definition, $options);
        }
    }


@@ -84,6 +84,7 @@ protected function describeInputOption(InputOption $option, array $options = [])
            .'- **Accept value**: '.($option->acceptValue() ? 'yes' : 'no')."\n"
            .'- **Is value required**: '.($option->isValueRequired() ? 'yes' : 'no')."\n"
            .'- **Is multiple**: '.($option->isArray() ? 'yes' : 'no')."\n"
+            .($option->isDeprecated() ? ('- **Is deprecated**: yes'."\n") : '')
            .'- **Is negatable**: '.($option->isNegatable() ? 'yes' : 'no')."\n"
            .'- **Default**: ``'.str_replace("\n", '', var_export($option->getDefault(), true)).'``'."\n"
        );
@@ -95,18 +96,19 @@ protected function describeInputDefinition(InputDefinition $definition, array $o
            $this->write("Arguments\n".str_repeat($this->subsubsectionChar, 9));
            foreach ($definition->getArguments() as $argument) {
                $this->write("\n\n");
-                $this->describeInputArgument($argument);
+                $this->describeInputArgument($argument, $options);
            }
        }

-        if ($nonDefaultOptions = $this->getNonDefaultOptions($definition)) {
+        $inputOptions = $this->removeHiddenOptions($this->getNonDefaultOptions($definition), $options);
+        if (!empty($inputOptions)) {
            if ($showArguments) {
                $this->write("\n\n");
            }

-            $this->write("Options\n".str_repeat($this->subsubsectionChar, 7)."\n\n");
-            foreach ($nonDefaultOptions as $option) {
-                $this->describeInputOption($option);
+            $this->write("Options\n" . str_repeat($this->subsubsectionChar, 7) . "\n\n");
+            foreach ($inputOptions as $option) {
+                $this->describeInputOption($option, $options);
                $this->write("\n");
            }
        }
@@ -145,9 +147,9 @@ protected function describeCommand(Command $command, array $options = []): void
        }

        $definition = $command->getDefinition();
-        if ($definition->getOptions() || $definition->getArguments()) {
+        if ($this->removeHiddenOptions($definition->getOptions(), $options) || $definition->getArguments()) {
            $this->write("\n\n");
-            $this->describeInputDefinition($definition);
+            $this->describeInputDefinition($definition, $options);
        }
    }


@@ -73,8 +73,8 @@ protected function describeInputOption(InputOption $option, array $options = [])

        $spacingWidth = $totalWidth - Helper::width($synopsis);

-        $this->writeText(\sprintf('  <info>%s</info>  %s%s%s%s',
-            $synopsis,
+        $this->writeText(\sprintf('  %s  %s%s%s%s',
+            \sprintf('<%1$s>%2$s</%1$s>', $option->isDeprecated() ? 'text_error' : 'info', $synopsis),
            str_repeat(' ', $spacingWidth),
            // + 4 = 2 spaces before <info>, 2 spaces after </info>
            preg_replace('/\s*[\r\n]\s*/', "\n".str_repeat(' ', $totalWidth + 4), $option->getDescription()),
@@ -85,29 +85,30 @@ protected function describeInputOption(InputOption $option, array $options = [])

    protected function describeInputDefinition(InputDefinition $definition, array $options = []): void
    {
-        $totalWidth = $this->calculateTotalWidthForOptions($definition->getOptions());
-        foreach ($definition->getArguments() as $argument) {
+        $inputArguments = $definition->getArguments();
+        $inputOptions = $this->removeHiddenOptions($definition->getOptions(), $options);
+        $totalWidth = $this->calculateTotalWidthForOptions($inputOptions);
+        foreach ($inputArguments as $argument) {
            $totalWidth = max($totalWidth, Helper::width($argument->getName()));
        }

-        if ($definition->getArguments()) {
+        if ($inputArguments) {
            $this->writeText('<comment>Arguments:</comment>', $options);
            $this->writeText("\n");
-            foreach ($definition->getArguments() as $argument) {
+            foreach ($inputArguments as $argument) {
                $this->describeInputArgument($argument, array_merge($options, ['total_width' => $totalWidth]));
                $this->writeText("\n");
            }
        }

-        if ($definition->getArguments() && $definition->getOptions()) {
-            $this->writeText("\n");
-        }
-
-        if ($definition->getOptions()) {
+        if ($inputOptions) {
+            if ($showArguments) {
+                $this->writeText("\n");
+            }
            $laterOptions = [];

            $this->writeText('<comment>Options:</comment>', $options);
-            foreach ($definition->getOptions() as $option) {
+            foreach ($inputOptions as $option) {
                if (\strlen($option->getShortcut() ?? '') > 1) {
                    $laterOptions[] = $option;
                    continue;
@@ -141,7 +142,7 @@ protected function describeCommand(Command $command, array $options = []): void
        $this->writeText("\n");

        $definition = $command->getDefinition();
-        if ($definition->getOptions() || $definition->getArguments()) {
+        if ($this->removeHiddenOptions($definition->getOptions(), $options) || $definition->getArguments()) {
            $this->writeText("\n");
            $this->describeInputDefinition($definition, $options);
            $this->writeText("\n");