[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\Command;
  13  
  14  use Symfony\Component\Console\Descriptor\TextDescriptor;
  15  use Symfony\Component\Console\Descriptor\XmlDescriptor;
  16  use Symfony\Component\Console\Input\InputDefinition;
  17  use Symfony\Component\Console\Input\InputOption;
  18  use Symfony\Component\Console\Input\InputArgument;
  19  use Symfony\Component\Console\Input\InputInterface;
  20  use Symfony\Component\Console\Output\OutputInterface;
  21  use Symfony\Component\Console\Application;
  22  use Symfony\Component\Console\Helper\HelperSet;
  23  
  24  /**
  25   * Base class for all commands.
  26   *
  27   * @author Fabien Potencier <fabien@symfony.com>
  28   */
  29  class Command
  30  {
  31      private $application;
  32      private $name;
  33      private $aliases;
  34      private $definition;
  35      private $help;
  36      private $description;
  37      private $ignoreValidationErrors;
  38      private $applicationDefinitionMerged;
  39      private $applicationDefinitionMergedWithArgs;
  40      private $code;
  41      private $synopsis;
  42      private $helperSet;
  43  
  44      /**
  45       * Constructor.
  46       *
  47       * @param string $name The name of the command
  48       *
  49       * @throws \LogicException When the command name is empty
  50       */
  51      public function __construct($name = null)
  52      {
  53          $this->definition = new InputDefinition();
  54          $this->ignoreValidationErrors = false;
  55          $this->applicationDefinitionMerged = false;
  56          $this->applicationDefinitionMergedWithArgs = false;
  57          $this->aliases = array();
  58  
  59          if (null !== $name) {
  60              $this->setName($name);
  61          }
  62  
  63          $this->configure();
  64  
  65          if (!$this->name) {
  66              throw new \LogicException('The command name cannot be empty.');
  67          }
  68      }
  69  
  70      /**
  71       * Ignores validation errors.
  72       *
  73       * This is mainly useful for the help command.
  74       */
  75      public function ignoreValidationErrors()
  76      {
  77          $this->ignoreValidationErrors = true;
  78      }
  79  
  80      /**
  81       * Sets the application instance for this command.
  82       *
  83       * @param Application $application An Application instance
  84       */
  85      public function setApplication(Application $application = null)
  86      {
  87          $this->application = $application;
  88          if ($application) {
  89              $this->setHelperSet($application->getHelperSet());
  90          } else {
  91              $this->helperSet = null;
  92          }
  93      }
  94  
  95      /**
  96       * Sets the helper set.
  97       *
  98       * @param HelperSet $helperSet A HelperSet instance
  99       */
 100      public function setHelperSet(HelperSet $helperSet)
 101      {
 102          $this->helperSet = $helperSet;
 103      }
 104  
 105      /**
 106       * Gets the helper set.
 107       *
 108       * @return HelperSet A HelperSet instance
 109       */
 110      public function getHelperSet()
 111      {
 112          return $this->helperSet;
 113      }
 114  
 115      /**
 116       * Gets the application instance for this command.
 117       *
 118       * @return Application An Application instance
 119       */
 120      public function getApplication()
 121      {
 122          return $this->application;
 123      }
 124  
 125      /**
 126       * Checks whether the command is enabled or not in the current environment.
 127       *
 128       * Override this to check for x or y and return false if the command can not
 129       * run properly under the current conditions.
 130       *
 131       * @return bool
 132       */
 133      public function isEnabled()
 134      {
 135          return true;
 136      }
 137  
 138      /**
 139       * Configures the current command.
 140       */
 141      protected function configure()
 142      {
 143      }
 144  
 145      /**
 146       * Executes the current command.
 147       *
 148       * This method is not abstract because you can use this class
 149       * as a concrete class. In this case, instead of defining the
 150       * execute() method, you set the code to execute by passing
 151       * a Closure to the setCode() method.
 152       *
 153       * @param InputInterface  $input  An InputInterface instance
 154       * @param OutputInterface $output An OutputInterface instance
 155       *
 156       * @return null|int null or 0 if everything went fine, or an error code
 157       *
 158       * @throws \LogicException When this abstract method is not implemented
 159       *
 160       * @see setCode()
 161       */
 162      protected function execute(InputInterface $input, OutputInterface $output)
 163      {
 164          throw new \LogicException('You must override the execute() method in the concrete command class.');
 165      }
 166  
 167      /**
 168       * Interacts with the user.
 169       *
 170       * This method is executed before the InputDefinition is validated.
 171       * This means that this is the only place where the command can
 172       * interactively ask for values of missing required arguments.
 173       *
 174       * @param InputInterface  $input  An InputInterface instance
 175       * @param OutputInterface $output An OutputInterface instance
 176       */
 177      protected function interact(InputInterface $input, OutputInterface $output)
 178      {
 179      }
 180  
 181      /**
 182       * Initializes the command just after the input has been validated.
 183       *
 184       * This is mainly useful when a lot of commands extends one main command
 185       * where some things need to be initialized based on the input arguments and options.
 186       *
 187       * @param InputInterface  $input  An InputInterface instance
 188       * @param OutputInterface $output An OutputInterface instance
 189       */
 190      protected function initialize(InputInterface $input, OutputInterface $output)
 191      {
 192      }
 193  
 194      /**
 195       * Runs the command.
 196       *
 197       * The code to execute is either defined directly with the
 198       * setCode() method or by overriding the execute() method
 199       * in a sub-class.
 200       *
 201       * @param InputInterface  $input  An InputInterface instance
 202       * @param OutputInterface $output An OutputInterface instance
 203       *
 204       * @return int The command exit code
 205       *
 206       * @throws \Exception
 207       *
 208       * @see setCode()
 209       * @see execute()
 210       */
 211      public function run(InputInterface $input, OutputInterface $output)
 212      {
 213          // force the creation of the synopsis before the merge with the app definition
 214          $this->getSynopsis();
 215  
 216          // add the application arguments and options
 217          $this->mergeApplicationDefinition();
 218  
 219          // bind the input against the command specific arguments/options
 220          try {
 221              $input->bind($this->definition);
 222          } catch (\Exception $e) {
 223              if (!$this->ignoreValidationErrors) {
 224                  throw $e;
 225              }
 226          }
 227  
 228          $this->initialize($input, $output);
 229  
 230          if ($input->isInteractive()) {
 231              $this->interact($input, $output);
 232          }
 233  
 234          // The command name argument is often omitted when a command is executed directly with its run() method.
 235          // It would fail the validation if we didn't make sure the command argument is present,
 236          // since it's required by the application.
 237          if ($input->hasArgument('command') && null === $input->getArgument('command')) {
 238              $input->setArgument('command', $this->getName());
 239          }
 240  
 241          $input->validate();
 242  
 243          if ($this->code) {
 244              $statusCode = call_user_func($this->code, $input, $output);
 245          } else {
 246              $statusCode = $this->execute($input, $output);
 247          }
 248  
 249          return is_numeric($statusCode) ? (int) $statusCode : 0;
 250      }
 251  
 252      /**
 253       * Sets the code to execute when running this command.
 254       *
 255       * If this method is used, it overrides the code defined
 256       * in the execute() method.
 257       *
 258       * @param callable $code A callable(InputInterface $input, OutputInterface $output)
 259       *
 260       * @return Command The current instance
 261       *
 262       * @throws \InvalidArgumentException
 263       *
 264       * @see execute()
 265       */
 266      public function setCode($code)
 267      {
 268          if (!is_callable($code)) {
 269              throw new \InvalidArgumentException('Invalid callable provided to Command::setCode.');
 270          }
 271  
 272          $this->code = $code;
 273  
 274          return $this;
 275      }
 276  
 277      /**
 278       * Merges the application definition with the command definition.
 279       *
 280       * This method is not part of public API and should not be used directly.
 281       *
 282       * @param bool $mergeArgs Whether to merge or not the Application definition arguments to Command definition arguments
 283       */
 284      public function mergeApplicationDefinition($mergeArgs = true)
 285      {
 286          if (null === $this->application || (true === $this->applicationDefinitionMerged && ($this->applicationDefinitionMergedWithArgs || !$mergeArgs))) {
 287              return;
 288          }
 289  
 290          $this->definition->addOptions($this->application->getDefinition()->getOptions());
 291  
 292          if ($mergeArgs) {
 293              $currentArguments = $this->definition->getArguments();
 294              $this->definition->setArguments($this->application->getDefinition()->getArguments());
 295              $this->definition->addArguments($currentArguments);
 296          }
 297  
 298          $this->applicationDefinitionMerged = true;
 299          if ($mergeArgs) {
 300              $this->applicationDefinitionMergedWithArgs = true;
 301          }
 302      }
 303  
 304      /**
 305       * Sets an array of argument and option instances.
 306       *
 307       * @param array|InputDefinition $definition An array of argument and option instances or a definition instance
 308       *
 309       * @return Command The current instance
 310       */
 311      public function setDefinition($definition)
 312      {
 313          if ($definition instanceof InputDefinition) {
 314              $this->definition = $definition;
 315          } else {
 316              $this->definition->setDefinition($definition);
 317          }
 318  
 319          $this->applicationDefinitionMerged = false;
 320  
 321          return $this;
 322      }
 323  
 324      /**
 325       * Gets the InputDefinition attached to this Command.
 326       *
 327       * @return InputDefinition An InputDefinition instance
 328       */
 329      public function getDefinition()
 330      {
 331          return $this->definition;
 332      }
 333  
 334      /**
 335       * Gets the InputDefinition to be used to create XML and Text representations of this Command.
 336       *
 337       * Can be overridden to provide the original command representation when it would otherwise
 338       * be changed by merging with the application InputDefinition.
 339       *
 340       * This method is not part of public API and should not be used directly.
 341       *
 342       * @return InputDefinition An InputDefinition instance
 343       */
 344      public function getNativeDefinition()
 345      {
 346          return $this->getDefinition();
 347      }
 348  
 349      /**
 350       * Adds an argument.
 351       *
 352       * @param string $name        The argument name
 353       * @param int    $mode        The argument mode: InputArgument::REQUIRED or InputArgument::OPTIONAL
 354       * @param string $description A description text
 355       * @param mixed  $default     The default value (for InputArgument::OPTIONAL mode only)
 356       *
 357       * @return Command The current instance
 358       */
 359      public function addArgument($name, $mode = null, $description = '', $default = null)
 360      {
 361          $this->definition->addArgument(new InputArgument($name, $mode, $description, $default));
 362  
 363          return $this;
 364      }
 365  
 366      /**
 367       * Adds an option.
 368       *
 369       * @param string $name        The option name
 370       * @param string $shortcut    The shortcut (can be null)
 371       * @param int    $mode        The option mode: One of the InputOption::VALUE_* constants
 372       * @param string $description A description text
 373       * @param mixed  $default     The default value (must be null for InputOption::VALUE_NONE)
 374       *
 375       * @return Command The current instance
 376       */
 377      public function addOption($name, $shortcut = null, $mode = null, $description = '', $default = null)
 378      {
 379          $this->definition->addOption(new InputOption($name, $shortcut, $mode, $description, $default));
 380  
 381          return $this;
 382      }
 383  
 384      /**
 385       * Sets the name of the command.
 386       *
 387       * This method can set both the namespace and the name if
 388       * you separate them by a colon (:)
 389       *
 390       *     $command->setName('foo:bar');
 391       *
 392       * @param string $name The command name
 393       *
 394       * @return Command The current instance
 395       *
 396       * @throws \InvalidArgumentException When command name given is empty
 397       */
 398      public function setName($name)
 399      {
 400          $this->validateName($name);
 401  
 402          $this->name = $name;
 403  
 404          return $this;
 405      }
 406  
 407      /**
 408       * Returns the command name.
 409       *
 410       * @return string The command name
 411       */
 412      public function getName()
 413      {
 414          return $this->name;
 415      }
 416  
 417      /**
 418       * Sets the description for the command.
 419       *
 420       * @param string $description The description for the command
 421       *
 422       * @return Command The current instance
 423       */
 424      public function setDescription($description)
 425      {
 426          $this->description = $description;
 427  
 428          return $this;
 429      }
 430  
 431      /**
 432       * Returns the description for the command.
 433       *
 434       * @return string The description for the command
 435       */
 436      public function getDescription()
 437      {
 438          return $this->description;
 439      }
 440  
 441      /**
 442       * Sets the help for the command.
 443       *
 444       * @param string $help The help for the command
 445       *
 446       * @return Command The current instance
 447       */
 448      public function setHelp($help)
 449      {
 450          $this->help = $help;
 451  
 452          return $this;
 453      }
 454  
 455      /**
 456       * Returns the help for the command.
 457       *
 458       * @return string The help for the command
 459       */
 460      public function getHelp()
 461      {
 462          return $this->help;
 463      }
 464  
 465      /**
 466       * Returns the processed help for the command replacing the %command.name% and
 467       * %command.full_name% patterns with the real values dynamically.
 468       *
 469       * @return string The processed help for the command
 470       */
 471      public function getProcessedHelp()
 472      {
 473          $name = $this->name;
 474  
 475          $placeholders = array(
 476              '%command.name%',
 477              '%command.full_name%',
 478          );
 479          $replacements = array(
 480              $name,
 481              $_SERVER['PHP_SELF'].' '.$name,
 482          );
 483  
 484          return str_replace($placeholders, $replacements, $this->getHelp() ?: $this->getDescription());
 485      }
 486  
 487      /**
 488       * Sets the aliases for the command.
 489       *
 490       * @param string[] $aliases An array of aliases for the command
 491       *
 492       * @return Command The current instance
 493       */
 494      public function setAliases($aliases)
 495      {
 496          if (!is_array($aliases) && !$aliases instanceof \Traversable) {
 497              throw new \InvalidArgumentException('$aliases must be an array or an instance of \Traversable');
 498          }
 499  
 500          foreach ($aliases as $alias) {
 501              $this->validateName($alias);
 502          }
 503  
 504          $this->aliases = $aliases;
 505  
 506          return $this;
 507      }
 508  
 509      /**
 510       * Returns the aliases for the command.
 511       *
 512       * @return array An array of aliases for the command
 513       */
 514      public function getAliases()
 515      {
 516          return $this->aliases;
 517      }
 518  
 519      /**
 520       * Returns the synopsis for the command.
 521       *
 522       * @return string The synopsis
 523       */
 524      public function getSynopsis()
 525      {
 526          if (null === $this->synopsis) {
 527              $this->synopsis = trim(sprintf('%s %s', $this->name, $this->definition->getSynopsis()));
 528          }
 529  
 530          return $this->synopsis;
 531      }
 532  
 533      /**
 534       * Gets a helper instance by name.
 535       *
 536       * @param string $name The helper name
 537       *
 538       * @return mixed The helper value
 539       *
 540       * @throws \LogicException           if no HelperSet is defined
 541       * @throws \InvalidArgumentException if the helper is not defined
 542       */
 543      public function getHelper($name)
 544      {
 545          if (null === $this->helperSet) {
 546              throw new \LogicException(sprintf('Cannot retrieve helper "%s" because there is no HelperSet defined. Did you forget to add your command to the application or to set the application on the command using the setApplication() method? You can also set the HelperSet directly using the setHelperSet() method.', $name));
 547          }
 548  
 549          return $this->helperSet->get($name);
 550      }
 551  
 552      /**
 553       * Returns a text representation of the command.
 554       *
 555       * @return string A string representing the command
 556       *
 557       * @deprecated Deprecated since version 2.3, to be removed in 3.0.
 558       */
 559      public function asText()
 560      {
 561          $descriptor = new TextDescriptor();
 562  
 563          return $descriptor->describe($this);
 564      }
 565  
 566      /**
 567       * Returns an XML representation of the command.
 568       *
 569       * @param bool $asDom Whether to return a DOM or an XML string
 570       *
 571       * @return string|\DOMDocument An XML string representing the command
 572       *
 573       * @deprecated Deprecated since version 2.3, to be removed in 3.0.
 574       */
 575      public function asXml($asDom = false)
 576      {
 577          $descriptor = new XmlDescriptor();
 578  
 579          return $descriptor->describe($this, array('as_dom' => $asDom));
 580      }
 581  
 582      private function validateName($name)
 583      {
 584          if (!preg_match('/^[^\:]+(\:[^\:]+)*$/', $name)) {
 585              throw new \InvalidArgumentException(sprintf('Command name "%s" is invalid.', $name));
 586          }
 587      }
 588  }