1 | <?php |
||||
2 | /** |
||||
3 | * @link http://www.yiiframework.com/ |
||||
4 | * @copyright Copyright (c) 2008 Yii Software LLC |
||||
5 | * @license http://www.yiiframework.com/license/ |
||||
6 | */ |
||||
7 | |||||
8 | namespace yii\console; |
||||
9 | |||||
10 | use Yii; |
||||
11 | use yii\base\Action; |
||||
12 | use yii\base\InlineAction; |
||||
13 | use yii\base\InvalidRouteException; |
||||
14 | use yii\helpers\Console; |
||||
15 | use yii\helpers\Inflector; |
||||
16 | |||||
17 | /** |
||||
18 | * Controller is the base class of console command classes. |
||||
19 | * |
||||
20 | * A console controller consists of one or several actions known as sub-commands. |
||||
21 | * Users call a console command by specifying the corresponding route which identifies a controller action. |
||||
22 | * The `yii` program is used when calling a console command, like the following: |
||||
23 | * |
||||
24 | * ``` |
||||
25 | * yii <route> [--param1=value1 --param2 ...] |
||||
26 | * ``` |
||||
27 | * |
||||
28 | * where `<route>` is a route to a controller action and the params will be populated as properties of a command. |
||||
29 | * See [[options()]] for details. |
||||
30 | * |
||||
31 | * @property-read string $help This property is read-only. |
||||
32 | * @property-read string $helpSummary This property is read-only. |
||||
33 | * @property-read array $passedOptionValues The properties corresponding to the passed options. This property |
||||
34 | * is read-only. |
||||
35 | * @property-read array $passedOptions The names of the options passed during execution. This property is |
||||
36 | * read-only. |
||||
37 | * @property Request $request |
||||
38 | * @property Response $response |
||||
39 | * |
||||
40 | * @author Qiang Xue <[email protected]> |
||||
41 | * @since 2.0 |
||||
42 | */ |
||||
43 | class Controller extends \yii\base\Controller |
||||
44 | { |
||||
45 | /** |
||||
46 | * @deprecated since 2.0.13. Use [[ExitCode::OK]] instead. |
||||
47 | */ |
||||
48 | const EXIT_CODE_NORMAL = 0; |
||||
49 | /** |
||||
50 | * @deprecated since 2.0.13. Use [[ExitCode::UNSPECIFIED_ERROR]] instead. |
||||
51 | */ |
||||
52 | const EXIT_CODE_ERROR = 1; |
||||
53 | |||||
54 | /** |
||||
55 | * @var bool whether to run the command interactively. |
||||
56 | */ |
||||
57 | public $interactive = true; |
||||
58 | /** |
||||
59 | * @var bool|null whether to enable ANSI color in the output. |
||||
60 | * If not set, ANSI color will only be enabled for terminals that support it. |
||||
61 | */ |
||||
62 | public $color; |
||||
63 | /** |
||||
64 | * @var bool whether to display help information about current command. |
||||
65 | * @since 2.0.10 |
||||
66 | */ |
||||
67 | public $help = false; |
||||
68 | /** |
||||
69 | * @var bool|null if true - script finish with `ExitCode::OK` in case of exception. |
||||
70 | * false - `ExitCode::UNSPECIFIED_ERROR`. |
||||
71 | * Default: `YII_ENV_TEST` |
||||
72 | * @since 2.0.36 |
||||
73 | */ |
||||
74 | public $silentExitOnException; |
||||
75 | |||||
76 | /** |
||||
77 | * @var array the options passed during execution. |
||||
78 | */ |
||||
79 | private $_passedOptions = []; |
||||
80 | |||||
81 | |||||
82 | /** |
||||
83 | * {@inheritdoc} |
||||
84 | */ |
||||
85 | 240 | public function beforeAction($action) |
|||
86 | { |
||||
87 | 240 | $silentExit = $this->silentExitOnException !== null ? $this->silentExitOnException : YII_ENV_TEST; |
|||
88 | 240 | Yii::$app->errorHandler->silentExitOnException = $silentExit; |
|||
89 | |||||
90 | 240 | return parent::beforeAction($action); |
|||
91 | } |
||||
92 | |||||
93 | /** |
||||
94 | * Returns a value indicating whether ANSI color is enabled. |
||||
95 | * |
||||
96 | * ANSI color is enabled only if [[color]] is set true or is not set |
||||
97 | * and the terminal supports ANSI color. |
||||
98 | * |
||||
99 | * @param resource $stream the stream to check. |
||||
100 | * @return bool Whether to enable ANSI style in output. |
||||
101 | */ |
||||
102 | 7 | public function isColorEnabled($stream = \STDOUT) |
|||
103 | { |
||||
104 | 7 | return $this->color === null ? Console::streamSupportsAnsiColors($stream) : $this->color; |
|||
105 | } |
||||
106 | |||||
107 | /** |
||||
108 | * Runs an action with the specified action ID and parameters. |
||||
109 | * If the action ID is empty, the method will use [[defaultAction]]. |
||||
110 | * @param string $id the ID of the action to be executed. |
||||
111 | * @param array $params the parameters (name-value pairs) to be passed to the action. |
||||
112 | * @return int the status of the action execution. 0 means normal, other values mean abnormal. |
||||
113 | * @throws InvalidRouteException if the requested action ID cannot be resolved into an action successfully. |
||||
114 | * @throws Exception if there are unknown options or missing arguments |
||||
115 | * @see createAction |
||||
116 | */ |
||||
117 | 240 | public function runAction($id, $params = []) |
|||
118 | { |
||||
119 | 240 | if (!empty($params)) { |
|||
120 | // populate options here so that they are available in beforeAction(). |
||||
121 | 228 | $options = $this->options($id === '' ? $this->defaultAction : $id); |
|||
122 | 228 | if (isset($params['_aliases'])) { |
|||
123 | 1 | $optionAliases = $this->optionAliases(); |
|||
124 | 1 | foreach ($params['_aliases'] as $name => $value) { |
|||
125 | 1 | if (array_key_exists($name, $optionAliases)) { |
|||
126 | 1 | $params[$optionAliases[$name]] = $value; |
|||
127 | } else { |
||||
128 | $message = Yii::t('yii', 'Unknown alias: -{name}', ['name' => $name]); |
||||
129 | if (!empty($optionAliases)) { |
||||
130 | $aliasesAvailable = []; |
||||
131 | foreach ($optionAliases as $alias => $option) { |
||||
132 | $aliasesAvailable[] = '-' . $alias . ' (--' . $option . ')'; |
||||
133 | } |
||||
134 | |||||
135 | $message .= '. ' . Yii::t('yii', 'Aliases available: {aliases}', [ |
||||
136 | 'aliases' => implode(', ', $aliasesAvailable) |
||||
137 | ]); |
||||
138 | } |
||||
139 | 1 | throw new Exception($message); |
|||
140 | } |
||||
141 | } |
||||
142 | 1 | unset($params['_aliases']); |
|||
143 | } |
||||
144 | 228 | foreach ($params as $name => $value) { |
|||
145 | // Allow camelCase options to be entered in kebab-case |
||||
146 | 228 | if (!in_array($name, $options, true) && strpos($name, '-') !== false) { |
|||
147 | 1 | $kebabName = $name; |
|||
148 | 1 | $altName = lcfirst(Inflector::id2camel($kebabName)); |
|||
149 | 1 | if (in_array($altName, $options, true)) { |
|||
150 | 1 | $name = $altName; |
|||
151 | } |
||||
152 | } |
||||
153 | |||||
154 | 228 | if (in_array($name, $options, true)) { |
|||
155 | 53 | $default = $this->$name; |
|||
156 | 53 | if (is_array($default) && is_string($value)) { |
|||
157 | 52 | $this->$name = preg_split('/\s*,\s*(?![^()]*\))/', $value); |
|||
158 | 12 | } elseif ($default !== null) { |
|||
159 | 11 | settype($value, gettype($default)); |
|||
160 | 11 | $this->$name = $value; |
|||
161 | } else { |
||||
162 | 2 | $this->$name = $value; |
|||
163 | } |
||||
164 | 53 | $this->_passedOptions[] = $name; |
|||
165 | 53 | unset($params[$name]); |
|||
166 | 53 | if (isset($kebabName)) { |
|||
167 | 53 | unset($params[$kebabName]); |
|||
168 | } |
||||
169 | 221 | } elseif (!is_int($name)) { |
|||
170 | $message = Yii::t('yii', 'Unknown option: --{name}', ['name' => $name]); |
||||
171 | if (!empty($options)) { |
||||
172 | $message .= '. ' . Yii::t('yii', 'Options available: {options}', ['options' => '--' . implode(', --', $options)]); |
||||
173 | } |
||||
174 | |||||
175 | 228 | throw new Exception($message); |
|||
176 | } |
||||
177 | } |
||||
178 | } |
||||
179 | 240 | if ($this->help) { |
|||
180 | 2 | $route = $this->getUniqueId() . '/' . $id; |
|||
181 | 2 | return Yii::$app->runAction('help', [$route]); |
|||
182 | } |
||||
183 | |||||
184 | 240 | return parent::runAction($id, $params); |
|||
185 | } |
||||
186 | |||||
187 | /** |
||||
188 | * Binds the parameters to the action. |
||||
189 | * This method is invoked by [[Action]] when it begins to run with the given parameters. |
||||
190 | * This method will first bind the parameters with the [[options()|options]] |
||||
191 | * available to the action. It then validates the given arguments. |
||||
192 | * @param Action $action the action to be bound with parameters |
||||
193 | * @param array $params the parameters to be bound to the action |
||||
194 | * @return array the valid parameters that the action can run with. |
||||
195 | * @throws Exception if there are unknown options or missing arguments |
||||
196 | */ |
||||
197 | 254 | public function bindActionParams($action, $params) |
|||
198 | { |
||||
199 | 254 | if ($action instanceof InlineAction) { |
|||
200 | 254 | $method = new \ReflectionMethod($this, $action->actionMethod); |
|||
201 | } else { |
||||
202 | $method = new \ReflectionMethod($action, 'run'); |
||||
203 | } |
||||
204 | |||||
205 | 254 | $args = []; |
|||
206 | 254 | $missing = []; |
|||
207 | 254 | $actionParams = []; |
|||
208 | 254 | $requestedParams = []; |
|||
209 | 254 | foreach ($method->getParameters() as $i => $param) { |
|||
210 | 247 | $name = $param->getName(); |
|||
211 | 247 | $key = null; |
|||
212 | 247 | if (array_key_exists($i, $params)) { |
|||
213 | 221 | $key = $i; |
|||
214 | 83 | } elseif (array_key_exists($name, $params)) { |
|||
215 | 7 | $key = $name; |
|||
216 | } |
||||
217 | |||||
218 | 247 | if ($key !== null) { |
|||
219 | 228 | if (PHP_VERSION_ID >= 80000) { |
|||
220 | $isArray = ($type = $param->getType()) instanceof \ReflectionNamedType && $type->getName() === 'array'; |
||||
221 | } else { |
||||
222 | 228 | $isArray = $param->isArray(); |
|||
223 | } |
||||
224 | 228 | if ($isArray) { |
|||
225 | 1 | $params[$key] = $params[$key] === '' ? [] : preg_split('/\s*,\s*/', $params[$key]); |
|||
226 | } |
||||
227 | 228 | $args[] = $actionParams[$key] = $params[$key]; |
|||
228 | 228 | unset($params[$key]); |
|||
229 | 79 | } elseif (PHP_VERSION_ID >= 70100 && ($type = $param->getType()) !== null && !$type->isBuiltin()) { |
|||
230 | try { |
||||
231 | 5 | $this->bindInjectedParams($type, $name, $args, $requestedParams); |
|||
232 | 2 | } catch (\yii\base\Exception $e) { |
|||
233 | 5 | throw new Exception($e->getMessage()); |
|||
234 | } |
||||
235 | 74 | } elseif ($param->isDefaultValueAvailable()) { |
|||
236 | 74 | $args[] = $actionParams[$i] = $param->getDefaultValue(); |
|||
237 | } else { |
||||
238 | 247 | $missing[] = $name; |
|||
239 | } |
||||
240 | } |
||||
241 | |||||
242 | 252 | if (!empty($missing)) { |
|||
243 | 1 | throw new Exception(Yii::t('yii', 'Missing required arguments: {params}', ['params' => implode(', ', $missing)])); |
|||
244 | } |
||||
245 | |||||
246 | // We use a different array here, specifically one that doesn't contain service instances but descriptions instead. |
||||
247 | 252 | if (\Yii::$app->requestedParams === null) { |
|||
248 | 252 | \Yii::$app->requestedParams = array_merge($actionParams, $requestedParams); |
|||
249 | } |
||||
250 | |||||
251 | 252 | return array_merge($args, $params); |
|||
252 | } |
||||
253 | |||||
254 | /** |
||||
255 | * Formats a string with ANSI codes. |
||||
256 | * |
||||
257 | * You may pass additional parameters using the constants defined in [[\yii\helpers\Console]]. |
||||
258 | * |
||||
259 | * Example: |
||||
260 | * |
||||
261 | * ``` |
||||
262 | * echo $this->ansiFormat('This will be red and underlined.', Console::FG_RED, Console::UNDERLINE); |
||||
263 | * ``` |
||||
264 | * |
||||
265 | * @param string $string the string to be formatted |
||||
266 | * @return string |
||||
267 | */ |
||||
268 | 7 | public function ansiFormat($string) |
|||
269 | { |
||||
270 | 7 | if ($this->isColorEnabled()) { |
|||
271 | 1 | $args = func_get_args(); |
|||
272 | 1 | array_shift($args); |
|||
273 | 1 | $string = Console::ansiFormat($string, $args); |
|||
274 | } |
||||
275 | |||||
276 | 7 | return $string; |
|||
277 | } |
||||
278 | |||||
279 | /** |
||||
280 | * Prints a string to STDOUT. |
||||
281 | * |
||||
282 | * You may optionally format the string with ANSI codes by |
||||
283 | * passing additional parameters using the constants defined in [[\yii\helpers\Console]]. |
||||
284 | * |
||||
285 | * Example: |
||||
286 | * |
||||
287 | * ``` |
||||
288 | * $this->stdout('This will be red and underlined.', Console::FG_RED, Console::UNDERLINE); |
||||
289 | * ``` |
||||
290 | * |
||||
291 | * @param string $string the string to print |
||||
292 | * @param int ...$args additional parameters to decorate the output |
||||
293 | * @return int|bool Number of bytes printed or false on error |
||||
294 | */ |
||||
295 | public function stdout($string) |
||||
296 | { |
||||
297 | if ($this->isColorEnabled()) { |
||||
298 | $args = func_get_args(); |
||||
299 | array_shift($args); |
||||
300 | $string = Console::ansiFormat($string, $args); |
||||
301 | } |
||||
302 | |||||
303 | return Console::stdout($string); |
||||
304 | } |
||||
305 | |||||
306 | /** |
||||
307 | * Prints a string to STDERR. |
||||
308 | * |
||||
309 | * You may optionally format the string with ANSI codes by |
||||
310 | * passing additional parameters using the constants defined in [[\yii\helpers\Console]]. |
||||
311 | * |
||||
312 | * Example: |
||||
313 | * |
||||
314 | * ``` |
||||
315 | * $this->stderr('This will be red and underlined.', Console::FG_RED, Console::UNDERLINE); |
||||
316 | * ``` |
||||
317 | * |
||||
318 | * @param string $string the string to print |
||||
319 | * @return int|bool Number of bytes printed or false on error |
||||
320 | */ |
||||
321 | public function stderr($string) |
||||
322 | { |
||||
323 | if ($this->isColorEnabled(\STDERR)) { |
||||
324 | $args = func_get_args(); |
||||
325 | array_shift($args); |
||||
326 | $string = Console::ansiFormat($string, $args); |
||||
327 | } |
||||
328 | |||||
329 | return fwrite(\STDERR, $string); |
||||
330 | } |
||||
331 | |||||
332 | /** |
||||
333 | * Prompts the user for input and validates it. |
||||
334 | * |
||||
335 | * @param string $text prompt string |
||||
336 | * @param array $options the options to validate the input: |
||||
337 | * |
||||
338 | * - required: whether it is required or not |
||||
339 | * - default: default value if no input is inserted by the user |
||||
340 | * - pattern: regular expression pattern to validate user input |
||||
341 | * - validator: a callable function to validate input. The function must accept two parameters: |
||||
342 | * - $input: the user input to validate |
||||
343 | * - $error: the error value passed by reference if validation failed. |
||||
344 | * |
||||
345 | * An example of how to use the prompt method with a validator function. |
||||
346 | * |
||||
347 | * ```php |
||||
348 | * $code = $this->prompt('Enter 4-Chars-Pin', ['required' => true, 'validator' => function($input, &$error) { |
||||
349 | * if (strlen($input) !== 4) { |
||||
350 | * $error = 'The Pin must be exactly 4 chars!'; |
||||
351 | * return false; |
||||
352 | * } |
||||
353 | * return true; |
||||
354 | * }]); |
||||
355 | * ``` |
||||
356 | * |
||||
357 | * @return string the user input |
||||
358 | */ |
||||
359 | public function prompt($text, $options = []) |
||||
360 | { |
||||
361 | if ($this->interactive) { |
||||
362 | return Console::prompt($text, $options); |
||||
363 | } |
||||
364 | |||||
365 | return isset($options['default']) ? $options['default'] : ''; |
||||
366 | } |
||||
367 | |||||
368 | /** |
||||
369 | * Asks user to confirm by typing y or n. |
||||
370 | * |
||||
371 | * A typical usage looks like the following: |
||||
372 | * |
||||
373 | * ```php |
||||
374 | * if ($this->confirm("Are you sure?")) { |
||||
375 | * echo "user typed yes\n"; |
||||
376 | * } else { |
||||
377 | * echo "user typed no\n"; |
||||
378 | * } |
||||
379 | * ``` |
||||
380 | * |
||||
381 | * @param string $message to echo out before waiting for user input |
||||
382 | * @param bool $default this value is returned if no selection is made. |
||||
383 | * @return bool whether user confirmed. |
||||
384 | * Will return true if [[interactive]] is false. |
||||
385 | */ |
||||
386 | 172 | public function confirm($message, $default = false) |
|||
387 | { |
||||
388 | 172 | if ($this->interactive) { |
|||
389 | return Console::confirm($message, $default); |
||||
390 | } |
||||
391 | |||||
392 | 172 | return true; |
|||
393 | } |
||||
394 | |||||
395 | /** |
||||
396 | * Gives the user an option to choose from. Giving '?' as an input will show |
||||
397 | * a list of options to choose from and their explanations. |
||||
398 | * |
||||
399 | * @param string $prompt the prompt message |
||||
400 | * @param array $options Key-value array of options to choose from |
||||
401 | * |
||||
402 | * @return string An option character the user chose |
||||
403 | */ |
||||
404 | public function select($prompt, $options = []) |
||||
405 | { |
||||
406 | return Console::select($prompt, $options); |
||||
407 | } |
||||
408 | |||||
409 | /** |
||||
410 | * Returns the names of valid options for the action (id) |
||||
411 | * An option requires the existence of a public member variable whose |
||||
412 | * name is the option name. |
||||
413 | * Child classes may override this method to specify possible options. |
||||
414 | * |
||||
415 | * Note that the values setting via options are not available |
||||
416 | * until [[beforeAction()]] is being called. |
||||
417 | * |
||||
418 | * @param string $actionID the action id of the current request |
||||
419 | * @return string[] the names of the options valid for the action |
||||
420 | */ |
||||
421 | 231 | public function options($actionID) |
|||
0 ignored issues
–
show
|
|||||
422 | { |
||||
423 | // $actionId might be used in subclasses to provide options specific to action id |
||||
424 | 231 | return ['color', 'interactive', 'help', 'silentExitOnException']; |
|||
425 | } |
||||
426 | |||||
427 | /** |
||||
428 | * Returns option alias names. |
||||
429 | * Child classes may override this method to specify alias options. |
||||
430 | * |
||||
431 | * @return array the options alias names valid for the action |
||||
432 | * where the keys is alias name for option and value is option name. |
||||
433 | * |
||||
434 | * @since 2.0.8 |
||||
435 | * @see options() |
||||
436 | */ |
||||
437 | 2 | public function optionAliases() |
|||
438 | { |
||||
439 | return [ |
||||
440 | 2 | 'h' => 'help', |
|||
441 | ]; |
||||
442 | } |
||||
443 | |||||
444 | /** |
||||
445 | * Returns properties corresponding to the options for the action id |
||||
446 | * Child classes may override this method to specify possible properties. |
||||
447 | * |
||||
448 | * @param string $actionID the action id of the current request |
||||
449 | * @return array properties corresponding to the options for the action |
||||
450 | */ |
||||
451 | 65 | public function getOptionValues($actionID) |
|||
0 ignored issues
–
show
The parameter
$actionID is not used and could be removed.
(
Ignorable by Annotation
)
If this is a false-positive, you can also ignore this issue in your code via the
This check looks for parameters that have been defined for a function or method, but which are not used in the method body.
Loading history...
|
|||||
452 | { |
||||
453 | // $actionId might be used in subclasses to provide properties specific to action id |
||||
454 | 65 | $properties = []; |
|||
455 | 65 | foreach ($this->options($this->action->id) as $property) { |
|||
456 | 65 | $properties[$property] = $this->$property; |
|||
457 | } |
||||
458 | |||||
459 | 65 | return $properties; |
|||
460 | } |
||||
461 | |||||
462 | /** |
||||
463 | * Returns the names of valid options passed during execution. |
||||
464 | * |
||||
465 | * @return array the names of the options passed during execution |
||||
466 | */ |
||||
467 | public function getPassedOptions() |
||||
468 | { |
||||
469 | return $this->_passedOptions; |
||||
470 | } |
||||
471 | |||||
472 | /** |
||||
473 | * Returns the properties corresponding to the passed options. |
||||
474 | * |
||||
475 | * @return array the properties corresponding to the passed options |
||||
476 | */ |
||||
477 | 59 | public function getPassedOptionValues() |
|||
478 | { |
||||
479 | 59 | $properties = []; |
|||
480 | 59 | foreach ($this->_passedOptions as $property) { |
|||
481 | $properties[$property] = $this->$property; |
||||
482 | } |
||||
483 | |||||
484 | 59 | return $properties; |
|||
485 | } |
||||
486 | |||||
487 | /** |
||||
488 | * Returns one-line short summary describing this controller. |
||||
489 | * |
||||
490 | * You may override this method to return customized summary. |
||||
491 | * The default implementation returns first line from the PHPDoc comment. |
||||
492 | * |
||||
493 | * @return string |
||||
494 | */ |
||||
495 | 5 | public function getHelpSummary() |
|||
496 | { |
||||
497 | 5 | return $this->parseDocCommentSummary(new \ReflectionClass($this)); |
|||
498 | } |
||||
499 | |||||
500 | /** |
||||
501 | * Returns help information for this controller. |
||||
502 | * |
||||
503 | * You may override this method to return customized help. |
||||
504 | * The default implementation returns help information retrieved from the PHPDoc comment. |
||||
505 | * @return string |
||||
506 | */ |
||||
507 | public function getHelp() |
||||
508 | { |
||||
509 | return $this->parseDocCommentDetail(new \ReflectionClass($this)); |
||||
510 | } |
||||
511 | |||||
512 | /** |
||||
513 | * Returns a one-line short summary describing the specified action. |
||||
514 | * @param Action $action action to get summary for |
||||
515 | * @return string a one-line short summary describing the specified action. |
||||
516 | */ |
||||
517 | 3 | public function getActionHelpSummary($action) |
|||
518 | { |
||||
519 | 3 | if ($action === null) { |
|||
520 | 1 | return $this->ansiFormat(Yii::t('yii', 'Action not found.'), Console::FG_RED); |
|||
521 | } |
||||
522 | |||||
523 | 2 | return $this->parseDocCommentSummary($this->getActionMethodReflection($action)); |
|||
524 | } |
||||
525 | |||||
526 | /** |
||||
527 | * Returns the detailed help information for the specified action. |
||||
528 | * @param Action $action action to get help for |
||||
529 | * @return string the detailed help information for the specified action. |
||||
530 | */ |
||||
531 | 3 | public function getActionHelp($action) |
|||
532 | { |
||||
533 | 3 | return $this->parseDocCommentDetail($this->getActionMethodReflection($action)); |
|||
534 | } |
||||
535 | |||||
536 | /** |
||||
537 | * Returns the help information for the anonymous arguments for the action. |
||||
538 | * |
||||
539 | * The returned value should be an array. The keys are the argument names, and the values are |
||||
540 | * the corresponding help information. Each value must be an array of the following structure: |
||||
541 | * |
||||
542 | * - required: boolean, whether this argument is required. |
||||
543 | * - type: string, the PHP type of this argument. |
||||
544 | * - default: string, the default value of this argument |
||||
545 | * - comment: string, the comment of this argument |
||||
546 | * |
||||
547 | * The default implementation will return the help information extracted from the doc-comment of |
||||
548 | * the parameters corresponding to the action method. |
||||
549 | * |
||||
550 | * @param Action $action |
||||
551 | * @return array the help information of the action arguments |
||||
552 | */ |
||||
553 | 6 | public function getActionArgsHelp($action) |
|||
554 | { |
||||
555 | 6 | $method = $this->getActionMethodReflection($action); |
|||
556 | 6 | $tags = $this->parseDocCommentTags($method); |
|||
557 | 6 | $params = isset($tags['param']) ? (array) $tags['param'] : []; |
|||
558 | |||||
559 | 6 | $args = []; |
|||
560 | |||||
561 | /** @var \ReflectionParameter $reflection */ |
||||
562 | 6 | foreach ($method->getParameters() as $i => $reflection) { |
|||
563 | 6 | if (PHP_VERSION_ID >= 80000) { |
|||
564 | $class = $reflection->getType(); |
||||
565 | } else { |
||||
566 | 6 | $class = $reflection->getClass(); |
|||
567 | } |
||||
568 | |||||
569 | 6 | if ($class !== null) { |
|||
570 | 1 | continue; |
|||
571 | } |
||||
572 | 6 | $name = $reflection->getName(); |
|||
573 | 6 | $tag = isset($params[$i]) ? $params[$i] : ''; |
|||
574 | 6 | if (preg_match('/^(\S+)\s+(\$\w+\s+)?(.*)/s', $tag, $matches)) { |
|||
575 | 4 | $type = $matches[1]; |
|||
576 | 4 | $comment = $matches[3]; |
|||
577 | } else { |
||||
578 | 2 | $type = null; |
|||
579 | 2 | $comment = $tag; |
|||
580 | } |
||||
581 | 6 | if ($reflection->isDefaultValueAvailable()) { |
|||
582 | 3 | $args[$name] = [ |
|||
583 | 3 | 'required' => false, |
|||
584 | 3 | 'type' => $type, |
|||
585 | 3 | 'default' => $reflection->getDefaultValue(), |
|||
586 | 3 | 'comment' => $comment, |
|||
587 | ]; |
||||
588 | } else { |
||||
589 | 4 | $args[$name] = [ |
|||
590 | 4 | 'required' => true, |
|||
591 | 4 | 'type' => $type, |
|||
592 | 'default' => null, |
||||
593 | 6 | 'comment' => $comment, |
|||
594 | ]; |
||||
595 | } |
||||
596 | } |
||||
597 | |||||
598 | 6 | return $args; |
|||
599 | } |
||||
600 | |||||
601 | /** |
||||
602 | * Returns the help information for the options for the action. |
||||
603 | * |
||||
604 | * The returned value should be an array. The keys are the option names, and the values are |
||||
605 | * the corresponding help information. Each value must be an array of the following structure: |
||||
606 | * |
||||
607 | * - type: string, the PHP type of this argument. |
||||
608 | * - default: string, the default value of this argument |
||||
609 | * - comment: string, the comment of this argument |
||||
610 | * |
||||
611 | * The default implementation will return the help information extracted from the doc-comment of |
||||
612 | * the properties corresponding to the action options. |
||||
613 | * |
||||
614 | * @param Action $action |
||||
615 | * @return array the help information of the action options |
||||
616 | */ |
||||
617 | 4 | public function getActionOptionsHelp($action) |
|||
618 | { |
||||
619 | 4 | $optionNames = $this->options($action->id); |
|||
620 | 4 | if (empty($optionNames)) { |
|||
621 | return []; |
||||
622 | } |
||||
623 | |||||
624 | 4 | $class = new \ReflectionClass($this); |
|||
625 | 4 | $options = []; |
|||
626 | 4 | foreach ($class->getProperties() as $property) { |
|||
627 | 4 | $name = $property->getName(); |
|||
628 | 4 | if (!in_array($name, $optionNames, true)) { |
|||
629 | 4 | continue; |
|||
630 | } |
||||
631 | 4 | $defaultValue = $property->getValue($this); |
|||
632 | 4 | $tags = $this->parseDocCommentTags($property); |
|||
633 | |||||
634 | // Display camelCase options in kebab-case |
||||
635 | 4 | $name = Inflector::camel2id($name, '-', true); |
|||
636 | |||||
637 | 4 | if (isset($tags['var']) || isset($tags['property'])) { |
|||
638 | 4 | $doc = isset($tags['var']) ? $tags['var'] : $tags['property']; |
|||
639 | 4 | if (is_array($doc)) { |
|||
640 | $doc = reset($doc); |
||||
641 | } |
||||
642 | 4 | if (preg_match('/^(\S+)(.*)/s', $doc, $matches)) { |
|||
643 | 4 | $type = $matches[1]; |
|||
644 | 4 | $comment = $matches[2]; |
|||
645 | } else { |
||||
646 | $type = null; |
||||
647 | $comment = $doc; |
||||
648 | } |
||||
649 | 4 | $options[$name] = [ |
|||
650 | 4 | 'type' => $type, |
|||
651 | 4 | 'default' => $defaultValue, |
|||
652 | 4 | 'comment' => $comment, |
|||
653 | ]; |
||||
654 | } else { |
||||
655 | 1 | $options[$name] = [ |
|||
656 | 1 | 'type' => null, |
|||
657 | 1 | 'default' => $defaultValue, |
|||
658 | 4 | 'comment' => '', |
|||
659 | ]; |
||||
660 | } |
||||
661 | } |
||||
662 | |||||
663 | 4 | return $options; |
|||
664 | } |
||||
665 | |||||
666 | private $_reflections = []; |
||||
667 | |||||
668 | /** |
||||
669 | * @param Action $action |
||||
670 | * @return \ReflectionMethod |
||||
671 | */ |
||||
672 | 8 | protected function getActionMethodReflection($action) |
|||
673 | { |
||||
674 | 8 | if (!isset($this->_reflections[$action->id])) { |
|||
675 | 8 | if ($action instanceof InlineAction) { |
|||
676 | 8 | $this->_reflections[$action->id] = new \ReflectionMethod($this, $action->actionMethod); |
|||
677 | } else { |
||||
678 | $this->_reflections[$action->id] = new \ReflectionMethod($action, 'run'); |
||||
679 | } |
||||
680 | } |
||||
681 | |||||
682 | 8 | return $this->_reflections[$action->id]; |
|||
683 | } |
||||
684 | |||||
685 | /** |
||||
686 | * Parses the comment block into tags. |
||||
687 | * @param \Reflector $reflection the comment block |
||||
688 | * @return array the parsed tags |
||||
689 | */ |
||||
690 | 6 | protected function parseDocCommentTags($reflection) |
|||
691 | { |
||||
692 | 6 | $comment = $reflection->getDocComment(); |
|||
693 | 6 | $comment = "@description \n" . strtr(trim(preg_replace('/^\s*\**( |\t)?/m', '', trim($comment, '/'))), "\r", ''); |
|||
694 | 6 | $parts = preg_split('/^\s*@/m', $comment, -1, PREG_SPLIT_NO_EMPTY); |
|||
695 | 6 | $tags = []; |
|||
696 | 6 | foreach ($parts as $part) { |
|||
697 | 6 | if (preg_match('/^(\w+)(.*)/ms', trim($part), $matches)) { |
|||
698 | 6 | $name = $matches[1]; |
|||
699 | 6 | if (!isset($tags[$name])) { |
|||
700 | 6 | $tags[$name] = trim($matches[2]); |
|||
701 | } elseif (is_array($tags[$name])) { |
||||
702 | $tags[$name][] = trim($matches[2]); |
||||
703 | } else { |
||||
704 | 6 | $tags[$name] = [$tags[$name], trim($matches[2])]; |
|||
705 | } |
||||
706 | } |
||||
707 | } |
||||
708 | |||||
709 | 6 | return $tags; |
|||
710 | } |
||||
711 | |||||
712 | /** |
||||
713 | * Returns the first line of docblock. |
||||
714 | * |
||||
715 | * @param \Reflector $reflection |
||||
716 | * @return string |
||||
717 | */ |
||||
718 | 5 | protected function parseDocCommentSummary($reflection) |
|||
719 | { |
||||
720 | 5 | $docLines = preg_split('~\R~u', $reflection->getDocComment()); |
|||
721 | 5 | if (isset($docLines[1])) { |
|||
722 | 5 | return trim($docLines[1], "\t *"); |
|||
723 | } |
||||
724 | |||||
725 | 2 | return ''; |
|||
726 | } |
||||
727 | |||||
728 | /** |
||||
729 | * Returns full description from the docblock. |
||||
730 | * |
||||
731 | * @param \Reflector $reflection |
||||
732 | * @return string |
||||
733 | */ |
||||
734 | 3 | protected function parseDocCommentDetail($reflection) |
|||
735 | { |
||||
736 | 3 | $comment = strtr(trim(preg_replace('/^\s*\**( |\t)?/m', '', trim($reflection->getDocComment(), '/'))), "\r", ''); |
|||
737 | 3 | if (preg_match('/^\s*@\w+/m', $comment, $matches, PREG_OFFSET_CAPTURE)) { |
|||
738 | 2 | $comment = trim(substr($comment, 0, $matches[0][1])); |
|||
739 | } |
||||
740 | 3 | if ($comment !== '') { |
|||
741 | 2 | return rtrim(Console::renderColoredString(Console::markdownToAnsi($comment))); |
|||
742 | } |
||||
743 | |||||
744 | 1 | return ''; |
|||
745 | } |
||||
746 | } |
||||
747 |
This check looks for parameters that have been defined for a function or method, but which are not used in the method body.