HelpController.php 13.3 KB
Newer Older
Alexander Makarov committed
1 2 3
<?php
/**
 * @link http://www.yiiframework.com/
Qiang Xue committed
4
 * @copyright Copyright (c) 2008 Yii Software LLC
Alexander Makarov committed
5 6 7
 * @license http://www.yiiframework.com/license/
 */

8
namespace yii\console\controllers;
Alexander Makarov committed
9

10
use Yii;
Qiang Xue committed
11 12 13
use yii\base\Application;
use yii\base\InlineAction;
use yii\console\Controller;
Qiang Xue committed
14
use yii\console\Exception;
15
use yii\helpers\Console;
Alexander Makarov committed
16
use yii\helpers\Inflector;
Qiang Xue committed
17

Alexander Makarov committed
18
/**
Qiang Xue committed
19
 * This command provides help information about console commands.
Alexander Makarov committed
20
 *
Qiang Xue committed
21 22 23
 * This command displays the available command list in
 * the application or the detailed instructions about using
 * a specific command.
Alexander Makarov committed
24
 *
Qiang Xue committed
25
 * This command can be used as follows on command line:
Qiang Xue committed
26 27
 *
 * ~~~
28
 * yii help [command name]
Qiang Xue committed
29 30
 * ~~~
 *
Qiang Xue committed
31 32
 * In the above, if the command name is not provided, all
 * available commands will be displayed.
Alexander Makarov committed
33
 *
34
 * @property array $commands All available command names. This property is read-only.
35
 *
Alexander Makarov committed
36 37 38
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
Qiang Xue committed
39
class HelpController extends Controller
Alexander Makarov committed
40
{
Qiang Xue committed
41 42 43 44
	/**
	 * Displays available commands or the detailed information
	 * about a particular command. For example,
	 *
Qiang Xue committed
45
	 * @param string $command The name of the command to show help about.
Qiang Xue committed
46
	 * If not provided, all available commands will be displayed.
Qiang Xue committed
47
	 * @return integer the exit status
Qiang Xue committed
48
	 * @throws Exception if the command for help is unknown
Qiang Xue committed
49
	 */
Qiang Xue committed
50
	public function actionIndex($command = null)
