HelpController.php 13.1 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 45
	/**
	 * Displays available commands or the detailed information
	 * about a particular command. For example,
	 *
	 * ~~~
46 47
	 * yii help          # list available commands
	 * yii help message  # display help info about "message"
Qiang Xue committed
48 49
	 * ~~~
	 *
Qiang Xue committed
50
	 * @param string $command The name of the command to show help about.
Qiang Xue committed
51
	 * If not provided, all available commands will be displayed.
Qiang Xue committed
52
	 * @return integer the exit status
Qiang Xue committed
53
	 * @throws Exception if the command for help is unknown
Qiang Xue committed
54
	 */
Qiang Xue committed
55
	public function actionIndex($command = null)
Qiang Xue committed
56
	{
Qiang Xue committed
57
		if ($command !== null) {
Qiang Xue committed
58
			$result = Yii::$app->createController($command);
Qiang Xue committed
59
			if ($result === false) {
Alexander Makarov committed
60
				throw new Exception(Yii::t('yii', 'No help for unknown command "{command}".', [
61
					'command' => $this->ansiFormat($command, Console::FG_YELLOW),
Alexander Makarov committed
62
				]));
Qiang Xue committed
63 64
			}

Qiang Xue committed
65
			list($controller, $actionID) = $result;
Qiang Xue committed
66

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

	/**
	 * Returns all available command names.
	 * @return array all available command names
	 */
	public function getCommands()
	{
Qiang Xue committed
84
		$commands = $this->getModuleCommands(Yii::$app);
Qiang Xue committed
85 86 87 88 89 90 91 92 93 94 95
		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
96
		$actions = array_keys($controller->actions());
Qiang Xue committed
97 98 99
		$class = new \ReflectionClass($controller);
		foreach ($class->getMethods() as $method) {
			$name = $method->getName();
Qiang Xue committed
100
			if ($method->isPublic() && !$method->isStatic() && strpos($name, 'action') === 0 && $name !== 'actions') {
Alexander Makarov committed
101
				$actions[] = Inflector::camel2id(substr($name, 6));
Qiang Xue committed
102 103 104 105 106 107 108 109 110 111 112 113 114
			}
		}
		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
115
		$prefix = $module instanceof Application ? '' : $module->getUniqueID() . '/';
Qiang Xue committed
116

Alexander Makarov committed
117
		$commands = [];
Qiang Xue committed
118
		foreach (array_keys($module->controllerMap) as $id) {
Qiang Xue committed
119 120 121 122 123 124 125 126 127 128 129 130 131 132
			$commands[] = $prefix . $id;
		}

		foreach ($module->getModules() as $id => $child) {
			if (($child = $module->getModule($id)) === null) {
				continue;
			}
			foreach ($this->getModuleCommands($child) as $command) {
				$commands[] = $prefix . $id . '/' . $command;
			}
		}

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

		return $commands;
	}

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

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

		$actions = $this->getActions($controller);
178
		if (!empty($actions)) {
179
			$this->stdout("\nSUB-COMMANDS\n\n", Console::BOLD);
Qiang Xue committed
180 181
			$prefix = $controller->getUniqueId();
			foreach ($actions as $action) {
182
				echo '- ' . $this->ansiFormat($prefix.'/'.$action, Console::FG_YELLOW);
Qiang Xue committed
183
				if ($action === $controller->defaultAction) {
184
					$this->stdout(' (default)', Console::FG_GREEN);
Qiang Xue committed
185
				}
Qiang Xue committed
186 187 188 189 190
				$summary = $this->getActionSummary($controller, $action);
				if ($summary !== '') {
					echo ': ' . $summary;
				}
				echo "\n";
Qiang Xue committed
191
			}
192 193 194
			echo "\nTo see the detailed information about individual sub-commands, enter:\n";
			echo "\n  yii " . $this->ansiFormat('help', Console::FG_YELLOW) . ' '
							. $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);
Qiang Xue committed
264
		if ($action->id === $controller->defaultAction) {
265
			echo 'yii ' . $this->ansiFormat($controller->getUniqueId(), Console::FG_YELLOW);
Qiang Xue committed
266
		} else {
267
			echo 'yii ' . $this->ansiFormat($action->getUniqueId(), Console::FG_YELLOW);
Qiang Xue committed
268
		}
Alexander Makarov committed
269
		list ($required, $optional) = $this->getArgHelps($method, isset($tags['param']) ? $tags['param'] : []);
270 271
		foreach ($required as $arg => $description) {
			$this->stdout(' <' . $arg . '>', Console::FG_CYAN);
Alexander Makarov committed
272
		}
273 274
		foreach ($optional as $arg => $description) {
			$this->stdout(' [' . $arg . ']', Console::FG_CYAN);
Qiang Xue committed
275
		}
276
		if (!empty($options)) {
277
			$this->stdout(' [...options...]', Console::FG_RED);
278
		}
Qiang Xue committed
279
		echo "\n\n";
Qiang Xue committed
280

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

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

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

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

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

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

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