Added ZSH completion, moved scripts to a separate directory

contrib/completion/zsh/_yii

@@ -0,0 +1,38 @@
+#compdef yii
+
+_yii() {
+    local state command lastArgument commands options executive
+    lastArgument=${words[${#words[@]}]}
+    executive=$words[1]
+
+    # lookup for command
+    for word in ${words[@]:1}; do
+        if [[ $word != -* ]]; then
+            command=$word
+            break
+        fi
+    done
+
+
+    [[ $lastArgument == $command ]] && state="command"
+    [[ $lastArgument != $command ]] && state="option"
+
+    case $state in
+        command)
+            commands=("${(@f)$(${executive} help/list 2>/dev/null)}")
+            _describe 'command' commands
+        ;;
+        option)
+            options=("${(@f)$(${executive} help/usage ${command} 2>/dev/null)}")
+            _message -r "$options"
+
+            suboptions=("${(@f)$(${executive} help/list-action-options ${command} 2>/dev/null)}")
+            _describe -V -o -t suboption 'action options' suboptions
+        ;;
+        *)
+    esac
+
+}
+
+compdef _yii yii
+

docs/guide/tutorial-console.md

@@ -107,19 +107,49 @@ You can see an example of this in the advanced project template.
 > ```
 
 
-Bash completion <span id="bash-completion"></span>
+Console command completion <span id="console-command-completion"></span>
 ---------------
 
-Auto-completion of command arguments is a useful thing when working with the shell. Since version 2.0.11, the `./yii` command provides auto completion
-for the bash out of the box. This is provided by the `yii.bash-completion` file located in the framework base directory.
-For temporary usage you can source that file by typing:
+Auto-completion of command arguments is a useful thing when working with the shell. 
+Since version 2.0.11, the `./yii` command provides auto completion for the bash out of the box. 
 
-    source yii.bash-completion
+### Bash completion
 
-This will include the definitions given in the `yii.bash-completion` file in your current session.
-For permanent usage you can copy the file to `/etc/bash_completion.d/` on your system or add the source line above to your `.bashrc` file.
-Check the [Bash Manual](https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html) for more information.
+Make sure bash completion is installed. For most of installations it is available by default.
 
+Place the completion script in `/etc/bash_completion.d/`:
+
+     curl -L https://raw.githubusercontent.com/yiisoft/yii2/blob/master/contrib/completion/bash/yii > /etc/bash_completion.d/yii
+
+Check the [Bash Manual](https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html) for
+other ways of including completion script to your environment.
+
+### ZSH completion
+
+Put the completion script in directory for completions, using e.g. `~/.zsh/completion/`
+
+```
+mkdir -p ~/.zsh/completion
+curl -L https://raw.githubusercontent.com/yiisoft/yii2/blob/master/contrib/completion/zsh/_yii > ~/.zsh/completion/_yii
+```
+
+Include the directory in the `$fpath`, e.g. by adding it to `~/.zshrc`
+
+```
+fpath=(~/.zsh/completion $fpath)
+```
+
+Make sure `compinit` is loaded or do it by adding in `~/.zshrc`
+
+```
+autoload -Uz compinit && compinit -i
+```
+
+Then reload your shell
+
+```
+exec $SHELL -l
+```
 
 Creating your own console commands <span id="create-command"></span>
 ----------------------------------

framework/console/controllers/HelpController.php

@@ -70,7 +70,7 @@ class HelpController extends Controller
 
     /**
      * List all available controllers and actions in machine readable format.
-     * This is used for bash completion.
+     * This is used for shell completion.
      * @since 2.0.11
      */
     public function actionList()
@@ -95,6 +95,84 @@ class HelpController extends Controller
     }
 
     /**
+     * List all available options for the $action in machine readable format.
+     * This is used for shell completion.
+     *
+     * @param string $action route to action
+     * @since 2.0.11
+     */
+    public function actionListActionOptions($action)
+    {
+        $result = Yii::$app->createController($action);
+
+        if ($result === false || !($result[0] instanceof Controller)) {
+            return;
+        }
+
+        /** @var Controller $controller */
+        list($controller, $actionID) = $result;
+        $action = $controller->createAction($actionID);
+        if ($action === null) {
+            return;
+        }
+
+        $arguments = $controller->getActionArgsHelp($action);
+        foreach ($arguments as $argument => $help) {
+            $description = str_replace("\n", '', addcslashes($help['comment'], ':')) ?: $argument;
+            $this->stdout($argument . ':' . $description . "\n");
+        }
+
+        $this->stdout("\n");
+        $options = $controller->getActionOptionsHelp($action);
+        foreach ($options as $argument => $help) {
+            $description = str_replace("\n", '', addcslashes($help['comment'], ':')) ?: $argument;
+            $this->stdout('--' . $argument . ':' . $description . "\n");
+        }
+    }
+
+    /**
+     * Displays usage information for $action
+     *
+     * @param string $action route to action
+     * @since 2.0.11
+     */
+    public function actionUsage($action)
+    {
+        $result = Yii::$app->createController($action);
+
+        if ($result === false || !($result[0] instanceof Controller)) {
+            return;
+        }
+
+        /** @var Controller $controller */
+        list($controller, $actionID) = $result;
+        $action = $controller->createAction($actionID);
+        if ($action === null) {
+            return;
+        }
+
+        $scriptName = $this->getScriptName();
+        if ($action->id === $controller->defaultAction) {
+            $this->stdout($scriptName . ' ' . $this->ansiFormat($controller->getUniqueId(), Console::FG_YELLOW));
+        } else {
+            $this->stdout($scriptName . ' ' . $this->ansiFormat($action->getUniqueId(), Console::FG_YELLOW));
+        }
+
+        $args = $controller->getActionArgsHelp($action);
+        foreach ($args as $name => $arg) {
+            if ($arg['required']) {
+                $this->stdout(' <' . $name . '>', Console::FG_CYAN);
+            } else {
+                $this->stdout(' [' . $name . ']', Console::FG_CYAN);
+            }
+        }
+
+        $this->stdout("\n");
+
+        return;
+    }
+
+    /**
      * Returns all available command names.
      * @return array all available command names
      */

tests/framework/console/controllers/HelpControllerTest.php

@@ -45,7 +45,7 @@ class HelpControllerTest extends TestCase
         return $controller->flushStdOutBuffer();
     }
 
-    public function testActionIndex()
+    public function testActionList()
     {
         $this->mockApplication([
             'enableCoreCommands' => false,
@@ -64,6 +64,8 @@ cache/index
 help
 help/index
 help/list
+help/list-action-options
+help/usage
 migrate
 migrate/create
 migrate/down
@@ -78,7 +80,45 @@ STRING
         , $result);
     }
 
-    public function testActionList()
+    public function testActionListActionOptions()
+    {
+        $this->mockApplication([
+            'enableCoreCommands' => false,
+            'controllerMap' => [
+                'migrate' => 'yii\console\controllers\MigrateController',
+                'cache' => 'yii\console\controllers\CacheController',
+            ],
+        ]);
+        $result = Console::stripAnsiFormat($this->runControllerAction('list-action-options', ['action' => 'help/list-action-options']));
+        $this->assertEquals(<<<STRING
+action:route to action
+
+--interactive: whether to run the command interactively.
+--color: whether to enable ANSI color in the output.If not set, ANSI color will only be enabled for terminals that support it.
+--help: whether to display help information about current command.
+
+STRING
+        , $result);
+    }
+
+    public function testActionUsage()
+    {
+        $this->mockApplication([
+            'enableCoreCommands' => false,
+            'controllerMap' => [
+                'migrate' => 'yii\console\controllers\MigrateController',
+                'cache' => 'yii\console\controllers\CacheController',
+            ],
+        ]);
+        $result = Console::stripAnsiFormat($this->runControllerAction('usage', ['action' => 'help/list-action-options']));
+        $this->assertEquals(<<<STRING
+bootstrap.php help/list-action-options <action>
+
+STRING
+            , $result);
+    }
+
+    public function testActionIndex()
     {
         $result = Console::stripAnsiFormat($this->runControllerAction('index'));
         $this->assertContains('This is Yii version ', $result);
@@ -121,4 +161,4 @@ STRING
 class BufferedHelpController extends HelpController
 {
     use StdOutBufferControllerTrait;
-}
+}