Qiang Xue committed
51
	{
Qiang Xue committed
52
		if ($command !== null) {
Qiang Xue committed
53
			$result = Yii::$app->createController($command);
Qiang Xue committed
54
			if ($result === false) {
Alexander Makarov committed
55
				throw new Exception(Yii::t('yii', 'No help for unknown command "{command}".', [
56
					'command' => $this->ansiFormat($command, Console::FG_YELLOW),
Alexander Makarov committed
57
				]));
Qiang Xue committed
58 59
			}

Qiang Xue committed
60
			list($controller, $actionID) = $result;
Qiang Xue committed
61

Qiang Xue committed
62 63
			$actions = $this->getActions($controller);
			if ($actionID !== '' || count($actions) === 1 && $actions[0] === $controller->defaultAction) {
64
				$this->getActionHelp($controller, $actionID);
Qiang Xue committed
65 66
			} else {
				$this->getControllerHelp($controller);
Qiang Xue committed
67
			}
Qiang Xue committed
68 69
		} else {
			$this->getHelp();
Qiang Xue committed
70 71 72 73 74 75 76 77 78
		}
	}

	/**
	 * Returns all available command names.
	 * @return array all available command names
	 */
	public function getCommands()
	{
Qiang Xue committed
79
		$commands = $this->getModuleCommands(Yii::$app);
Qiang Xue committed
80 81 82 83 84 85 86 87 88 89 90
		sort($commands);
		return array_unique($commands);
	}

	/**
	 * Returns all available actions of the specified controller.
	 * @param Controller $controller the controller instance
	 * @return array all available action IDs.
	 */
	public function getActions($controller)
	{
Qiang Xue committed
91
		$actions = array_keys($controller->actions());
Qiang Xue committed
92 93 94
		$class = new \ReflectionClass($controller);
		foreach ($class->getMethods() as $method) {
			$name = $method->getName();
Qiang Xue committed
95
			if ($method->isPublic() && !$method->isStatic() && strpos($name, 'action') === 0 && $name !== 'actions') {
Alexander Makarov committed
96
				$actions[] = Inflector::camel2id(substr($name, 6));
Qiang Xue committed
97 98 99 100 101 102 103 104 105 106 107 108 109
			}
		}
		sort($actions);
		return array_unique($actions);
	}

	/**
	 * Returns available commands of a specified module.
	 * @param \yii\base\Module $module the module instance
	 * @return array the available command names
	 */
	protected function getModuleCommands($module)
	{
Qiang Xue committed
110
		$prefix = $module instanceof Application ? '' : $module->getUniqueID() . '/';
Qiang Xue committed
111

Alexander Makarov committed
112
		$commands = [];
Qiang Xue committed
113
		foreach (array_keys($module->controllerMap) as $id) {
Qiang Xue committed
114 115 116 117 118 119 120 121
			$commands[] = $prefix . $id;
		}

		foreach ($module->getModules() as $id => $child) {
			if (($child = $module->getModule($id)) === null) {
				continue;
			}
			foreach ($this->getModuleCommands($child) as $command) {
122
				$commands[] = $command;
Qiang Xue committed
123 124 125
			}
		}

126 127 128 129 130 131 132
		$controllerPath = $module->getControllerPath();
		if (is_dir($controllerPath)) {
			$files = scandir($controllerPath);
			foreach ($files as $file) {
				if (strcmp(substr($file, -14), 'Controller.php') === 0) {
					$commands[] = $prefix . Inflector::camel2id(substr(basename($file), 0, -14));
				}
Qiang Xue committed
133 134 135 136 137 138 139 140 141
			}
		}

		return $commands;
	}

	/**
	 * Displays all available commands.
	 */
Qiang Xue committed
142
	protected function getHelp()
Qiang Xue committed
143
	{
Qiang Xue committed
144
		$commands = $this->getCommands();
145
		if (!empty($commands)) {
146
			$this->stdout("\nThe following commands are available:\n\n", Console::BOLD);
Qiang Xue committed
147
			foreach ($commands as $command) {
148
				echo "- " . $this->ansiFormat($command, Console::FG_YELLOW) . "\n";
Qiang Xue committed
149
			}
150
			$scriptName = $this->getScriptName();
151
			$this->stdout("\nTo see the help of each command, enter:\n", Console::BOLD);
152
			echo "\n  $scriptName " . $this->ansiFormat('help', Console::FG_YELLOW) . ' '
153
							. $this->ansiFormat('<command-name>', Console::FG_CYAN) . "\n\n";
Qiang Xue committed
154
		} else {
155
			$this->stdout("\nNo commands are found.\n\n", Console::BOLD);
Qiang Xue committed
156 157
		}
	}
Qiang Xue committed
158

Qiang Xue committed
159 160 161 162
	/**
	 * Displays the overall information of the command.
	 * @param Controller $controller the controller instance
	 */
Qiang Xue committed
163
	protected function getControllerHelp($controller)
