HelpController.php 12.9 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;
Qiang Xue committed
15
use yii\console\Request;
16
use yii\helpers\Console;
Alexander Makarov committed
17
use yii\helpers\Inflector;
Qiang Xue committed
18

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

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

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

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

		$commands = array();
Qiang Xue committed
117
		foreach (array_keys($module->controllerMap) as $id) {
Qiang Xue committed
118 119 120 121 122 123 124 125 126 127 128 129 130 131
			$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
132
			if (strcmp(substr($file, -14), 'Controller.php') === 0) {
Qiang Xue committed
133 134 135 136 137 138 139 140 141 142
				$commands[] = $prefix . lcfirst(substr(basename($file), 0, -14));
			}
		}

		return $commands;
	}

	/**
	 * Displays all available commands.
	 */
Qiang Xue committed
143
	protected function getHelp()
Qiang Xue committed
144
	{
Qiang Xue committed
145
		$commands = $this->getCommands();
146
		if (!empty($commands)) {
147
			$this->stdout("\nThe following commands are available:\n\n", Console::BOLD);
Qiang Xue committed
148
			foreach ($commands as $command) {
149
				echo "- " . $this->ansiFormat($command, Console::FG_YELLOW) . "\n";
Qiang Xue committed
150
			}
151 152 153
			$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
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 192 193
			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
194
		}
Qiang Xue committed
195 196
	}

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

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

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

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

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

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

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

Qiang Xue committed
321
		return array($required, $optional);
Qiang Xue committed
322 323 324
	}

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

		$class = new \ReflectionClass($controller);
Qiang Xue committed
337 338 339
		$options = array();
		foreach ($class->getProperties() as $property) {
			$name = $property->getName();
Qiang Xue committed
340 341
			if (!in_array($name, $optionNames, true)) {
				continue;
Qiang Xue committed
342
			}
Qiang Xue committed
343 344 345 346 347 348
			$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
349
				}
Qiang Xue committed
350 351 352 353 354 355 356
				if (preg_match('/^([^\s]+)(.*)/s', $doc, $matches)) {
					$type = $matches[1];
					$comment = $matches[2];
				} else {
					$type = null;
					$comment = $doc;
				}
357
				$options[$name] = $this->formatOptionHelp($this->ansiFormat('--' . $name, Console::FG_RED), false, $type, $defaultValue, $comment);
Qiang Xue committed
358
			} else {
359
				$options[$name] = $this->formatOptionHelp($this->ansiFormat('--' . $name, Console::FG_RED), false, null, $defaultValue, '');
Qiang Xue committed
360 361 362 363
			}
		}
		ksort($options);
		return $options;
Alexander Makarov committed
364
	}
Qiang Xue committed
365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422

	/**
	 * Parses the comment block into tags.
	 * @param string $comment the comment block
	 * @return array the parsed tags
	 */
	protected function parseComment($comment)
	{
		$tags = array();
		$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 {
					$tags[$name] = array($tags[$name], trim($matches[2]));
				}
			}
		}
		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);
			}
			$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
423
}