[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\Command;
  10  
  11  use Joomla\Console\Application;
  12  use Symfony\Component\Console\Helper\HelperSet;
  13  use Symfony\Component\Console\Input\InputArgument;
  14  use Symfony\Component\Console\Input\InputDefinition;
  15  use Symfony\Component\Console\Input\InputInterface;
  16  use Symfony\Component\Console\Input\InputOption;
  17  use Symfony\Component\Console\Output\OutputInterface;
  18  
  19  /**
  20   * Base command class for a Joomla! command line application.
  21   *
  22   * @since  2.0.0
  23   */
  24  abstract class AbstractCommand
  25  {
  26      /**
  27       * The default command name
  28       *
  29       * @var    string|null
  30       * @since  2.0.0
  31       */
  32      protected static $defaultName;
  33  
  34      /**
  35       * The command's aliases.
  36       *
  37       * @var    string[]
  38       * @since  2.0.0
  39       */
  40      private $aliases = [];
  41  
  42      /**
  43       * The application running this command.
  44       *
  45       * @var    Application|null
  46       * @since  2.0.0
  47       */
  48      private $application;
  49  
  50      /**
  51       * Flag tracking whether the application definition has been merged to this command.
  52       *
  53       * @var    boolean
  54       * @since  2.0.0
  55       */
  56      private $applicationDefinitionMerged = false;
  57  
  58      /**
  59       * Flag tracking whether the application definition with arguments has been merged to this command.
  60       *
  61       * @var    boolean
  62       * @since  2.0.0
  63       */
  64      private $applicationDefinitionMergedWithArgs = false;
  65  
  66      /**
  67       * The command's input definition.
  68       *
  69       * @var    InputDefinition
  70       * @since  2.0.0
  71       */
  72      private $definition;
  73  
  74      /**
  75       * The command's description.
  76       *
  77       * @var    string
  78       * @since  2.0.0
  79       */
  80      private $description = '';
  81  
  82      /**
  83       * The command's help.
  84       *
  85       * @var    string
  86       * @since  2.0.0
  87       */
  88      private $help = '';
  89  
  90      /**
  91       * The command's input helper set.
  92       *
  93       * @var    HelperSet|null
  94       * @since  2.0.0
  95       */
  96      private $helperSet;
  97  
  98      /**
  99       * Flag tracking whether the command is hidden from the command listing.
 100       *
 101       * @var    boolean
 102       * @since  2.0.0
 103       */
 104      private $hidden = false;
 105  
 106      /**
 107       * The command's name.
 108       *
 109       * @var    string
 110       * @since  2.0.0
 111       */
 112      private $name;
 113  
 114      /**
 115       * The command's synopses.
 116       *
 117       * @var    string[]
 118       * @since  2.0.0
 119       */
 120      private $synopsis = [];
 121  
 122      /**
 123       * Command constructor.
 124       *
 125       * @param   string|null  $name  The name of the command; if the name is empty and no default is set, a name must be set in the configure() method
 126       *
 127       * @since   2.0.0
 128       */
 129  	public function __construct(?string $name = null)
 130      {
 131          $this->definition = new InputDefinition;
 132  
 133          if ($name !== null || null !== $name = static::getDefaultName())
 134          {
 135              $this->setName($name);
 136          }
 137  
 138          $this->configure();
 139      }
 140  
 141      /**
 142       * Adds an argument to the input definition.
 143       *
 144       * @param   string   $name         The argument name
 145       * @param   integer  $mode         The argument mode: InputArgument::REQUIRED or InputArgument::OPTIONAL
 146       * @param   string   $description  A description text
 147       * @param   mixed    $default      The default value (for InputArgument::OPTIONAL mode only)
 148       *
 149       * @return  $this
 150       *
 151       * @since   2.0.0
 152       */
 153  	public function addArgument(string $name, ?int $mode = null, string $description = '', $default = null): self
 154      {
 155          $this->definition->addArgument(new InputArgument($name, $mode, $description, $default));
 156  
 157          return $this;
 158      }
 159  
 160      /**
 161       * Adds an option to the input definition.
 162       *
 163       * @param   string        $name         The option name
 164       * @param   string|array  $shortcut     The shortcuts, can be null, a string of shortcuts delimited by | or an array of shortcuts
 165       * @param   integer       $mode         The option mode: One of the VALUE_* constants
 166       * @param   string        $description  A description text
 167       * @param   mixed         $default      The default value (must be null for InputOption::VALUE_NONE)
 168       *
 169       * @return  $this
 170       *
 171       * @since   2.0.0
 172       */
 173  	public function addOption(string $name, $shortcut = null, ?int $mode = null, $description = '', $default = null): self
 174      {
 175          $this->definition->addOption(new InputOption($name, $shortcut, $mode, $description, $default));
 176  
 177          return $this;
 178      }
 179  
 180      /**
 181       * Configure the command.
 182       *
 183       * @return  void
 184       *
 185       * @since   2.0.0
 186       */
 187  	protected function configure(): void
 188      {
 189      }
 190  
 191      /**
 192       * Internal function to execute the command.
 193       *
 194       * @param   InputInterface   $input   The input to inject into the command.
 195       * @param   OutputInterface  $output  The output to inject into the command.
 196       *
 197       * @return  integer  The command exit code
 198       *
 199       * @since   2.0.0
 200       */
 201      abstract protected function doExecute(InputInterface $input, OutputInterface $output): int;
 202  
 203      /**
 204       * Executes the command.
 205       *
 206       * @param   InputInterface   $input   The input to inject into the command.
 207       * @param   OutputInterface  $output  The output to inject into the command.
 208       *
 209       * @return  integer  The command exit code
 210       *
 211       * @since   2.0.0
 212       */
 213  	public function execute(InputInterface $input, OutputInterface $output): int
 214      {
 215          // Force the creation of the synopsis before the merge with the app definition
 216          $this->getSynopsis(true);
 217          $this->getSynopsis(false);
 218  
 219          // Add the application arguments and options
 220          $this->mergeApplicationDefinition();
 221  
 222          // Bind the input against the command specific arguments/options
 223          $input->bind($this->getDefinition());
 224  
 225          $this->initialise($input, $output);
 226  
 227          // Ensure that the command has a `command` argument so it does not fail validation
 228          if ($input->hasArgument('command') && $input->getArgument('command') === null)
 229          {
 230              $input->setArgument('command', $this->getName());
 231          }
 232  
 233          $input->validate();
 234  
 235          return $this->doExecute($input, $output);
 236      }
 237  
 238      /**
 239       * Get the command's aliases.
 240       *
 241       * @return  string[]
 242       *
 243       * @since   2.0.0
 244       */
 245  	public function getAliases(): array
 246      {
 247          return $this->aliases;
 248      }
 249  
 250      /**
 251       * Get the application object.
 252       *
 253       * @return  Application  The application object.
 254       *
 255       * @since   2.0.0
 256       * @throws  \UnexpectedValueException if the application has not been set.
 257       */
 258  	public function getApplication(): Application
 259      {
 260          if ($this->application)
 261          {
 262              return $this->application;
 263          }
 264  
 265          throw new \UnexpectedValueException('Application not set in ' . \get_class($this));
 266      }
 267  
 268      /**
 269       * Get the default command name for this class.
 270       *
 271       * This allows a command name to defined and referenced without instantiating the full command class.
 272       *
 273       * @return  string|null
 274       *
 275       * @since  2.0.0
 276       */
 277  	public static function getDefaultName(): ?string
 278      {
 279          $class = \get_called_class();
 280          $r     = new \ReflectionProperty($class, 'defaultName');
 281  
 282          return $class === $r->class ? static::$defaultName : null;
 283      }
 284  
 285      /**
 286       * Gets the InputDefinition attached to this command.
 287       *
 288       * @return  InputDefinition
 289       *
 290       * @since   2.0.0
 291       */
 292  	public function getDefinition(): InputDefinition
 293      {
 294          return $this->definition;
 295      }
 296  
 297      /**
 298       * Get the command's description.
 299       *
 300       * @return  string
 301       *
 302       * @since   2.0.0
 303       */
 304  	public function getDescription(): string
 305      {
 306          return $this->description;
 307      }
 308  
 309      /**
 310       * Get the command's help.
 311       *
 312       * @return  string
 313       *
 314       * @since   2.0.0
 315       */
 316  	public function getHelp(): string
 317      {
 318          return $this->help;
 319      }
 320  
 321      /**
 322       * Get the command's input helper set.
 323       *
 324       * @return  HelperSet|null
 325       *
 326       * @since   2.0.0
 327       */
 328  	public function getHelperSet(): ?HelperSet
 329      {
 330          return $this->helperSet;
 331      }
 332  
 333      /**
 334       * Get the command's name.
 335       *
 336       * @return  string|null
 337       *
 338       * @since   2.0.0
 339       */
 340  	public function getName(): ?string
 341      {
 342          return $this->name;
 343      }
 344  
 345      /**
 346       * Returns the processed help for the command.
 347       *
 348       * This method is used to replace placeholders in commands with the real values.
 349       * By default, this supports `%command.name%` and `%command.full_name`.
 350       *
 351       * @return  string
 352       *
 353       * @since   2.0.0
 354       */
 355  	public function getProcessedHelp(): string
 356      {
 357          $name = $this->getName();
 358  
 359          $placeholders = [
 360              '%command.name%',
 361              '%command.full_name%',
 362          ];
 363  
 364          $replacements = [
 365              $name,
 366              $_SERVER['PHP_SELF'] . ' ' . $name,
 367          ];
 368  
 369          return str_replace($placeholders, $replacements, $this->getHelp() ?: $this->getDescription());
 370      }
 371  
 372      /**
 373       * Get the command's synopsis.
 374       *
 375       * @param   boolean  $short  Flag indicating whether the short or long version of the synopsis should be returned
 376       *
 377       * @return  string
 378       *
 379       * @since   2.0.0
 380       */
 381  	public function getSynopsis(bool $short = false): string
 382      {
 383          $key = $short ? 'short' : 'long';
 384  
 385          if (!isset($this->synopsis[$key]))
 386          {
 387              $this->synopsis[$key] = trim(sprintf('%s %s', $this->getName(), $this->getDefinition()->getSynopsis($short)));
 388          }
 389  
 390          return $this->synopsis[$key];
 391      }
 392  
 393      /**
 394       * Internal hook to initialise the command after the input has been bound and before the input is validated.
 395       *
 396       * @param   InputInterface   $input   The input to inject into the command.
 397       * @param   OutputInterface  $output  The output to inject into the command.
 398       *
 399       * @return  void
 400       *
 401       * @since   2.0.0
 402       */
 403  	protected function initialise(InputInterface $input, OutputInterface $output): void
 404      {
 405      }
 406  
 407      /**
 408       * Check if the command is enabled in this environment.
 409       *
 410       * @return  boolean
 411       *
 412       * @since   2.0.0
 413       */
 414  	public function isEnabled(): bool
 415      {
 416          return true;
 417      }
 418  
 419      /**
 420       * Check if the command is hidden from the command listing.
 421       *
 422       * @return  boolean
 423       *
 424       * @since   2.0.0
 425       */
 426  	public function isHidden(): bool
 427      {
 428          return $this->hidden;
 429      }
 430  
 431      /**
 432       * Merges the application definition with the command definition.
 433       *
 434       * @param   boolean  $mergeArgs  Flag indicating whether the application's definition arguments should be merged
 435       *
 436       * @return  void
 437       *
 438       * @since   2.0.0
 439       * @internal  This method should not be relied on as part of the public API
 440       */
 441  	final public function mergeApplicationDefinition(bool $mergeArgs = true): void
 442      {
 443          if (!$this->application || ($this->applicationDefinitionMerged && ($this->applicationDefinitionMergedWithArgs || !$mergeArgs)))
 444          {
 445              return;
 446          }
 447  
 448          $this->getDefinition()->addOptions($this->getApplication()->getDefinition()->getOptions());
 449  
 450          $this->applicationDefinitionMerged = true;
 451  
 452          if ($mergeArgs)
 453          {
 454              $currentArguments = $this->getDefinition()->getArguments();
 455              $this->getDefinition()->setArguments($this->getApplication()->getDefinition()->getArguments());
 456              $this->getDefinition()->addArguments($currentArguments);
 457  
 458              $this->applicationDefinitionMergedWithArgs = true;
 459          }
 460      }
 461  
 462      /**
 463       * Set the command's aliases.
 464       *
 465       * @param   string[]  $aliases  The command aliases
 466       *
 467       * @return  void
 468       *
 469       * @since   2.0.0
 470       */
 471  	public function setAliases(array $aliases): void
 472      {
 473          $this->aliases = $aliases;
 474      }
 475  
 476      /**
 477       * Set the command's application.
 478       *
 479       * @param   Application  $application  The command's application
 480       *
 481       * @return  void
 482       *
 483       * @since   2.0.0
 484       */
 485  	public function setApplication(?Application $application = null): void
 486      {
 487          $this->application = $application;
 488  
 489          if ($application)
 490          {
 491              $this->setHelperSet($application->getHelperSet());
 492          }
 493          else
 494          {
 495              $this->helperSet = null;
 496          }
 497      }
 498  
 499      /**
 500       * Sets the input definition for the command.
 501       *
 502       * @param   array|InputDefinition  $definition  Either an InputDefinition object or an array of objects to write to the definition.
 503       *
 504       * @return  void
 505       *
 506       * @since   2.0.0
 507       */
 508  	public function setDefinition($definition): void
 509      {
 510          if ($definition instanceof InputDefinition)
 511          {
 512              $this->definition = $definition;
 513          }
 514          else
 515          {
 516              $this->definition->setDefinition($definition);
 517          }
 518  
 519          $this->applicationDefinitionMerged = false;
 520      }
 521  
 522      /**
 523       * Sets the description for the command.
 524       *
 525       * @param   string  $description  The description for the command
 526       *
 527       * @return  void
 528       *
 529       * @since   2.0.0
 530       */
 531  	public function setDescription(string $description): void
 532      {
 533          $this->description = $description;
 534      }
 535  
 536      /**
 537       * Sets the help for the command.
 538       *
 539       * @param   string  $help  The help for the command
 540       *
 541       * @return  void
 542       *
 543       * @since   2.0.0
 544       */
 545  	public function setHelp(string $help): void
 546      {
 547          $this->help = $help;
 548      }
 549  
 550      /**
 551       * Set the command's input helper set.
 552       *
 553       * @param   HelperSet  $helperSet  The helper set.
 554       *
 555       * @return  void
 556       *
 557       * @since   2.0.0
 558       */
 559  	public function setHelperSet(HelperSet $helperSet): void
 560      {
 561          $this->helperSet = $helperSet;
 562      }
 563  
 564      /**
 565       * Set whether this command is hidden from the command listing.
 566       *
 567       * @param   boolean  $hidden  Flag if this command is hidden.
 568       *
 569       * @return  void
 570       *
 571       * @since   2.0.0
 572       */
 573  	public function setHidden(bool $hidden): void
 574      {
 575          $this->hidden = $hidden;
 576      }
 577  
 578      /**
 579       * Set the command's name.
 580       *
 581       * @param   string  $name  The command name
 582       *
 583       * @return  void
 584       *
 585       * @since   2.0.0
 586       */
 587  	public function setName(string $name): void
 588      {
 589          $this->name = $name;
 590      }
 591  }