Qiang Xue committed
164
	{
Qiang Xue committed
165 166 167 168 169 170 171
		$class = new \ReflectionClass($controller);
		$comment = strtr(trim(preg_replace('/^\s*\**( |\t)?/m', '', trim($class->getDocComment(), '/'))), "\r", '');
		if (preg_match('/^\s*@\w+/m', $comment, $matches, PREG_OFFSET_CAPTURE)) {
			$comment = trim(substr($comment, 0, $matches[0][1]));
		}

		if ($comment !== '') {
172 173
			$this->stdout("\nDESCRIPTION\n", Console::BOLD);
			echo "\n" . Console::renderColoredString($comment) . "\n\n";
Qiang Xue committed
174 175 176
		}

		$actions = $this->getActions($controller);
177
		if (!empty($actions)) {
178
			$this->stdout("\nSUB-COMMANDS\n\n", Console::BOLD);
Qiang Xue committed
179 180
			$prefix = $controller->getUniqueId();
			foreach ($actions as $action) {
181
				echo '- ' . $this->ansiFormat($prefix.'/'.$action, Console::FG_YELLOW);
Qiang Xue committed
182
				if ($action === $controller->defaultAction) {
183
					$this->stdout(' (default)', Console::FG_GREEN);
Qiang Xue committed
184
				}
Qiang Xue committed
185 186 187 188 189
				$summary = $this->getActionSummary($controller, $action);
				if ($summary !== '') {
					echo ': ' . $summary;
				}
				echo "\n";
Qiang Xue committed
190
			}
191
			$scriptName = $this->getScriptName();
192
			echo "\nTo see the detailed information about individual sub-commands, enter:\n";
193
			echo "\n  $scriptName " . $this->ansiFormat('help', Console::FG_YELLOW) . ' '
194
							. $this->ansiFormat('<sub-command>', Console::FG_CYAN) . "\n\n";
Qiang Xue committed
195
		}
Qiang Xue committed
196 197
	}

Qiang Xue committed
198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234
	/**
	 * Returns the short summary of the action.
	 * @param Controller $controller the controller instance
	 * @param string $actionID action ID
	 * @return string the summary about the action
	 */
	protected function getActionSummary($controller, $actionID)
	{
		$action = $controller->createAction($actionID);
		if ($action === null) {
			return '';
		}
		if ($action instanceof InlineAction) {
			$reflection = new \ReflectionMethod($controller, $action->actionMethod);
		} else {
			$reflection = new \ReflectionClass($action);
		}
		$tags = $this->parseComment($reflection->getDocComment());
		if ($tags['description'] !== '') {
			$limit = 73 - strlen($action->getUniqueId());
			if ($actionID === $controller->defaultAction) {
				$limit -= 10;
			}
			if ($limit < 0) {
				$limit = 50;
			}
			$description = $tags['description'];
			if (($pos = strpos($tags['description'], "\n")) !== false) {
				$description = substr($description, 0, $pos);
			}
			$text = substr($description, 0, $limit);
			return strlen($description) > $limit ? $text . '...' : $text;
		} else {
			return '';
		}
	}

Alexander Makarov committed
235
	/**
Qiang Xue committed
236 237 238
	 * Displays the detailed information of a command action.
	 * @param Controller $controller the controller instance
	 * @param string $actionID action ID
Qiang Xue committed
239
	 * @throws Exception if the action does not exist
Alexander Makarov committed
240
	 */
Qiang Xue committed
241
	protected function getActionHelp($controller, $actionID)
