[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /*
   4   * This file is part of the Symfony package.
   5   *
   6   * (c) Fabien Potencier <fabien@symfony.com>
   7   *
   8   * For the full copyright and license information, please view the LICENSE
   9   * file that was distributed with this source code.
  10   */
  11  
  12  namespace Symfony\Component\Console\Descriptor;
  13  
  14  use Symfony\Component\Console\Application;
  15  use Symfony\Component\Console\Command\Command;
  16  use Symfony\Component\Console\Formatter\OutputFormatter;
  17  use Symfony\Component\Console\Helper\Helper;
  18  use Symfony\Component\Console\Input\InputArgument;
  19  use Symfony\Component\Console\Input\InputDefinition;
  20  use Symfony\Component\Console\Input\InputOption;
  21  
  22  /**
  23   * Text descriptor.
  24   *
  25   * @author Jean-François Simon <contact@jfsimon.fr>
  26   *
  27   * @internal
  28   */
  29  class TextDescriptor extends Descriptor
  30  {
  31      /**
  32       * {@inheritdoc}
  33       */
  34      protected function describeInputArgument(InputArgument $argument, array $options = [])
  35      {
  36          if (null !== $argument->getDefault() && (!\is_array($argument->getDefault()) || \count($argument->getDefault()))) {
  37              $default = sprintf('<comment> [default: %s]</comment>', $this->formatDefaultValue($argument->getDefault()));
  38          } else {
  39              $default = '';
  40          }
  41  
  42          $totalWidth = isset($options['total_width']) ? $options['total_width'] : Helper::strlen($argument->getName());
  43          $spacingWidth = $totalWidth - \strlen($argument->getName());
  44  
  45          $this->writeText(sprintf('  <info>%s</info>  %s%s%s',
  46              $argument->getName(),
  47              str_repeat(' ', $spacingWidth),
  48              // + 4 = 2 spaces before <info>, 2 spaces after </info>
  49              preg_replace('/\s*[\r\n]\s*/', "\n".str_repeat(' ', $totalWidth + 4), $argument->getDescription()),
  50              $default
  51          ), $options);
  52      }
  53  
  54      /**
  55       * {@inheritdoc}
  56       */
  57      protected function describeInputOption(InputOption $option, array $options = [])
  58      {
  59          if ($option->acceptValue() && null !== $option->getDefault() && (!\is_array($option->getDefault()) || \count($option->getDefault()))) {
  60              $default = sprintf('<comment> [default: %s]</comment>', $this->formatDefaultValue($option->getDefault()));
  61          } else {
  62              $default = '';
  63          }
  64  
  65          $value = '';
  66          if ($option->acceptValue()) {
  67              $value = '='.strtoupper($option->getName());
  68  
  69              if ($option->isValueOptional()) {
  70                  $value = '['.$value.']';
  71              }
  72          }
  73  
  74          $totalWidth = isset($options['total_width']) ? $options['total_width'] : $this->calculateTotalWidthForOptions([$option]);
  75          $synopsis = sprintf('%s%s',
  76              $option->getShortcut() ? sprintf('-%s, ', $option->getShortcut()) : '    ',
  77              sprintf('--%s%s', $option->getName(), $value)
  78          );
  79  
  80          $spacingWidth = $totalWidth - Helper::strlen($synopsis);
  81  
  82          $this->writeText(sprintf('  <info>%s</info>  %s%s%s%s',
  83              $synopsis,
  84              str_repeat(' ', $spacingWidth),
  85              // + 4 = 2 spaces before <info>, 2 spaces after </info>
  86              preg_replace('/\s*[\r\n]\s*/', "\n".str_repeat(' ', $totalWidth + 4), $option->getDescription()),
  87              $default,
  88              $option->isArray() ? '<comment> (multiple values allowed)</comment>' : ''
  89          ), $options);
  90      }
  91  
  92      /**
  93       * {@inheritdoc}
  94       */
  95      protected function describeInputDefinition(InputDefinition $definition, array $options = [])
  96      {
  97          $totalWidth = $this->calculateTotalWidthForOptions($definition->getOptions());
  98          foreach ($definition->getArguments() as $argument) {
  99              $totalWidth = max($totalWidth, Helper::strlen($argument->getName()));
 100          }
 101  
 102          if ($definition->getArguments()) {
 103              $this->writeText('<comment>Arguments:</comment>', $options);
 104              $this->writeText("\n");
 105              foreach ($definition->getArguments() as $argument) {
 106                  $this->describeInputArgument($argument, array_merge($options, ['total_width' => $totalWidth]));
 107                  $this->writeText("\n");
 108              }
 109          }
 110  
 111          if ($definition->getArguments() && $definition->getOptions()) {
 112              $this->writeText("\n");
 113          }
 114  
 115          if ($definition->getOptions()) {
 116              $laterOptions = [];
 117  
 118              $this->writeText('<comment>Options:</comment>', $options);
 119              foreach ($definition->getOptions() as $option) {
 120                  if (\strlen($option->getShortcut()) > 1) {
 121                      $laterOptions[] = $option;
 122                      continue;
 123                  }
 124                  $this->writeText("\n");
 125                  $this->describeInputOption($option, array_merge($options, ['total_width' => $totalWidth]));
 126              }
 127              foreach ($laterOptions as $option) {
 128                  $this->writeText("\n");
 129                  $this->describeInputOption($option, array_merge($options, ['total_width' => $totalWidth]));
 130              }
 131          }
 132      }
 133  
 134      /**
 135       * {@inheritdoc}
 136       */
 137      protected function describeCommand(Command $command, array $options = [])
 138      {
 139          $command->getSynopsis(true);
 140          $command->getSynopsis(false);
 141          $command->mergeApplicationDefinition(false);
 142  
 143          $this->writeText('<comment>Usage:</comment>', $options);
 144          foreach (array_merge([$command->getSynopsis(true)], $command->getAliases(), $command->getUsages()) as $usage) {
 145              $this->writeText("\n");
 146              $this->writeText('  '.OutputFormatter::escape($usage), $options);
 147          }
 148          $this->writeText("\n");
 149  
 150          $definition = $command->getNativeDefinition();
 151          if ($definition->getOptions() || $definition->getArguments()) {
 152              $this->writeText("\n");
 153              $this->describeInputDefinition($definition, $options);
 154              $this->writeText("\n");
 155          }
 156  
 157          if ($help = $command->getProcessedHelp()) {
 158              $this->writeText("\n");
 159              $this->writeText('<comment>Help:</comment>', $options);
 160              $this->writeText("\n");
 161              $this->writeText('  '.str_replace("\n", "\n  ", $help), $options);
 162              $this->writeText("\n");
 163          }
 164      }
 165  
 166      /**
 167       * {@inheritdoc}
 168       */
 169      protected function describeApplication(Application $application, array $options = [])
 170      {
 171          $describedNamespace = isset($options['namespace']) ? $options['namespace'] : null;
 172          $description = new ApplicationDescription($application, $describedNamespace);
 173  
 174          if (isset($options['raw_text']) && $options['raw_text']) {
 175              $width = $this->getColumnWidth($description->getCommands());
 176  
 177              foreach ($description->getCommands() as $command) {
 178                  $this->writeText(sprintf("%-{$width}s %s", $command->getName(), $command->getDescription()), $options);
 179                  $this->writeText("\n");
 180              }
 181          } else {
 182              if ('' != $help = $application->getHelp()) {
 183                  $this->writeText("$help\n\n", $options);
 184              }
 185  
 186              $this->writeText("<comment>Usage:</comment>\n", $options);
 187              $this->writeText("  command [options] [arguments]\n\n", $options);
 188  
 189              $this->describeInputDefinition(new InputDefinition($application->getDefinition()->getOptions()), $options);
 190  
 191              $this->writeText("\n");
 192              $this->writeText("\n");
 193  
 194              $commands = $description->getCommands();
 195              $namespaces = $description->getNamespaces();
 196              if ($describedNamespace && $namespaces) {
 197                  // make sure all alias commands are included when describing a specific namespace
 198                  $describedNamespaceInfo = reset($namespaces);
 199                  foreach ($describedNamespaceInfo['commands'] as $name) {
 200                      $commands[$name] = $description->getCommand($name);
 201                  }
 202              }
 203  
 204              // calculate max. width based on available commands per namespace
 205              $width = $this->getColumnWidth(\call_user_func_array('array_merge', array_map(function ($namespace) use ($commands) {
 206                  return array_intersect($namespace['commands'], array_keys($commands));
 207              }, array_values($namespaces))));
 208  
 209              if ($describedNamespace) {
 210                  $this->writeText(sprintf('<comment>Available commands for the "%s" namespace:</comment>', $describedNamespace), $options);
 211              } else {
 212                  $this->writeText('<comment>Available commands:</comment>', $options);
 213              }
 214  
 215              foreach ($namespaces as $namespace) {
 216                  $namespace['commands'] = array_filter($namespace['commands'], function ($name) use ($commands) {
 217                      return isset($commands[$name]);
 218                  });
 219  
 220                  if (!$namespace['commands']) {
 221                      continue;
 222                  }
 223  
 224                  if (!$describedNamespace && ApplicationDescription::GLOBAL_NAMESPACE !== $namespace['id']) {
 225                      $this->writeText("\n");
 226                      $this->writeText(' <comment>'.$namespace['id'].'</comment>', $options);
 227                  }
 228  
 229                  foreach ($namespace['commands'] as $name) {
 230                      $this->writeText("\n");
 231                      $spacingWidth = $width - Helper::strlen($name);
 232                      $command = $commands[$name];
 233                      $commandAliases = $name === $command->getName() ? $this->getCommandAliasesText($command) : '';
 234                      $this->writeText(sprintf('  <info>%s</info>%s%s', $name, str_repeat(' ', $spacingWidth), $commandAliases.$command->getDescription()), $options);
 235                  }
 236              }
 237  
 238              $this->writeText("\n");
 239          }
 240      }
 241  
 242      /**
 243       * {@inheritdoc}
 244       */
 245      private function writeText($content, array $options = [])
 246      {
 247          $this->write(
 248              isset($options['raw_text']) && $options['raw_text'] ? strip_tags($content) : $content,
 249              isset($options['raw_output']) ? !$options['raw_output'] : true
 250          );
 251      }
 252  
 253      /**
 254       * Formats command aliases to show them in the command description.
 255       *
 256       * @return string
 257       */
 258      private function getCommandAliasesText(Command $command)
 259      {
 260          $text = '';
 261          $aliases = $command->getAliases();
 262  
 263          if ($aliases) {
 264              $text = '['.implode('|', $aliases).'] ';
 265          }
 266  
 267          return $text;
 268      }
 269  
 270      /**
 271       * Formats input option/argument default value.
 272       *
 273       * @param mixed $default
 274       *
 275       * @return string
 276       */
 277      private function formatDefaultValue($default)
 278      {
 279          if (\INF === $default) {
 280              return 'INF';
 281          }
 282  
 283          if (\is_string($default)) {
 284              $default = OutputFormatter::escape($default);
 285          } elseif (\is_array($default)) {
 286              foreach ($default as $key => $value) {
 287                  if (\is_string($value)) {
 288                      $default[$key] = OutputFormatter::escape($value);
 289                  }
 290              }
 291          }
 292  
 293          return str_replace('\\\\', '\\', json_encode($default, \JSON_UNESCAPED_SLASHES | \JSON_UNESCAPED_UNICODE));
 294      }
 295  
 296      /**
 297       * @param (Command|string)[] $commands
 298       *
 299       * @return int
 300       */
 301      private function getColumnWidth(array $commands)
 302      {
 303          $widths = [];
 304  
 305          foreach ($commands as $command) {
 306              if ($command instanceof Command) {
 307                  $widths[] = Helper::strlen($command->getName());
 308                  foreach ($command->getAliases() as $alias) {
 309                      $widths[] = Helper::strlen($alias);
 310                  }
 311              } else {
 312                  $widths[] = Helper::strlen($command);
 313              }
 314          }
 315  
 316          return $widths ? max($widths) + 2 : 0;
 317      }
 318  
 319      /**
 320       * @param InputOption[] $options
 321       *
 322       * @return int
 323       */
 324      private function calculateTotalWidthForOptions(array $options)
 325      {
 326          $totalWidth = 0;
 327          foreach ($options as $option) {
 328              // "-" + shortcut + ", --" + name
 329              $nameLength = 1 + max(Helper::strlen($option->getShortcut()), 1) + 4 + Helper::strlen($option->getName());
 330  
 331              if ($option->acceptValue()) {
 332                  $valueLength = 1 + Helper::strlen($option->getName()); // = + value
 333                  $valueLength += $option->isValueOptional() ? 2 : 0; // [ + ]
 334  
 335                  $nameLength += $valueLength;
 336              }
 337              $totalWidth = max($totalWidth, $nameLength);
 338          }
 339  
 340          return $totalWidth;
 341      }
 342  }