Merge pull request #340 from sergeyklay/console_improvements

Extended Console: Added ability for namespace and hidding actions

Library/Phalcon/Cli/Console/Extended.php

@@ -78,6 +78,8 @@ private function createHelp()
         $scannedTasksDir = array_diff(scandir($this->tasksDir), array('..', '.'));
 
         $config = $this->getDI()->get('config');
+        $dispatcher = $this->getDI()->getShared('dispatcher');
+        $namespace = $dispatcher->getNamespaceName();
 
         if (isset($config['annotationsAdapter']) && $config['annotationsAdapter']) {
             $adapter = '\Phalcon\Annotations\Adapter\\' . $config['annotationsAdapter'];
@@ -91,8 +93,9 @@ private function createHelp()
         }
 
         foreach ($scannedTasksDir as $taskFile) {
-            $taskClass = str_replace('.php', '', $taskFile);
+            $taskClass = ($namespace ? $namespace . '\\' : '') . str_replace('.php', '', $taskFile);
             $taskName  = strtolower(str_replace('Task', '', $taskClass));
+            $taskName  = trim($taskName, '\\');
 
             $this->documentation[$taskName] = array('description'=>array(''), 'actions'=>array());
 
@@ -119,6 +122,10 @@ private function createHelp()
             }
 
             foreach ($methodAnnotations as $action => $collection) {
+                if ($collection->has('DoNotCover')) {
+                    continue;
+                }
+
                 $actionName = strtolower(str_replace('Action', '', $action));
 
                 $this->documentation[$taskName]['actions'][$actionName]=array();
@@ -154,7 +161,7 @@ private function showHelp()
         echo $helpOutput . PHP_EOL;
         echo PHP_EOL . 'Usage:' . PHP_EOL;
         echo PHP_EOL;
-        echo '           command [<task> [<action> [<param1> <param2> ... <paramN>] ] ]'. PHP_EOL;
+        echo "\t" , 'command [<task> [<action> [<param1> <param2> ... <paramN>] ] ]', PHP_EOL;
         echo PHP_EOL;
         echo PHP_EOL . 'To show task help type:' . PHP_EOL;
         echo PHP_EOL;
@@ -186,7 +193,7 @@ private function showTaskHelp($taskTogetHelp)
         echo $helpOutput . PHP_EOL;
         echo PHP_EOL . 'Usage:' . PHP_EOL;
         echo PHP_EOL;
-        echo '           command [<task> [<action> [<param1> <param2> ... <paramN>] ] ]'. PHP_EOL;
+        echo "\t" , 'command [<task> [<action> [<param1> <param2> ... <paramN>] ] ]', PHP_EOL;
         echo PHP_EOL;
         foreach ($this->documentation as $task => $doc) {
             if ($taskTogetHelp != $task) {

Library/Phalcon/Cli/Console/README.md

@@ -1,36 +1,51 @@
-#Phalcon\CLI\Console\Extended
-Extended "Phalcon\CLI\Console\Extended" class that uses **annotations** in order to create automatically a help description.
+# Phalcon\Cli\Console\Extended
+
+Extended "Phalcon\Cli\Console\Extended" class that uses **annotations** in order to create automatically a help description.
+
+## How to use it?
 
-##How to use it?
 The parameters **-h**, **--help** or **help** could be used in order to get the help documentation automatically. For instance:
 
 **To get the tasks list and their description**
 
-> ./yourAppCommand -h
+```sh
+$ ./yourAppCommand -h
+```
 
 or
 
-> ./yourAppCommand --help
+```sh
+$ ./yourAppCommand --help
+```
 
 or
 
-> ./yourAppCommand help
+```sh
+$ ./yourAppCommand help
+```
 
 **To get the task's actions list and their description, even the parameters description**
 
-> ./yourAppCommand <task> -h
+```sh
+$ ./yourAppCommand <task> -h
+```
 
 or
 
-> ./yourAppCommand <task> --help
+```sh
+$ ./yourAppCommand <task> --help
+```
 
 or
 
-> ./yourAppCommand <task> help
+```sh
+$ ./yourAppCommand <task> help
+```
 
-##How to set it up?
+## How to set it up?
 
 Firstly you need to add some important values into the config.
+
 ```php
 $config =  new \Phalcon\Config(array(
 
@@ -45,7 +60,6 @@ $config =  new \Phalcon\Config(array(
 
     /**
     * annotationsAdapter is the choosen adapter to read annotations. 
-    * Available adapters: memory | apc
     * Adapter by default: memory
     */
     'annotationsAdapter' => 'memory',
@@ -64,6 +78,7 @@ $di->set("config",function () use ($config) {
 ```
 
 Well, it's time to create an instance of Extended Console Class to handle the calls
+
 ```php
 $console = new \Phalcon\CLI\Console\Extended();
 //Seting the above DI
@@ -92,15 +107,20 @@ try {
     exit(255);
 }
 ```
-##How to add task description?
+
+## How to add task description?
+
 The annotation tags that have been used to add tasks description are described below:
 
 | Annotation| Description|
 | :------------- |:-------------|
 | description      | Is the Task or Action description. Could be one line or multiples lines|
 | param      | Is the parameter documentation of the Action. The "param " annotation have 3 variables Name, Type and description|
 
-###Task Example
+Also is available instruction for hiding action from help. Just use `@DoNotCover` in method annotation. 
+
+### Task Example
+
 Assume that we have developed a task, to list a directory's content. So the file of the task must be located within the tasks folder. **For instance: /path/to/your/project/tasks/LsTask.php**
 
 Pay attention to the file name. This must be named as **<TaskName>Task.php**
@@ -131,15 +151,29 @@ class LsTask extends \Phalcon\CLI\Task
         $unitSize = $params[1];
         //Code to iterate a directory and show the content
     }
+
+    /**
+     * @DoNotCover
+     */
+    public function secretAction()
+    {
+        echo 'Secret list:'.PHP_EOL;
+        // ...
+    }
 }
 ```
+
 So the above example should looks like:
-> ./yourAppCommand ls --help
 
 ```
+$ ./yourAppCommand ls --help
+
 My Console App 1.0
+
 Usage:
-           command [<task> [<action> [<param1> <param2> ... <paramN>] ] ]
+        command [<task> [<action> [<param1> <param2> ... <paramN>] ] ]
+
+
 Task: ls
   List directory content
   The content will be displayed in the standard output