Alexander Makarov committed
242
	{
Qiang Xue committed
243 244
		$action = $controller->createAction($actionID);
		if ($action === null) {
Alexander Makarov committed
245
			throw new Exception(Yii::t('yii', 'No help for unknown sub-command "{command}".', [
246
				'command' => rtrim($controller->getUniqueId() . '/' . $actionID, '/'),
Alexander Makarov committed
247
			]));
Qiang Xue committed
248 249
		}
		if ($action instanceof InlineAction) {
Qiang Xue committed
250
			$method = new \ReflectionMethod($controller, $action->actionMethod);
Qiang Xue committed
251 252 253
		} else {
			$method = new \ReflectionMethod($action, 'run');
		}
Qiang Xue committed
254 255

		$tags = $this->parseComment($method->getDocComment());
256
		$options = $this->getOptionHelps($controller);
Qiang Xue committed
257 258

		if ($tags['description'] !== '') {
259 260
			$this->stdout("\nDESCRIPTION\n", Console::BOLD);
			echo "\n" . Console::renderColoredString($tags['description']) . "\n\n";
Qiang Xue committed
261
		}
Qiang Xue committed
262

263
		$this->stdout("\nUSAGE\n\n", Console::BOLD);
264
		$scriptName = $this->getScriptName();
Qiang Xue committed
265
		if ($action->id === $controller->defaultAction) {
266
			echo $scriptName . ' ' . $this->ansiFormat($controller->getUniqueId(), Console::FG_YELLOW);
Qiang Xue committed
267
		} else {
268
			echo $scriptName . ' ' . $this->ansiFormat($action->getUniqueId(), Console::FG_YELLOW);
Qiang Xue committed
269
		}
Alexander Makarov committed
270
		list ($required, $optional) = $this->getArgHelps($method, isset($tags['param']) ? $tags['param'] : []);
271 272
		foreach ($required as $arg => $description) {
			$this->stdout(' <' . $arg . '>', Console::FG_CYAN);
Alexander Makarov committed
273
		}
274 275
		foreach ($optional as $arg => $description) {
			$this->stdout(' [' . $arg . ']', Console::FG_CYAN);
Qiang Xue committed
276
		}
277
		if (!empty($options)) {
278
			$this->stdout(' [...options...]', Console::FG_RED);
279
		}
Qiang Xue committed
280
		echo "\n\n";
Qiang Xue committed
281

Qiang Xue committed
282 283
		if (!empty($required) || !empty($optional)) {
			echo implode("\n\n", array_merge($required, $optional)) . "\n\n";
Qiang Xue committed
284
		}
Qiang Xue committed
285

Qiang Xue committed
286
		$options = $this->getOptionHelps($controller);
287
		if (!empty($options)) {
288
			$this->stdout("\nOPTIONS\n\n", Console::BOLD);
Qiang Xue committed
289 290 291 292
			echo implode("\n\n", $options) . "\n\n";
		}
	}

Qiang Xue committed
293
	/**
Qiang Xue committed
294
	 * Returns the help information about arguments.
Qiang Xue committed
295
	 * @param \ReflectionMethod $method
Qiang Xue committed
296 297
	 * @param string $tags the parsed comment block related with arguments
	 * @return array the required and optional argument help information
Qiang Xue committed
298
	 */
Qiang Xue committed
299
	protected function getArgHelps($method, $tags)
Qiang Xue committed
300
	{
Qiang Xue committed
301
		if (is_string($tags)) {
Alexander Makarov committed
302
			$tags = [$tags];
Qiang Xue committed
303
		}
Qiang Xue committed
304
		$params = $method->getParameters();
Alexander Makarov committed
305
		$optional = $required = [];
Qiang Xue committed
306 307 308 309 310 311 312 313 314 315 316
		foreach ($params as $i => $param) {
			$name = $param->getName();
			$tag = isset($tags[$i]) ? $tags[$i] : '';
			if (preg_match('/^([^\s]+)\s+(\$\w+\s+)?(.*)/s', $tag, $matches)) {
				$type = $matches[1];
				$comment = $matches[3];
			} else {
				$type = null;
				$comment = $tag;
			}
			if ($param->isDefaultValueAvailable()) {
317
				$optional[$name] = $this->formatOptionHelp('- ' . $this->ansiFormat($name, Console::FG_CYAN), false, $type, $param->getDefaultValue(), $comment);
Qiang Xue committed
318
			} else {
319
				$required[$name] = $this->formatOptionHelp('- ' . $this->ansiFormat($name, Console::FG_CYAN), true, $type, null, $comment);
Qiang Xue committed
320 321
			}
		}
Qiang Xue committed
322

Alexander Makarov committed
323
		return [$required, $optional];
Qiang Xue committed
324 325 326
	}

	/**
Qiang Xue committed
327 328 329
	 * Returns the help information about the options available for a console controller.
	 * @param Controller $controller the console controller
	 * @return array the help information about the options
Qiang Xue committed
330
	 */
Qiang Xue committed
331
	protected function getOptionHelps($controller)
