primo commit

libraries/vendor/joomla/console/src/Command/AbstractCommand.php

@@ -0,0 +1,580 @@
+<?php
+
+/**
+ * Part of the Joomla Framework Console Package
+ *
+ * @copyright  Copyright (C) 2005 - 2021 Open Source Matters, Inc. All rights reserved.
+ * @license    GNU General Public License version 2 or later; see LICENSE
+ */
+
+namespace Joomla\Console\Command;
+
+use Joomla\Console\Application;
+use Symfony\Component\Console\Helper\HelperSet;
+use Symfony\Component\Console\Input\InputArgument;
+use Symfony\Component\Console\Input\InputDefinition;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+
+/**
+ * Base command class for a Joomla! command line application.
+ *
+ * @since  2.0.0
+ */
+abstract class AbstractCommand
+{
+    /**
+     * The default command name
+     *
+     * @var    string|null
+     * @since  2.0.0
+     */
+    protected static $defaultName;
+
+    /**
+     * The command's aliases.
+     *
+     * @var    string[]
+     * @since  2.0.0
+     */
+    private $aliases = [];
+
+    /**
+     * The application running this command.
+     *
+     * @var    Application|null
+     * @since  2.0.0
+     */
+    private $application;
+
+    /**
+     * Flag tracking whether the application definition has been merged to this command.
+     *
+     * @var    boolean
+     * @since  2.0.0
+     */
+    private $applicationDefinitionMerged = false;
+
+    /**
+     * Flag tracking whether the application definition with arguments has been merged to this command.
+     *
+     * @var    boolean
+     * @since  2.0.0
+     */
+    private $applicationDefinitionMergedWithArgs = false;
+
+    /**
+     * The command's input definition.
+     *
+     * @var    InputDefinition
+     * @since  2.0.0
+     */
+    private $definition;
+
+    /**
+     * The command's description.
+     *
+     * @var    string
+     * @since  2.0.0
+     */
+    private $description = '';
+
+    /**
+     * The command's help.
+     *
+     * @var    string
+     * @since  2.0.0
+     */
+    private $help = '';
+
+    /**
+     * The command's input helper set.
+     *
+     * @var    HelperSet|null
+     * @since  2.0.0
+     */
+    private $helperSet;
+
+    /**
+     * Flag tracking whether the command is hidden from the command listing.
+     *
+     * @var    boolean
+     * @since  2.0.0
+     */
+    private $hidden = false;
+
+    /**
+     * The command's name.
+     *
+     * @var    string
+     * @since  2.0.0
+     */
+    private $name;
+
+    /**
+     * The command's synopses.
+     *
+     * @var    string[]
+     * @since  2.0.0
+     */
+    private $synopsis = [];
+
+    /**
+     * Command constructor.
+     *
+     * @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
+     *
+     * @since   2.0.0
+     */
+    public function __construct(?string $name = null)
+    {
+        $this->definition = new InputDefinition();
+
+        if ($name !== null || null !== $name = static::getDefaultName()) {
+            $this->setName($name);
+        }
+
+        $this->configure();
+    }
+
+    /**
+     * Adds an argument to the input definition.
+     *
+     * @param   string    $name         The argument name
+     * @param   ?integer  $mode         The argument mode: InputArgument::REQUIRED or InputArgument::OPTIONAL
+     * @param   string    $description  A description text
+     * @param   mixed     $default      The default value (for InputArgument::OPTIONAL mode only)
+     *
+     * @return  $this
+     *
+     * @since   2.0.0
+     */
+    public function addArgument(string $name, ?int $mode = null, string $description = '', $default = null): self
+    {
+        $this->definition->addArgument(new InputArgument($name, $mode, $description, $default));
+
+        return $this;
+    }
+
+    /**
+     * Adds an option to the input definition.
+     *
+     * @param   string         $name         The option name
+     * @param   string|array   $shortcut     The shortcuts, can be null, a string of shortcuts delimited by | or an array of shortcuts
+     * @param   ?integer       $mode         The option mode: One of the VALUE_* constants
+     * @param   string         $description  A description text
+     * @param   ?mixed         $default      The default value (must be null for InputOption::VALUE_NONE)
+     *
+     * @return  $this
+     *
+     * @since   2.0.0
+     */
+    public function addOption(string $name, $shortcut = null, ?int $mode = null, $description = '', $default = null): self
+    {
+        $this->definition->addOption(new InputOption($name, $shortcut, $mode, $description, $default));
+
+        return $this;
+    }
+
+    /**
+     * Configure the command.
+     *
+     * @return  void
+     *
+     * @since   2.0.0
+     */
+    protected function configure(): void
+    {
+    }
+
+    /**
+     * Internal function to execute the command.
+     *
+     * @param   InputInterface   $input   The input to inject into the command.
+     * @param   OutputInterface  $output  The output to inject into the command.
+     *
+     * @return  integer  The command exit code
+     *
+     * @since   2.0.0
+     */
+    abstract protected function doExecute(InputInterface $input, OutputInterface $output): int;
+
+    /**
+     * Executes the command.
+     *
+     * @param   InputInterface   $input   The input to inject into the command.
+     * @param   OutputInterface  $output  The output to inject into the command.
+     *
+     * @return  integer  The command exit code
+     *
+     * @since   2.0.0
+     */
+    public function execute(InputInterface $input, OutputInterface $output): int
+    {
+        // Force the creation of the synopsis before the merge with the app definition
+        $this->getSynopsis(true);
+        $this->getSynopsis(false);
+
+        // Add the application arguments and options
+        $this->mergeApplicationDefinition();
+
+        // Bind the input against the command specific arguments/options
+        $input->bind($this->getDefinition());
+
+        $this->initialise($input, $output);
+
+        // Ensure that the command has a `command` argument so it does not fail validation
+        if ($input->hasArgument('command') && $input->getArgument('command') === null) {
+            $input->setArgument('command', $this->getName());
+        }
+
+        $input->validate();
+
+        return $this->doExecute($input, $output);
+    }
+
+    /**
+     * Get the command's aliases.
+     *
+     * @return  string[]
+     *
+     * @since   2.0.0
+     */
+    public function getAliases(): array
+    {
+        return $this->aliases;
+    }
+
+    /**
+     * Get the application object.
+     *
+     * @return  Application  The application object.
+     *
+     * @since   2.0.0
+     * @throws  \UnexpectedValueException if the application has not been set.
+     */
+    public function getApplication(): Application
+    {
+        if ($this->application) {
+            return $this->application;
+        }
+
+        throw new \UnexpectedValueException('Application not set in ' . \get_class($this));
+    }
+
+    /**
+     * Get the default command name for this class.
+     *
+     * This allows a command name to defined and referenced without instantiating the full command class.
+     *
+     * @return  string|null
+     *
+     * @since  2.0.0
+     */
+    public static function getDefaultName(): ?string
+    {
+        $class = \get_called_class();
+        $r     = new \ReflectionProperty($class, 'defaultName');
+
+        return $class === $r->class ? static::$defaultName : null;
+    }
+
+    /**
+     * Gets the InputDefinition attached to this command.
+     *
+     * @return  InputDefinition
+     *
+     * @since   2.0.0
+     */
+    public function getDefinition(): InputDefinition
+    {
+        return $this->definition;
+    }
+
+    /**
+     * Get the command's description.
+     *
+     * @return  string
+     *
+     * @since   2.0.0
+     */
+    public function getDescription(): string
+    {
+        return $this->description;
+    }
+
+    /**
+     * Get the command's help.
+     *
+     * @return  string
+     *
+     * @since   2.0.0
+     */
+    public function getHelp(): string
+    {
+        return $this->help;
+    }
+
+    /**
+     * Get the command's input helper set.
+     *
+     * @return  HelperSet|null
+     *
+     * @since   2.0.0
+     */
+    public function getHelperSet(): ?HelperSet
+    {
+        return $this->helperSet;
+    }
+
+    /**
+     * Get the command's name.
+     *
+     * @return  string|null
+     *
+     * @since   2.0.0
+     */
+    public function getName(): ?string
+    {
+        return $this->name;
+    }
+
+    /**
+     * Returns the processed help for the command.
+     *
+     * This method is used to replace placeholders in commands with the real values.
+     * By default, this supports `%command.name%` and `%command.full_name`.
+     *
+     * @return  string
+     *
+     * @since   2.0.0
+     */
+    public function getProcessedHelp(): string
+    {
+        $name = $this->getName();
+
+        $placeholders = [
+            '%command.name%',
+            '%command.full_name%',
+        ];
+
+        $replacements = [
+            $name,
+            $_SERVER['PHP_SELF'] . ' ' . $name,
+        ];
+
+        return str_replace($placeholders, $replacements, $this->getHelp() ?: $this->getDescription());
+    }
+
+    /**
+     * Get the command's synopsis.
+     *
+     * @param   boolean  $short  Flag indicating whether the short or long version of the synopsis should be returned
+     *
+     * @return  string
+     *
+     * @since   2.0.0
+     */
+    public function getSynopsis(bool $short = false): string
+    {
+        $key = $short ? 'short' : 'long';
+
+        if (!isset($this->synopsis[$key])) {
+            $this->synopsis[$key] = trim(sprintf('%s %s', $this->getName(), $this->getDefinition()->getSynopsis($short)));
+        }
+
+        return $this->synopsis[$key];
+    }
+
+    /**
+     * Internal hook to initialise the command after the input has been bound and before the input is validated.
+     *
+     * @param   InputInterface   $input   The input to inject into the command.
+     * @param   OutputInterface  $output  The output to inject into the command.
+     *
+     * @return  void
+     *
+     * @since   2.0.0
+     */
+    protected function initialise(InputInterface $input, OutputInterface $output): void
+    {
+    }
+
+    /**
+     * Check if the command is enabled in this environment.
+     *
+     * @return  boolean
+     *
+     * @since   2.0.0
+     */
+    public function isEnabled(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Check if the command is hidden from the command listing.
+     *
+     * @return  boolean
+     *
+     * @since   2.0.0
+     */
+    public function isHidden(): bool
+    {
+        return $this->hidden;
+    }
+
+    /**
+     * Merges the application definition with the command definition.
+     *
+     * @param   boolean  $mergeArgs  Flag indicating whether the application's definition arguments should be merged
+     *
+     * @return  void
+     *
+     * @since   2.0.0
+     * @internal  This method should not be relied on as part of the public API
+     */
+    final public function mergeApplicationDefinition(bool $mergeArgs = true): void
+    {
+        if (!$this->application || ($this->applicationDefinitionMerged && ($this->applicationDefinitionMergedWithArgs || !$mergeArgs))) {
+            return;
+        }
+
+        $this->getDefinition()->addOptions($this->getApplication()->getDefinition()->getOptions());
+
+        $this->applicationDefinitionMerged = true;
+
+        if ($mergeArgs) {
+            $currentArguments = $this->getDefinition()->getArguments();
+            $this->getDefinition()->setArguments($this->getApplication()->getDefinition()->getArguments());
+            $this->getDefinition()->addArguments($currentArguments);
+
+            $this->applicationDefinitionMergedWithArgs = true;
+        }
+    }
+
+    /**
+     * Set the command's aliases.
+     *
+     * @param   string[]  $aliases  The command aliases
+     *
+     * @return  void
+     *
+     * @since   2.0.0
+     */
+    public function setAliases(array $aliases): void
+    {
+        $this->aliases = $aliases;
+    }
+
+    /**
+     * Set the command's application.
+     *
+     * @param   ?Application  $application  The command's application
+     *
+     * @return  void
+     *
+     * @since   2.0.0
+     */
+    public function setApplication(?Application $application = null): void
+    {
+        $this->application = $application;
+
+        if ($application) {
+            $this->setHelperSet($application->getHelperSet());
+        } else {
+            $this->helperSet = null;
+        }
+    }
+
+    /**
+     * Sets the input definition for the command.
+     *
+     * @param   array|InputDefinition  $definition  Either an InputDefinition object or an array of objects to write to the definition.
+     *
+     * @return  void
+     *
+     * @since   2.0.0
+     */
+    public function setDefinition($definition): void
+    {
+        if ($definition instanceof InputDefinition) {
+            $this->definition = $definition;
+        } else {
+            $this->definition->setDefinition($definition);
+        }
+
+        $this->applicationDefinitionMerged = false;
+    }
+
+    /**
+     * Sets the description for the command.
+     *
+     * @param   string  $description  The description for the command
+     *
+     * @return  void
+     *
+     * @since   2.0.0
+     */
+    public function setDescription(string $description): void
+    {
+        $this->description = $description;
+    }
+
+    /**
+     * Sets the help for the command.
+     *
+     * @param   string  $help  The help for the command
+     *
+     * @return  void
+     *
+     * @since   2.0.0
+     */
+    public function setHelp(string $help): void
+    {
+        $this->help = $help;
+    }
+
+    /**
+     * Set the command's input helper set.
+     *
+     * @param   HelperSet  $helperSet  The helper set.
+     *
+     * @return  void
+     *
+     * @since   2.0.0
+     */
+    public function setHelperSet(HelperSet $helperSet): void
+    {
+        $this->helperSet = $helperSet;
+    }
+
+    /**
+     * Set whether this command is hidden from the command listing.
+     *
+     * @param   boolean  $hidden  Flag if this command is hidden.
+     *
+     * @return  void
+     *
+     * @since   2.0.0
+     */
+    public function setHidden(bool $hidden): void
+    {
+        $this->hidden = $hidden;
+    }
+
+    /**
+     * Set the command's name.
+     *
+     * @param   string  $name  The command name
+     *
+     * @return  void
+     *
+     * @since   2.0.0
+     */
+    public function setName(string $name): void
+    {
+        $this->name = $name;
+    }
+}