From 4a9b2d2b82f781237ff94ac63d24836d6b29ad15 Mon Sep 17 00:00:00 2001 From: Qiang Xue Date: Thu, 2 Jan 2014 21:06:59 -0500 Subject: [PATCH] Added support for using array-typed arguments for console commands --- docs/guide/console.md | 56 ++++++++++++++++++++++++++++++------ framework/CHANGELOG.md | 1 + framework/yii/console/Controller.php | 6 ++-- framework/yii/web/User.php | 2 +- 4 files changed, 54 insertions(+), 11 deletions(-) diff --git a/docs/guide/console.md b/docs/guide/console.md index 9bc6069..46bd7a3 100644 --- a/docs/guide/console.md +++ b/docs/guide/console.md @@ -10,10 +10,10 @@ Usage You can execute controller action using the following syntax: ``` -yii [--param1=value1 --param2 ...] +yii [--option1=value1 --option2=value2 ... argument1 argument2 ...] ``` -For example, `MigrationController::create` with `MigrationController::$migrationTable` set can be called from command +For example, `MigrationController::actionCreate()` with `MigrationController::$migrationTable` set can be called from command line like the following: ``` @@ -55,7 +55,7 @@ exit($exitCode); ``` -This script is a part of your application so you're free to adjust it. There `YII_DEBUG` can be turned off if you do +This script is a part of your application so you're free to adjust it. The `YII_DEBUG` constant can be set `false` if you do not want to see stacktrace on error and want to improve overall performance. In both basic and advanced application templates it is enabled to provide more developer-friendly environment. @@ -71,13 +71,53 @@ done in advanced application template. Creating your own console commands ---------------------------------- -### Controller +### Console Controller and Action -### Action +A console command is defined as a controller class extending from [[yii\console\Controller]]. In the controller class, +you define one or several actions that correspond to the sub-commands of the command. Within each action, you write code +to implement certain tasks for that particular sub-command. -### Parameters +When running a command, you need to specify the route to the corresponding controller action. For example, +the route `migrate/create` specifies the sub-command corresponding to the `MigrateController::actionCreate()` action method. +If a route does not contain an action ID, the default action will be executed. -### Return codes +### Options + +By overriding the [[yii\console\Controller::globalOptions()]] method, you can specify options that are available +to a console command. The method should return a list of public property names of the controller class. +When running a command, you may specify the value of an option using the syntax `--OptionName=OptionValue`. +This will assign `OptionValue` to the `OptionName` property of the controller class. + +### Arguments + +Besides options, a command can also receive arguments. The arguments will be passed as the parameters to the action +method corresponding to the requested sub-command. The first argument corresponds to the first parameter, the second +corresponds to the second, and so on. If there are not enough arguments are provided, the corresponding parameters +may take the declared default values, or if they do not have default value the command will exit with an error. + +You may use `array` type hint to indicate that an argument should be treated as an array. The array will be generated +by splitting the input string by commas. + +The follow examples show how to declare arguments: + +```php +class ExampleController extends \yii\console\Controller +{ + // The command "yii example/create test" will call "actionCreate('test')" + public function actionCreate($name) { ... } + + // The command "yii example/index city" will call "actionIndex('city', 'name')" + // The command "yii example/index city id" will call "actionIndex('city', 'id')" + public function actionIndex($category, $order = 'name') { ... } + + // The command "yii example/add test" will call "actionAdd(['test'])" + // The command "yii example/add test1,test2" will call "actionAdd(['test1', 'test2'])" + public function actionAdd(array $name) { ... } +} +``` + + +### Exit Code Using return codes is the best practice of console application development. If command returns `0` it means everything -is OK. If it is a number more than zero, we have an error and integer returned is the error code. \ No newline at end of file +is OK. If it is a number more than zero, we have an error and integer returned is the error code. diff --git a/framework/CHANGELOG.md b/framework/CHANGELOG.md index 95c2d09..3d479e3 100644 --- a/framework/CHANGELOG.md +++ b/framework/CHANGELOG.md @@ -53,6 +53,7 @@ Yii Framework 2 Change Log - Enh: Added `Widget::autoIdPrefix` to support prefixing automatically generated widget IDs (qiangxue) - Enh: Support for file aliases in console command 'message' (omnilight) - Enh: Sort and Pagination can now create absolute URLs (cebe) +- Enh: Added support for using array-typed arguments for console commands (qiangxue) - Chg #1519: `yii\web\User::loginRequired()` now returns the `Response` object instead of exiting the application (qiangxue) - Chg #1586: `QueryBuilder::buildLikeCondition()` will now escape special characters and use percentage characters by default (qiangxue) - Chg #1610: `Html::activeCheckboxList()` and `Html::activeRadioList()` will submit an empty string if no checkbox/radio is selected (qiangxue) diff --git a/framework/yii/console/Controller.php b/framework/yii/console/Controller.php index 47ac4b0..68db86c 100644 --- a/framework/yii/console/Controller.php +++ b/framework/yii/console/Controller.php @@ -111,12 +111,14 @@ class Controller extends \yii\base\Controller $missing = []; foreach ($method->getParameters() as $i => $param) { - $name = $param->getName(); + if ($param->isArray() && isset($args[$i])) { + $args[$i] = preg_split('/\s*,\s*/', $args[$i]); + } if (!isset($args[$i])) { if ($param->isDefaultValueAvailable()) { $args[$i] = $param->getDefaultValue(); } else { - $missing[] = $name; + $missing[] = $param->getName(); } } } diff --git a/framework/yii/web/User.php b/framework/yii/web/User.php index 6dda2b8..d6948b6 100644 --- a/framework/yii/web/User.php +++ b/framework/yii/web/User.php @@ -321,7 +321,7 @@ class User extends Component * calling this method. * * Note that when [[loginUrl]] is set, calling this method will NOT terminate the application execution. - * + * * @return Response the redirection response if [[loginUrl]] is set * @throws AccessDeniedHttpException the "Access Denied" HTTP exception if [[loginUrl]] is not set */