From 4e7ac9caa27dd214edece9cde8a7856ae6f473d9 Mon Sep 17 00:00:00 2001
From: Evgeniy Zyubin <mail@devanych.ru>
Date: Thu, 28 Oct 2021 09:30:56 +0300
Subject: [PATCH] Fix #34: Add aliases and hidden commands, static name and
 description to readme (#134)

Co-authored-by: Alexander Makarov <sam@rmcreative.ru>
---
 README.md | 78 ++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 60 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index b36a40a4..f6b09fa7 100644
--- a/README.md
+++ b/README.md
@@ -6,8 +6,6 @@
     <br>
 </p>
 
-This Yii Framework package adds console into the application.
-
 [![Latest Stable Version](https://poser.pugx.org/yiisoft/yii-console/v/stable.png)](https://packagist.org/packages/yiisoft/yii-console)
 [![Total Downloads](https://poser.pugx.org/yiisoft/yii-console/downloads.png)](https://packagist.org/packages/yiisoft/yii-console)
 [![Build status](https://github.com/yiisoft/yii-console/workflows/build/badge.svg)](https://github.com/yiisoft/yii-console/actions)
@@ -17,6 +15,8 @@ This Yii Framework package adds console into the application.
 [![static analysis](https://github.com/yiisoft/yii-console/workflows/static%20analysis/badge.svg)](https://github.com/yiisoft/yii-console/actions?query=workflow%3A%22static+analysis%22)
 [![type-coverage](https://shepherd.dev/github/yiisoft/yii-console/coverage.svg)](https://shepherd.dev/github/yiisoft/yii-console)
 
+This Yii Framework package adds console into the application.
+
 ## Requirements
 
 - PHP 7.4 or higher.
@@ -43,6 +43,7 @@ declare(strict_types=1);
 
 use Psr\Container\ContainerInterface;
 use Yiisoft\Config\Config;
+use Yiisoft\Config\ConfigPaths;
 use Yiisoft\Di\Container;
 use Yiisoft\Yii\Console\Application;
 use Yiisoft\Yii\Console\Output\ConsoleBufferedOutput;
@@ -51,10 +52,7 @@ define('YII_ENV', getenv('env') ?: 'production');
 
 require_once 'vendor/autoload.php';
 
-$config = new Config(
-    __DIR__,
-    '/config/packages',
-);
+$config = new Config(new ConfigPaths(__DIR__, 'config'));
 
 $container = new Container(
     $config->get('console'),
@@ -78,26 +76,70 @@ try {
 }
 ```
 
-To start Console Application `composer.json` should contain minimal configuration for [Yiisoft\Config\Config](https://github.com/yiisoft/config) 
+To start Console Application `composer.json` should contain minimal configuration
+for [Yiisoft\Config\Config](https://github.com/yiisoft/config):
 
 ```json    
-    "extra": {
-        "config-plugin-options": {
-            "source-directory": "config",
-            "output-directory": "config/packages"
-        },
-        "config-plugin": {
-            "console": [
-                "$common",
-                "console.php"
-            ]
-        }
+"extra": {
+    "config-plugin-options": {
+        "source-directory": "config",
+    },
+    "config-plugin": {
+        "console": [
+            "$common",
+            "console.php"
+        ]
+    }
+}
+```
+
+Since `\Yiisoft\Yii\Console\CommandLoader` uses lazy loading of commands, it is necessary
+to specify the name and description in static properties when creating a command:
+
+```php
+use Symfony\Component\Console\Command\Command;
+
+final class MyCustomCommand implements Command
+{
+    protected static $defaultName = 'my/custom';
+    protected static $defaultDescription = 'Description of my custom command.';
+    
+    protected function configure(): void
+    {
+        // ...
     }
+    
+    protected function execute(InputInterface $input, OutputInterface $output): in
+    {
+        // ...
+    }
+}
 ```
 
+> When naming commands, a slash `/` should be used as a separator. For example: `user/create`, `user/delete`, etc.
+
+
 Since the package is based on [Symfony Console component](https://symfony.com/doc/current/components/console.html),
 refer to its documentation for details on how to use the binary and create your own commands.
 
+### Aliases and hidden commands
+
+To configure commands, set the names and aliases in `\Yiisoft\Yii\Console\CommandLoader` configuration.
+Names and aliases from the command class itself are always ignored.
+
+The command can be marked as hidden by prefixing its name with `|`.
+
+
+```php
+'yiisoft/yii-console' => [
+	'commands' => [
+		'hello' => Hello::class, // name: 'hello', aliases: [], hidden: false
+		'start|run|s|r' => Run::class, // name: 'start', aliases: ['run', 's', 'r'], hidden: false
+		'|hack|h' => Hack::class, // name: 'hack', aliases: ['h'], hidden: true
+	],
+],
+```
+
 ## Testing
 
 ### Unit testing