HelpController.php 13.2 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
			}
		}

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

		return $commands;
	}

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

Qiang Xue committed
156 157 158 159
	/**
	 * Displays the overall information of the command.
	 * @param Controller $controller the controller instance
	 */
Qiang Xue committed
160
	protected function getControllerHelp($controller)
Qiang Xue committed
161
	{
Qiang Xue committed
162 163 164 165 166 167 168
		$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 !== '') {
169 170
			$this->stdout("\nDESCRIPTION\n", Console::BOLD);
			echo "\n" . Console::renderColoredString($comment) . "\n\n";
Qiang Xue committed
171 172 173
		}

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

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

		$tags = $this->parseComment($method->getDocComment());
253
		$options = $this->getOptionHelps($controller);
Qiang Xue committed
254 255

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

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

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

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

Qiang Xue committed
290
	/**
Qiang Xue committed
291
	 * Returns the help information about arguments.
Qiang Xue committed
292
	 * @param \ReflectionMethod $method
Qiang Xue committed
293 294
	 * @param string $tags the parsed comment block related with arguments
	 * @return array the required and optional argument help information
Qiang Xue committed
295
	 */
Qiang Xue committed
296
	protected function getArgHelps($method, $tags)
Qiang Xue committed
297
	{
Qiang Xue committed
298
		if (is_string($tags)) {
Alexander Makarov committed
299
			$tags = [$tags];
Qiang Xue committed
300
		}
Qiang Xue committed
301
		$params = $method->getParameters();
Alexander Makarov committed
302
		$optional = $required = [];
Qiang Xue committed
303 304 305 306 307 308 309 310 311 312 313
		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()) {
314
				$optional[$name] = $this->formatOptionHelp('- ' . $this->ansiFormat($name, Console::FG_CYAN), false, $type, $param->getDefaultValue(), $comment);
Qiang Xue committed
315
			} else {
316
				$required[$name] = $this->formatOptionHelp('- ' . $this->ansiFormat($name, Console::FG_CYAN), true, $type, null, $comment);
Qiang Xue committed
317 318
			}
		}
Qiang Xue committed
319

Alexander Makarov committed
320
		return [$required, $optional];
Qiang Xue committed
321 322 323
	}

	/**
Qiang Xue committed
324 325 326
	 * 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
327
	 */
Qiang Xue committed
328
	protected function getOptionHelps($controller)
Qiang Xue committed
329
	{
Qiang Xue committed
330 331
		$optionNames = $controller->globalOptions();
		if (empty($optionNames)) {
Alexander Makarov committed
332
			return [];
Qiang Xue committed
333 334 335
		}

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

	/**
	 * Parses the comment block into tags.
	 * @param string $comment the comment block
	 * @return array the parsed tags
	 */
	protected function parseComment($comment)
	{
Alexander Makarov committed
372
		$tags = [];
Qiang Xue committed
373 374 375 376 377 378 379 380 381 382
		$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
383
					$tags[$name] = [$tags[$name], trim($matches[2])];
Qiang Xue committed
384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407
				}
			}
		}
		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);
			}
408 409 410 411
			if (is_bool($defaultValue)) {
				// show as integer to avoid confusion
				$defaultValue = (int)$defaultValue;
			}
Qiang Xue committed
412 413 414 415 416 417 418 419 420 421 422 423 424 425
			$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";
	}
426 427 428 429 430 431 432 433

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