[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\Input;
  13  
  14  use Symfony\Component\Console\Descriptor\TextDescriptor;
  15  use Symfony\Component\Console\Descriptor\XmlDescriptor;
  16  use Symfony\Component\Console\Exception\InvalidArgumentException;
  17  use Symfony\Component\Console\Exception\LogicException;
  18  use Symfony\Component\Console\Output\BufferedOutput;
  19  
  20  /**
  21   * A InputDefinition represents a set of valid command line arguments and options.
  22   *
  23   * Usage:
  24   *
  25   *     $definition = new InputDefinition(array(
  26   *         new InputArgument('name', InputArgument::REQUIRED),
  27   *         new InputOption('foo', 'f', InputOption::VALUE_REQUIRED),
  28   *     ));
  29   *
  30   * @author Fabien Potencier <fabien@symfony.com>
  31   */
  32  class InputDefinition
  33  {
  34      private $arguments;
  35      private $requiredCount;
  36      private $hasAnArrayArgument = false;
  37      private $hasOptional;
  38      private $options;
  39      private $shortcuts;
  40  
  41      /**
  42       * @param array $definition An array of InputArgument and InputOption instance
  43       */
  44      public function __construct(array $definition = array())
  45      {
  46          $this->setDefinition($definition);
  47      }
  48  
  49      /**
  50       * Sets the definition of the input.
  51       */
  52      public function setDefinition(array $definition)
  53      {
  54          $arguments = array();
  55          $options = array();
  56          foreach ($definition as $item) {
  57              if ($item instanceof InputOption) {
  58                  $options[] = $item;
  59              } else {
  60                  $arguments[] = $item;
  61              }
  62          }
  63  
  64          $this->setArguments($arguments);
  65          $this->setOptions($options);
  66      }
  67  
  68      /**
  69       * Sets the InputArgument objects.
  70       *
  71       * @param InputArgument[] $arguments An array of InputArgument objects
  72       */
  73      public function setArguments($arguments = array())
  74      {
  75          $this->arguments = array();
  76          $this->requiredCount = 0;
  77          $this->hasOptional = false;
  78          $this->hasAnArrayArgument = false;
  79          $this->addArguments($arguments);
  80      }
  81  
  82      /**
  83       * Adds an array of InputArgument objects.
  84       *
  85       * @param InputArgument[] $arguments An array of InputArgument objects
  86       */
  87      public function addArguments($arguments = array())
  88      {
  89          if (null !== $arguments) {
  90              foreach ($arguments as $argument) {
  91                  $this->addArgument($argument);
  92              }
  93          }
  94      }
  95  
  96      /**
  97       * @throws LogicException When incorrect argument is given
  98       */
  99      public function addArgument(InputArgument $argument)
 100      {
 101          if (isset($this->arguments[$argument->getName()])) {
 102              throw new LogicException(sprintf('An argument with name "%s" already exists.', $argument->getName()));
 103          }
 104  
 105          if ($this->hasAnArrayArgument) {
 106              throw new LogicException('Cannot add an argument after an array argument.');
 107          }
 108  
 109          if ($argument->isRequired() && $this->hasOptional) {
 110              throw new LogicException('Cannot add a required argument after an optional one.');
 111          }
 112  
 113          if ($argument->isArray()) {
 114              $this->hasAnArrayArgument = true;
 115          }
 116  
 117          if ($argument->isRequired()) {
 118              ++$this->requiredCount;
 119          } else {
 120              $this->hasOptional = true;
 121          }
 122  
 123          $this->arguments[$argument->getName()] = $argument;
 124      }
 125  
 126      /**
 127       * Returns an InputArgument by name or by position.
 128       *
 129       * @param string|int $name The InputArgument name or position
 130       *
 131       * @return InputArgument An InputArgument object
 132       *
 133       * @throws InvalidArgumentException When argument given doesn't exist
 134       */
 135      public function getArgument($name)
 136      {
 137          if (!$this->hasArgument($name)) {
 138              throw new InvalidArgumentException(sprintf('The "%s" argument does not exist.', $name));
 139          }
 140  
 141          $arguments = \is_int($name) ? array_values($this->arguments) : $this->arguments;
 142  
 143          return $arguments[$name];
 144      }
 145  
 146      /**
 147       * Returns true if an InputArgument object exists by name or position.
 148       *
 149       * @param string|int $name The InputArgument name or position
 150       *
 151       * @return bool true if the InputArgument object exists, false otherwise
 152       */
 153      public function hasArgument($name)
 154      {
 155          $arguments = \is_int($name) ? array_values($this->arguments) : $this->arguments;
 156  
 157          return isset($arguments[$name]);
 158      }
 159  
 160      /**
 161       * Gets the array of InputArgument objects.
 162       *
 163       * @return InputArgument[] An array of InputArgument objects
 164       */
 165      public function getArguments()
 166      {
 167          return $this->arguments;
 168      }
 169  
 170      /**
 171       * Returns the number of InputArguments.
 172       *
 173       * @return int The number of InputArguments
 174       */
 175      public function getArgumentCount()
 176      {
 177          return $this->hasAnArrayArgument ? PHP_INT_MAX : \count($this->arguments);
 178      }
 179  
 180      /**
 181       * Returns the number of required InputArguments.
 182       *
 183       * @return int The number of required InputArguments
 184       */
 185      public function getArgumentRequiredCount()
 186      {
 187          return $this->requiredCount;
 188      }
 189  
 190      /**
 191       * Gets the default values.
 192       *
 193       * @return array An array of default values
 194       */
 195      public function getArgumentDefaults()
 196      {
 197          $values = array();
 198          foreach ($this->arguments as $argument) {
 199              $values[$argument->getName()] = $argument->getDefault();
 200          }
 201  
 202          return $values;
 203      }
 204  
 205      /**
 206       * Sets the InputOption objects.
 207       *
 208       * @param InputOption[] $options An array of InputOption objects
 209       */
 210      public function setOptions($options = array())
 211      {
 212          $this->options = array();
 213          $this->shortcuts = array();
 214          $this->addOptions($options);
 215      }
 216  
 217      /**
 218       * Adds an array of InputOption objects.
 219       *
 220       * @param InputOption[] $options An array of InputOption objects
 221       */
 222      public function addOptions($options = array())
 223      {
 224          foreach ($options as $option) {
 225              $this->addOption($option);
 226          }
 227      }
 228  
 229      /**
 230       * @throws LogicException When option given already exist
 231       */
 232      public function addOption(InputOption $option)
 233      {
 234          if (isset($this->options[$option->getName()]) && !$option->equals($this->options[$option->getName()])) {
 235              throw new LogicException(sprintf('An option named "%s" already exists.', $option->getName()));
 236          }
 237  
 238          if ($option->getShortcut()) {
 239              foreach (explode('|', $option->getShortcut()) as $shortcut) {
 240                  if (isset($this->shortcuts[$shortcut]) && !$option->equals($this->options[$this->shortcuts[$shortcut]])) {
 241                      throw new LogicException(sprintf('An option with shortcut "%s" already exists.', $shortcut));
 242                  }
 243              }
 244          }
 245  
 246          $this->options[$option->getName()] = $option;
 247          if ($option->getShortcut()) {
 248              foreach (explode('|', $option->getShortcut()) as $shortcut) {
 249                  $this->shortcuts[$shortcut] = $option->getName();
 250              }
 251          }
 252      }
 253  
 254      /**
 255       * Returns an InputOption by name.
 256       *
 257       * @param string $name The InputOption name
 258       *
 259       * @return InputOption A InputOption object
 260       *
 261       * @throws InvalidArgumentException When option given doesn't exist
 262       */
 263      public function getOption($name)
 264      {
 265          if (!$this->hasOption($name)) {
 266              throw new InvalidArgumentException(sprintf('The "--%s" option does not exist.', $name));
 267          }
 268  
 269          return $this->options[$name];
 270      }
 271  
 272      /**
 273       * Returns true if an InputOption object exists by name.
 274       *
 275       * This method can't be used to check if the user included the option when
 276       * executing the command (use getOption() instead).
 277       *
 278       * @param string $name The InputOption name
 279       *
 280       * @return bool true if the InputOption object exists, false otherwise
 281       */
 282      public function hasOption($name)
 283      {
 284          return isset($this->options[$name]);
 285      }
 286  
 287      /**
 288       * Gets the array of InputOption objects.
 289       *
 290       * @return InputOption[] An array of InputOption objects
 291       */
 292      public function getOptions()
 293      {
 294          return $this->options;
 295      }
 296  
 297      /**
 298       * Returns true if an InputOption object exists by shortcut.
 299       *
 300       * @param string $name The InputOption shortcut
 301       *
 302       * @return bool true if the InputOption object exists, false otherwise
 303       */
 304      public function hasShortcut($name)
 305      {
 306          return isset($this->shortcuts[$name]);
 307      }
 308  
 309      /**
 310       * Gets an InputOption by shortcut.
 311       *
 312       * @param string $shortcut The Shortcut name
 313       *
 314       * @return InputOption An InputOption object
 315       */
 316      public function getOptionForShortcut($shortcut)
 317      {
 318          return $this->getOption($this->shortcutToName($shortcut));
 319      }
 320  
 321      /**
 322       * Gets an array of default values.
 323       *
 324       * @return array An array of all default values
 325       */
 326      public function getOptionDefaults()
 327      {
 328          $values = array();
 329          foreach ($this->options as $option) {
 330              $values[$option->getName()] = $option->getDefault();
 331          }
 332  
 333          return $values;
 334      }
 335  
 336      /**
 337       * Returns the InputOption name given a shortcut.
 338       *
 339       * @param string $shortcut The shortcut
 340       *
 341       * @return string The InputOption name
 342       *
 343       * @throws InvalidArgumentException When option given does not exist
 344       */
 345      private function shortcutToName($shortcut)
 346      {
 347          if (!isset($this->shortcuts[$shortcut])) {
 348              throw new InvalidArgumentException(sprintf('The "-%s" option does not exist.', $shortcut));
 349          }
 350  
 351          return $this->shortcuts[$shortcut];
 352      }
 353  
 354      /**
 355       * Gets the synopsis.
 356       *
 357       * @param bool $short Whether to return the short version (with options folded) or not
 358       *
 359       * @return string The synopsis
 360       */
 361      public function getSynopsis($short = false)
 362      {
 363          $elements = array();
 364  
 365          if ($short && $this->getOptions()) {
 366              $elements[] = '[options]';
 367          } elseif (!$short) {
 368              foreach ($this->getOptions() as $option) {
 369                  $value = '';
 370                  if ($option->acceptValue()) {
 371                      $value = sprintf(
 372                          ' %s%s%s',
 373                          $option->isValueOptional() ? '[' : '',
 374                          strtoupper($option->getName()),
 375                          $option->isValueOptional() ? ']' : ''
 376                      );
 377                  }
 378  
 379                  $shortcut = $option->getShortcut() ? sprintf('-%s|', $option->getShortcut()) : '';
 380                  $elements[] = sprintf('[%s--%s%s]', $shortcut, $option->getName(), $value);
 381              }
 382          }
 383  
 384          if (\count($elements) && $this->getArguments()) {
 385              $elements[] = '[--]';
 386          }
 387  
 388          foreach ($this->getArguments() as $argument) {
 389              $element = '<'.$argument->getName().'>';
 390              if (!$argument->isRequired()) {
 391                  $element = '['.$element.']';
 392              } elseif ($argument->isArray()) {
 393                  $element .= ' ('.$element.')';
 394              }
 395  
 396              if ($argument->isArray()) {
 397                  $element .= '...';
 398              }
 399  
 400              $elements[] = $element;
 401          }
 402  
 403          return implode(' ', $elements);
 404      }
 405  
 406      /**
 407       * Returns a textual representation of the InputDefinition.
 408       *
 409       * @return string A string representing the InputDefinition
 410       *
 411       * @deprecated since version 2.3, to be removed in 3.0.
 412       */
 413      public function asText()
 414      {
 415          @trigger_error('The '.__METHOD__.' method is deprecated since Symfony 2.3 and will be removed in 3.0.', E_USER_DEPRECATED);
 416  
 417          $descriptor = new TextDescriptor();
 418          $output = new BufferedOutput(BufferedOutput::VERBOSITY_NORMAL, true);
 419          $descriptor->describe($output, $this, array('raw_output' => true));
 420  
 421          return $output->fetch();
 422      }
 423  
 424      /**
 425       * Returns an XML representation of the InputDefinition.
 426       *
 427       * @param bool $asDom Whether to return a DOM or an XML string
 428       *
 429       * @return string|\DOMDocument An XML string representing the InputDefinition
 430       *
 431       * @deprecated since version 2.3, to be removed in 3.0.
 432       */
 433      public function asXml($asDom = false)
 434      {
 435          @trigger_error('The '.__METHOD__.' method is deprecated since Symfony 2.3 and will be removed in 3.0.', E_USER_DEPRECATED);
 436  
 437          $descriptor = new XmlDescriptor();
 438  
 439          if ($asDom) {
 440              return $descriptor->getInputDefinitionDocument($this);
 441          }
 442  
 443          $output = new BufferedOutput();
 444          $descriptor->describe($output, $this);
 445  
 446          return $output->fetch();
 447      }
 448  }