[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Part of the Joomla Framework Console Package
   4   *
   5   * @copyright  Copyright (C) 2005 - 2021 Open Source Matters, Inc. All rights reserved.
   6   * @license    GNU General Public License version 2 or later; see LICENSE
   7   */
   8  
   9  namespace Joomla\Console\Descriptor;
  10  
  11  use Joomla\Console\Application;
  12  use Joomla\Console\Command\AbstractCommand;
  13  use Joomla\String\StringHelper;
  14  use Symfony\Component\Console\Descriptor\TextDescriptor as SymfonyTextDescriptor;
  15  use Symfony\Component\Console\Input\InputDefinition;
  16  use Symfony\Component\Console\Output\OutputInterface;
  17  
  18  /**
  19   * Text object descriptor.
  20   *
  21   * @since  2.0.0
  22   */
  23  final class TextDescriptor extends SymfonyTextDescriptor
  24  {
  25      /**
  26       * Describes an object.
  27       *
  28       * @param   OutputInterface  $output   The output object to use.
  29       * @param   object           $object   The object to describe.
  30       * @param   array            $options  Descriptor options.
  31       *
  32       * @return  void
  33       *
  34       * @since   2.0.0
  35       */
  36  	public function describe(OutputInterface $output, $object, array $options = [])
  37      {
  38          $this->output = $output;
  39  
  40          switch (true)
  41          {
  42              case $object instanceof Application:
  43                  $this->describeJoomlaApplication($object, $options);
  44  
  45                  break;
  46  
  47              case $object instanceof AbstractCommand:
  48                  $this->describeConsoleCommand($object, $options);
  49  
  50                  break;
  51  
  52              default:
  53                  parent::describe($output, $object, $options);
  54          }
  55      }
  56  
  57      /**
  58       * Formats command aliases to show them in the command description.
  59       *
  60       * @param   AbstractCommand  $command  The command to process
  61       *
  62       * @return  string
  63       *
  64       * @since   2.0.0
  65       */
  66  	private function getCommandAliasesText(AbstractCommand $command): string
  67      {
  68          $text    = '';
  69          $aliases = $command->getAliases();
  70  
  71          if ($aliases)
  72          {
  73              $text = '[' . implode('|', $aliases) . '] ';
  74          }
  75  
  76          return $text;
  77      }
  78  
  79      /**
  80       * Describes a command.
  81       *
  82       * @param   AbstractCommand  $command  The command being described.
  83       * @param   array            $options  Descriptor options.
  84       *
  85       * @return  void
  86       *
  87       * @since   2.0.0
  88       */
  89  	private function describeConsoleCommand(AbstractCommand $command, array $options): void
  90      {
  91          $command->getSynopsis(true);
  92          $command->getSynopsis(false);
  93          $command->mergeApplicationDefinition(false);
  94  
  95          $this->writeText('<comment>Usage:</comment>', $options);
  96  
  97          foreach (array_merge([$command->getSynopsis(true)], $command->getAliases()) as $usage)
  98          {
  99              $this->writeText("\n");
 100              $this->writeText('  ' . $usage, $options);
 101          }
 102  
 103          $this->writeText("\n");
 104  
 105          $definition = $command->getDefinition();
 106  
 107          if ($definition->getOptions() || $definition->getArguments())
 108          {
 109              $this->writeText("\n");
 110              $this->describeInputDefinition($definition, $options);
 111              $this->writeText("\n");
 112          }
 113  
 114          if ($help = $command->getProcessedHelp())
 115          {
 116              $this->writeText("\n");
 117              $this->writeText('<comment>Help:</comment>', $options);
 118              $this->writeText("\n");
 119              $this->writeText('  ' . str_replace("\n", "\n  ", $help), $options);
 120              $this->writeText("\n");
 121          }
 122      }
 123  
 124      /**
 125       * Describes an application.
 126       *
 127       * @param   Application  $app      The application being described.
 128       * @param   array        $options  Descriptor options.
 129       *
 130       * @return  void
 131       *
 132       * @since   2.0.0
 133       */
 134  	private function describeJoomlaApplication(Application $app, array $options): void
 135      {
 136          $describedNamespace = $options['namespace'] ?? '';
 137          $description        = new ApplicationDescription($app, $describedNamespace);
 138  
 139          $version = $app->getLongVersion();
 140  
 141          if ($version !== '')
 142          {
 143              $this->writeText("$version\n\n", $options);
 144          }
 145  
 146          $this->writeText("<comment>Usage:</comment>\n");
 147          $this->writeText("  command [options] [arguments]\n\n");
 148  
 149          $this->describeInputDefinition(new InputDefinition($app->getDefinition()->getOptions()), $options);
 150  
 151          $this->writeText("\n");
 152          $this->writeText("\n");
 153  
 154          $commands   = $description->getCommands();
 155          $namespaces = $description->getNamespaces();
 156  
 157          if ($describedNamespace && $namespaces)
 158          {
 159              // Ensure all aliased commands are included when describing a specific namespace
 160              $describedNamespaceInfo = reset($namespaces);
 161  
 162              foreach ($describedNamespaceInfo['commands'] as $name)
 163              {
 164                  $commands[$name] = $description->getCommand($name);
 165              }
 166          }
 167  
 168          $width = $this->getColumnWidth(
 169              \call_user_func_array(
 170                  'array_merge',
 171                  array_map(
 172                      function ($namespace) use ($commands)
 173                      {
 174                          return array_intersect($namespace['commands'], array_keys($commands));
 175                      },
 176                      array_values($namespaces)
 177                  )
 178              )
 179          );
 180  
 181          if ($describedNamespace)
 182          {
 183              $this->writeText(sprintf('<comment>Available commands for the "%s" namespace:</comment>', $describedNamespace), $options);
 184          }
 185          else
 186          {
 187              $this->writeText('<comment>Available commands:</comment>', $options);
 188          }
 189  
 190          foreach ($namespaces as $namespace)
 191          {
 192              $namespace['commands'] = array_filter(
 193                  $namespace['commands'],
 194                  function ($name) use ($commands)
 195                  {
 196                      return isset($commands[$name]);
 197                  }
 198              );
 199  
 200              if (!$namespace['commands'])
 201              {
 202                  continue;
 203              }
 204  
 205              if (!$describedNamespace && $namespace['id'] !== ApplicationDescription::GLOBAL_NAMESPACE)
 206              {
 207                  $this->writeText("\n");
 208                  $this->writeText(' <comment>' . $namespace['id'] . '</comment>', $options);
 209              }
 210  
 211              foreach ($namespace['commands'] as $name)
 212              {
 213                  $this->writeText("\n");
 214                  $spacingWidth   = $width - StringHelper::strlen($name);
 215                  $command        = $commands[$name];
 216                  $commandAliases = $name === $command->getName() ? $this->getCommandAliasesText($command) : '';
 217  
 218                  $this->writeText(
 219                      sprintf(
 220                          '  <info>%s</info>%s%s', $name, str_repeat(' ', $spacingWidth), $commandAliases . $command->getDescription()
 221                      ),
 222                      $options
 223                  );
 224              }
 225          }
 226  
 227          $this->writeText("\n");
 228      }
 229  
 230      /**
 231       * Calculate the column width for a group of commands.
 232       *
 233       * @param   AbstractCommand[]|string[] $commands The commands to use for processing a width.
 234       *
 235       * @return  integer
 236       *
 237       * @since   2.0.0
 238       */
 239  	private function getColumnWidth(array $commands): int
 240      {
 241          $widths = [];
 242  
 243          foreach ($commands as $command)
 244          {
 245              if ($command instanceof AbstractCommand)
 246              {
 247                  $widths[] = StringHelper::strlen($command->getName());
 248  
 249                  foreach ($command->getAliases() as $alias)
 250                  {
 251                      $widths[] = StringHelper::strlen($alias);
 252                  }
 253              }
 254              else
 255              {
 256                  $widths[] = StringHelper::strlen($command);
 257              }
 258          }
 259  
 260          return $widths ? max($widths) + 2 : 0;
 261      }
 262  
 263      /**
 264       * Writes text to the output.
 265       *
 266       * @param   string  $content  The message.
 267       * @param   array   $options  The options to use for formatting the output.
 268       *
 269       * @return  void
 270       *
 271       * @since   2.0.0
 272       */
 273  	private function writeText($content, array $options = []): void
 274      {
 275          $this->write(
 276              isset($options['raw_text']) && $options['raw_text'] ? strip_tags($content) : $content,
 277              isset($options['raw_output']) ? !$options['raw_output'] : true
 278          );
 279      }
 280  }