[TASK] Streamline return tags in phpdocs
[Packages/TYPO3.CMS.git] / 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 * ./cli_dispatch.phpsh 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 }