Cleanup and docs (#31)

samdark · web-flow · commit b73067f716ea · 2024-06-17T11:13:02.000+03:00
diff --git a/.env b/.env
@@ -1,2 +1,3 @@
-YII_ENV=
+# Dev environment variables for Codeception.
+YII_ENV=dev
 YII_DEBUG=true
diff --git a/.env.test b/.env.test
@@ -1,2 +1,3 @@
+# Test environment variables for Codeception.
 YII_ENV=test
 YII_DEBUG=true
diff --git a/.gitattributes b/.gitattributes
@@ -24,7 +24,6 @@
 # Ignore some meta files when creating an archive of this repository
 /.github                export-ignore
 /.gitattributes         export-ignore
-/.scrutinizer.yml       export-ignore
 /.styleci.yml           export-ignore
 /CHANGELOG.md           export-ignore
 
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -5,7 +5,6 @@ on:
       - 'README.md'
       - 'CHANGELOG.md'
       - '.gitignore'
-      - '.env.example'
       - '.gitattributes'
       - 'infection.json.dist'
       - 'psalm.xml'
@@ -16,9 +15,7 @@ on:
       - 'README.md'
       - 'CHANGELOG.md'
       - '.gitignore'
-      - '.env.example'
       - '.gitattributes'
-      - 'infection.json.dist'
       - 'psalm.xml'
 
   schedule:
diff --git a/.github/workflows/static.yml b/.github/workflows/static.yml
@@ -6,8 +6,6 @@ on:
       - 'CHANGELOG.md'
       - '.gitignore'
       - '.gitattributes'
-      - 'infection.json.dist'
-      - 'phpunit.xml.dist'
 
   push:
     paths-ignore:
@@ -16,8 +14,6 @@ on:
       - 'CHANGELOG.md'
       - '.gitignore'
       - '.gitattributes'
-      - 'infection.json.dist'
-      - 'phpunit.xml.dist'
 
 name: static analysis
 
diff --git a/.scrutinizer.yml b/.scrutinizer.yml
diff --git a/README.md b/README.md
@@ -9,12 +9,18 @@
 [![Latest Stable Version](https://poser.pugx.org/yiisoft/app-console/v/stable.png)](https://packagist.org/packages/yiisoft/app-console)
 [![Total Downloads](https://poser.pugx.org/yiisoft/app-console/downloads.png)](https://packagist.org/packages/yiisoft/app-console)
 [![Build status](https://github.com/yiisoft/app-console/workflows/build/badge.svg)](https://github.com/yiisoft/app-console/actions?query=workflow%3Abuild)
-[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/yiisoft/app-console/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/yiisoft/app-console/?branch=master)
-[![Code Coverage](https://scrutinizer-ci.com/g/yiisoft/app-console/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/yiisoft/app-console/?branch=master)
 [![static analysis](https://github.com/yiisoft/app-console/workflows/static%20analysis/badge.svg)](https://github.com/yiisoft/app-console/actions?query=workflow%3A%22static+analysis%22)
 [![type-coverage](https://shepherd.dev/github/yiisoft/app-console/coverage.svg)](https://shepherd.dev/github/yiisoft/app-console)
 
-The package is a console application that can be used to perform common tasks in a Yii application.
+The package is a **console only** application template that can be used to perform common tasks in a Yii application.
+If you need classic web or API please start with corresponding templates:
+
+- [Classic web application template](https://github.com/yiisoft/app)
+- [API application template](https://github.com/yiisoft/app-api) 
+
+It is based on [Yii console runner](https://github.com/yiisoft/yii-runner-console) that is used in the entry
+command script, `./yii`. You are free to adjust any part of this template including the entry command script
+to suit your needs.
 
 ## Requirements
 
@@ -25,33 +31,119 @@ The package is a console application that can be used to perform common tasks in
 The package could be installed with [Composer](https://getcomposer.org):
 
 ```shell
-composer create-project --stability=dev yiisoft/app-console <your project>
+composer create-project yiisoft/app-console <your project>
 ```
 
 ## General usage
 
-### Create command console
+Console is available as `./yii` from the root directory of the application:
+
+```shell
+$ ./yii
+
+Yii Console 1.0
+
+Usage:
+  command [options] [arguments]
+
+Options:
+  -h, --help            Display help for the given command. When no command is given display help for the list command
+  -q, --quiet           Do not output any message
+  -V, --version         Display this application version
+      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
+  -n, --no-interaction  Do not ask any interactive question
+      --config=CONFIG   Set alternative configuration name
+  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
+
+Available commands:
+  completion  Dump the shell completion script
+  echo        An example command that echoes exactly what it is told to.
+  help        Display help for a command
+  list        List commands
+  serve       Runs PHP built-in web server
+```
+
+Help for specific command could be displayed by adding `--help` to the command itself:
+
+```shell
+$ ./yii echo --help
+
+Description:
+  An example command that echoes exactly what it is told to.
+
+Usage:
+  echo [<sentence>]
+
+Arguments:
+  sentence              Sentence to say. [default: "Hello!"]
+
+Options:
+  -h, --help            Display help for the given command. When no command is given display help for the list command
+  -q, --quiet           Do not output any message
+  -V, --version         Display this application version
+      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
+  -n, --no-interaction  Do not ask any interactive question
+      --config=CONFIG   Set alternative configuration name
+  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
+```
+
+Using the command is like the following: 
+
+```shell
+$ ./yii echo
+You said: Hello!
+
+$ ./yii echo 'Code something'
+You said: Code something
+```
+
+## Environments
+
+Out of the box, three environments are available:
+
+- dev — for development.
+- prod — for production.
+- test — for running tests.
+
+Config files for these are in `config/environments`.
+
+Environment could be chosen by setting `YII_ENV`:
+
+```shell
+YII_ENV=prod ./yii
+```
+
+## Extra debugging
+
+To enable validation of container and events, set `YII_DEBUG` environment variable:
+
+```shell
+YII_DEBUG=1 ./yii
+```
+
+## Creating your own command
+
+Commands are placed into `src/Command`. Let's see how `hello` command is implemented in `src/Command/HelloCommand.php`:
 
 ```php
+namespace App\Command;
+
+use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputDefinition;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
 use Yiisoft\Yii\Console\ExitCode;
 
-final class Hello extends Command
+#[AsCommand(
+    name: 'echo',
+    description: 'An example command that echoes exactly what it is told to.'
+)]
+final class EchoCommand extends Command
 {
-    protected static $defaultName = 'hello';
-    protected static $defaultDescription = 'An example command';
-
     private string $sentence = 'sentence';
 
-    public function __construct()
-    {
-        parent::__construct();
-    }
-
     protected function configure(): void
     {
         $this->setDefinition(
@@ -70,50 +162,41 @@ final class Hello extends Command
 }
 ```
 
-### Using command console
+To register the command, add it to `config/commands.php`:
 
-```shell
-$ ./yii
-Yii Console 1.0
+```php
+use App\Command\EchoCommand;
 
-Usage:
-  command [options] [arguments]
+return [
+    'echo' => EchoCommand::class,
+];
+```
 
-Options:
-  -h, --help            Display help for the given command. When no command is given display help for the list command
-  -q, --quiet           Do not output any message
-  -V, --version         Display this application version
-      --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
-  -n, --no-interaction  Do not ask any interactive question
-      --config=CONFIG   Set alternative configuration name
-  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
+> Info: Yii console is based on Symfony console so for additional usage documentation, please follow
+> [Yii console](https://github.com/yiisoft/yii-console) and
+> [Symfony console guide](https://symfony.com/doc/current/console.html).
 
-Available commands:
-  completion       Dump the shell completion script
-  hello            An example command
-  help             Display help for a command
-  list             List commands
-  serve            Runs PHP built-in web server
- debug
-  debug:container  Show information about container
-  debug:events     Show information about events and listeners
-  debug:reset      Clear debug data
-```
+## Events
 
-```shell
-$ ./yii hello
-You said: Hello!
+The application raises `ApplicationStartup` before and `ApplicationShutdown` after running a command.
 
-$ ./yii hello 'Code something'
-You said: Code something
+## Tests
+
+The template comes with ready to use [Codeception](https://codeception.com/) configuration.
+In order to execute tests run:
+
+```shell
+composer run serve > ./runtime/yii.log 2>&1 &
+vendor/bin/codecept run
 ```
 
-## Documentation
+## Static analysis
 
-- [Internals](docs/internals.md)
+The code is statically analyzed with [Psalm](https://psalm.dev/). To run static analysis:
 
-If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/63) is a good place for that.
-You may also check out other [Yii Community Resources](https://www.yiiframework.com/community).
+```shell
+./vendor/bin/psalm
+```
 
 ## License
 
diff --git a/codeception.yml b/codeception.yml
@@ -20,5 +20,4 @@ coverage:
     include:
       - src/*
 params:
-  - .env
   - .env.test
diff --git a/composer.json b/composer.json
@@ -57,9 +57,6 @@
         }
     },
     "extra": {
-        "branch-alias": {
-            "dev-master": "1.0.x-dev"
-        },
         "config-plugin-file": "configuration.php"
     },
     "config": {
diff --git a/config/commands.php b/config/commands.php
@@ -2,8 +2,8 @@
 
 declare(strict_types=1);
 
-use App\Command\HelloCommand;
+use App\Command\EchoCommand;
 
 return [
-    HelloCommand::$defaultName => HelloCommand::class,
+    'echo' => EchoCommand::class,
 ];
diff --git a/config/environments/dev/params.php b/config/environments/dev/params.php
@@ -3,7 +3,4 @@
 declare(strict_types=1);
 
 return [
-    'yiisoft/yii-debug' => [
-        'enabled' => true,
-    ],
 ];
diff --git a/config/environments/prod/params.php b/config/environments/prod/params.php
@@ -3,7 +3,4 @@
 declare(strict_types=1);
 
 return [
-    'yiisoft/yii-debug' => [
-        'enabled' => false,
-    ],
 ];
diff --git a/config/environments/test/params.php b/config/environments/test/params.php
@@ -3,7 +3,4 @@
 declare(strict_types=1);
 
 return [
-    'yiisoft/yii-debug' => [
-        'enabled' => false,
-    ],
 ];
diff --git a/docs/internals.md b/docs/internals.md
diff --git a/runtime/.gitignore b/runtime/.gitignore
@@ -0,0 +1,2 @@
+*
+!.gitignore
diff --git a/src/Command/EchoCommand.php b/src/Command/EchoCommand.php
diff --git a/tests/Cli/ConsoleCest.php b/tests/Cli/ConsoleCest.php
diff --git a/tests/Unit/EchoCest.php b/tests/Unit/EchoCest.php
diff --git a/yii b/yii

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
	`1`	`+# Test environment variables for Codeception.`
`1`	`2`	`YII_ENV=test`
`2`	`3`	`YII_DEBUG=true`