Qiang Xue committed
332
	{
Qiang Xue committed
333 334
		$optionNames = $controller->globalOptions();
		if (empty($optionNames)) {
Alexander Makarov committed
335
			return [];
Qiang Xue committed
336 337 338
		}

		$class = new \ReflectionClass($controller);
Alexander Makarov committed
339
		$options = [];
Qiang Xue committed
340 341
		foreach ($class->getProperties() as $property) {
			$name = $property->getName();
Qiang Xue committed
342 343
			if (!in_array($name, $optionNames, true)) {
				continue;
Qiang Xue committed
344
			}
Qiang Xue committed
345 346 347 348 349 350
			$defaultValue = $property->getValue($controller);
			$tags = $this->parseComment($property->getDocComment());
			if (isset($tags['var']) || isset($tags['property'])) {
				$doc = isset($tags['var']) ? $tags['var'] : $tags['property'];
				if (is_array($doc)) {
					$doc = reset($doc);
Qiang Xue committed
351
				}
Qiang Xue committed
352 353 354 355 356 357 358
				if (preg_match('/^([^\s]+)(.*)/s', $doc, $matches)) {
					$type = $matches[1];
					$comment = $matches[2];
				} else {
					$type = null;
					$comment = $doc;
				}
359
				$options[$name] = $this->formatOptionHelp($this->ansiFormat('--' . $name, Console::FG_RED), false, $type, $defaultValue, $comment);
Qiang Xue committed
360
			} else {
361
				$options[$name] = $this->formatOptionHelp($this->ansiFormat('--' . $name, Console::FG_RED), false, null, $defaultValue, '');
Qiang Xue committed
362 363 364 365
			}
		}
		ksort($options);
		return $options;
Alexander Makarov committed
366
	}
Qiang Xue committed
367 368 369 370 371 372 373 374

	/**
	 * Parses the comment block into tags.
	 * @param string $comment the comment block
	 * @return array the parsed tags
	 */
	protected function parseComment($comment)
	{
Alexander Makarov committed
375
		$tags = [];
Qiang Xue committed
376 377 378 379 380 381 382 383 384 385
		$comment = "@description \n" . strtr(trim(preg_replace('/^\s*\**( |\t)?/m', '', trim($comment, '/'))), "\r", '');
		$parts = preg_split('/^\s*@/m', $comment, -1, PREG_SPLIT_NO_EMPTY);
		foreach ($parts as $part) {
			if (preg_match('/^(\w+)(.*)/ms', trim($part), $matches)) {
				$name = $matches[1];
				if (!isset($tags[$name])) {
					$tags[$name] = trim($matches[2]);
				} elseif (is_array($tags[$name])) {
					$tags[$name][] = trim($matches[2]);
				} else {
Alexander Makarov committed
386
					$tags[$name] = [$tags[$name], trim($matches[2])];
Qiang Xue committed
387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410
				}
			}
		}
		return $tags;
	}

	/**
	 * Generates a well-formed string for an argument or option.
	 * @param string $name the name of the argument or option
	 * @param boolean $required whether the argument is required
	 * @param string $type the type of the option or argument
	 * @param mixed $defaultValue the default value of the option or argument
	 * @param string $comment comment about the option or argument
	 * @return string the formatted string for the argument or option
	 */
	protected function formatOptionHelp($name, $required, $type, $defaultValue, $comment)
	{
		$doc = '';
		$comment = trim($comment);

		if ($defaultValue !== null && !is_array($defaultValue)) {
			if ($type === null) {
				$type = gettype($defaultValue);
			}
411 412 413 414
			if (is_bool($defaultValue)) {
				// show as integer to avoid confusion
				$defaultValue = (int)$defaultValue;
			}
Qiang Xue committed
415 416 417 418 419 420 421 422 423 424 425 426 427 428
			$doc = "$type (defaults to " . var_export($defaultValue, true) . ")";
		} elseif (trim($type) !== '') {
			$doc = $type;
		}

		if ($doc === '') {
			$doc = $comment;
		} elseif ($comment !== '') {
			$doc .= "\n" . preg_replace("/^/m", "  ", $comment);
		}

		$name = $required ? "$name (required)" : $name;
		return $doc === '' ? $name : "$name: $doc";
	}
429 430 431 432 433 434 435 436

	/**
	 * @return string the name of the cli script currently running.
	 */
	protected function getScriptName()
	{
		return basename(Yii::$app->request->scriptFile);
	}
Zander Baldwin committed
437
}