typo3/sysext/extbase/Classes/Command/HelpCommandController.php

   1 <?php
   2 namespace TYPO3\CMS\Extbase\Command;
   3
   4 /*
   5  * This file is part of the TYPO3 CMS project.
   6  *
   7  * It is free software; you can redistribute it and/or modify it under
   8  * the terms of the GNU General Public License, either version 2
   9  * of the License, or any later version.
  10  *
  11  * For the full copyright and license information, please read the
  12  * LICENSE.txt file that was distributed with this source code.
  13  *
  14  * The TYPO3 project - inspiring people to share!
  15  */
  16
  17 /**
  18  * A Command Controller which provides help for available commands
  19  *
  20  * @license http://www.gnu.org/licenses/lgpl.html GNU Lesser General Public License, version 3 or later
  21  */
  22 class HelpCommandController extends \TYPO3\CMS\Extbase\Mvc\Controller\CommandController
  23 {
  24     /**
  25      * @var \TYPO3\CMS\Extbase\Mvc\Cli\CommandManager
  26      */
  27     protected $commandManager;
  28
  29     /**
  30      * @var array
  31      */
  32     protected $commandsByExtensionsAndControllers = [];
  33
  34     /**
  35      * @param \TYPO3\CMS\Extbase\Mvc\Cli\CommandManager $commandManager
  36      */
  37     public function injectCommandManager(\TYPO3\CMS\Extbase\Mvc\Cli\CommandManager $commandManager)
  38     {
  39         $this->commandManager = $commandManager;
  40     }
  41
  42     /**
  43      * Displays a short, general help message
  44      *
  45      * This only outputs the Extbase version number, context and some hint about how to
  46      * get more help about commands.
  47      *
  48      * @internal
  49      */
  50     public function helpStubCommand()
  51     {
  52         $this->outputLine('Extbase %s', [TYPO3_version]);
  53         $this->outputLine('usage: ' . $this->request->getCallingScript() . ' <command identifier>');
  54         $this->outputLine();
  55         $this->outputLine('See \'' . $this->request->getCallingScript() . ' help\' for a list of all available commands.');
  56         $this->outputLine();
  57     }
  58
  59     /**
  60      * Display help for a command
  61      *
  62      * The help command displays help for a given command:
  63      * ./typo3/sysext/core/bin/typo3 extbase:help <command identifier>
  64      *
  65      * @param string $commandIdentifier Identifier of a command for more details
  66      * @cli
  67      */
  68     public function helpCommand($commandIdentifier = null)
  69     {
  70         if ($commandIdentifier === null) {
  71             $this->displayHelpIndex();
  72         } else {
  73             try {
  74                 $command = $this->commandManager->getCommandByIdentifier($commandIdentifier);
  75             } catch (\TYPO3\CMS\Extbase\Mvc\Exception\CommandException $exception) {
  76                 $this->outputLine($exception->getMessage());
  77                 return;
  78             }
  79             $this->displayHelpForCommand($command);
  80         }
  81     }
  82
  83     /**
  84      * Builds an index of all commands that are available
  85      */
  86     protected function displayHelpIndex()
  87     {
  88         $this->buildCommandsIndex();
  89         $this->outputLine('Extbase %s', [TYPO3_version]);
  90         $this->outputLine('usage: ' . $this->request->getCallingScript() . ' <command identifier>');
  91         $this->outputLine();
  92         $this->outputLine('The following commands are currently available:');
  93         foreach ($this->commandsByExtensionsAndControllers as $extensionKey => $commandControllers) {
  94             $this->outputLine('');
  95             $this->outputLine('EXTENSION "%s":', [strtoupper($extensionKey)]);
  96             $this->outputLine(str_repeat('-', $this->output->getMaximumLineLength()));
  97             foreach ($commandControllers as $commands) {
  98                 foreach ($commands as $command) {
  99                     $description = wordwrap($command->getShortDescription(), $this->output->getMaximumLineLength() - 43, PHP_EOL . str_repeat(' ', 43), true);
 100                     $shortCommandIdentifier = $this->commandManager->getShortestIdentifierForCommand($command);
 101                     $this->outputLine('%-2s%-40s %s', [' ', $shortCommandIdentifier, $description]);
 102                 }
 103                 $this->outputLine();
 104             }
 105         }
 106         $this->outputLine('See \'' . $this->request->getCallingScript() . ' help <command identifier>\' for more information about a specific command.');
 107         $this->outputLine();
 108     }
 109
 110     /**
 111      * Render help text for a single command
 112      *
 113      * @param \TYPO3\CMS\Extbase\Mvc\Cli\Command $command
 114      */
 115     protected function displayHelpForCommand(\TYPO3\CMS\Extbase\Mvc\Cli\Command $command)
 116     {
 117         $this->outputLine();
 118         $this->outputLine($command->getShortDescription());
 119         $this->outputLine();
 120         $this->outputLine('COMMAND:');
 121         $this->outputLine('%-2s%s', [' ', $command->getCommandIdentifier()]);
 122         $commandArgumentDefinitions = $command->getArgumentDefinitions();
 123         $usage = '';
 124         $hasOptions = false;
 125         foreach ($commandArgumentDefinitions as $commandArgumentDefinition) {
 126             if (!$commandArgumentDefinition->isRequired()) {
 127                 $hasOptions = true;
 128             } else {
 129                 $usage .= sprintf(' <%s>', strtolower(preg_replace('/([A-Z])/', ' $1', $commandArgumentDefinition->getName())));
 130             }
 131         }
 132         $usage = $this->request->getCallingScript() . ' ' . $this->commandManager->getShortestIdentifierForCommand($command) . ($hasOptions ? ' [<options>]' : '') . $usage;
 133         $this->outputLine();
 134         $this->outputLine('USAGE:');
 135         $this->outputLine('  ' . $usage);
 136         $argumentDescriptions = [];
 137         $optionDescriptions = [];
 138         if ($command->hasArguments()) {
 139             foreach ($commandArgumentDefinitions as $commandArgumentDefinition) {
 140                 $argumentDescription = $commandArgumentDefinition->getDescription();
 141                 $argumentDescription = wordwrap($argumentDescription, $this->output->getMaximumLineLength() - 23, PHP_EOL . str_repeat(' ', 23), true);
 142                 if ($commandArgumentDefinition->isRequired()) {
 143                     $argumentDescriptions[] = vsprintf('  %-20s %s', [$commandArgumentDefinition->getDashedName(), $argumentDescription]);
 144                 } else {
 145                     $optionDescriptions[] = vsprintf('  %-20s %s', [$commandArgumentDefinition->getDashedName(), $argumentDescription]);
 146                 }
 147             }
 148         }
 149         if (!empty($argumentDescriptions)) {
 150             $this->outputLine();
 151             $this->outputLine('ARGUMENTS:');
 152             foreach ($argumentDescriptions as $argumentDescription) {
 153                 $this->outputLine($argumentDescription);
 154             }
 155         }
 156         if (!empty($optionDescriptions)) {
 157             $this->outputLine();
 158             $this->outputLine('OPTIONS:');
 159             foreach ($optionDescriptions as $optionDescription) {
 160                 $this->outputLine($optionDescription);
 161             }
 162         }
 163         if ($command->getDescription() !== '') {
 164             $this->outputLine();
 165             $this->outputLine('DESCRIPTION:');
 166             $descriptionLines = explode(LF, $command->getDescription());
 167             foreach ($descriptionLines as $descriptionLine) {
 168                 $this->outputLine('%-2s%s', [' ', $descriptionLine]);
 169             }
 170         }
 171         $relatedCommandIdentifiers = $command->getRelatedCommandIdentifiers();
 172         if ($relatedCommandIdentifiers !== []) {
 173             $this->outputLine();
 174             $this->outputLine('SEE ALSO:');
 175             foreach ($relatedCommandIdentifiers as $commandIdentifier) {
 176                 $command = $this->commandManager->getCommandByIdentifier($commandIdentifier);
 177                 $this->outputLine('%-2s%s (%s)', [' ', $commandIdentifier, $command->getShortDescription()]);
 178             }
 179         }
 180         $this->outputLine();
 181     }
 182
 183     /**
 184      * Displays an error message
 185      *
 186      * @internal
 187      * @param \TYPO3\CMS\Extbase\Mvc\Exception\CommandException $exception
 188      */
 189     public function errorCommand(\TYPO3\CMS\Extbase\Mvc\Exception\CommandException $exception)
 190     {
 191         $this->outputLine($exception->getMessage());
 192         if ($exception instanceof \TYPO3\CMS\Extbase\Mvc\Exception\AmbiguousCommandIdentifierException) {
 193             $this->outputLine('Please specify the complete command identifier. Matched commands:');
 194             foreach ($exception->getMatchingCommands() as $matchingCommand) {
 195                 $this->outputLine('    %s', [$matchingCommand->getCommandIdentifier()]);
 196             }
 197         }
 198         $this->outputLine('');
 199         $this->outputLine('Enter "' . $this->request->getCallingScript() . ' help" for an overview of all available commands');
 200         $this->outputLine('or "' . $this->request->getCallingScript() . ' help <command identifier>" for a detailed description of the corresponding command.');
 201     }
 202
 203     /**
 204      * Builds an index of available commands. For each of them a Command object is
 205      * added to the commands array of this class.
 206      */
 207     protected function buildCommandsIndex()
 208     {
 209         $availableCommands = $this->commandManager->getAvailableCommands();
 210         foreach ($availableCommands as $command) {
 211             if ($command->isInternal()) {
 212                 continue;
 213             }
 214             $commandIdentifier = $command->getCommandIdentifier();
 215             $extensionKey = strstr($commandIdentifier, ':', true);
 216             $commandControllerClassName = $command->getControllerClassName();
 217             $commandName = $command->getControllerCommandName();
 218             $this->commandsByExtensionsAndControllers[$extensionKey][$commandControllerClassName][$commandName] = $command;
 219         }
 220     }
 221 }