Release 5.4.0

AGENTS.md

@@ -4,8 +4,8 @@ Purpose
 This file is the project index for "agents":
 
 - the modules that generate or use PHP transfer objects
-- the IDE plugins that helps to develop the project
-- the IDE plugins that helps to integrate PHP transfer object into application
+- the IDE plugins that help to develop the project
+- the IDE plugins that help to integrate PHP transfer objects into the application
 
 It is intentionally short and only contains agent-specific facts and a concise inventory.
 Full how-to and contribution guides are in the canonical destinations:
@@ -26,9 +26,14 @@ $ composer require picamator/transfer-object
 Directory Structure
 -------------------
 
-### Endpoints
+### Console commands
 
-- `bin`: project's endpoints, include transfer object's console commands
+- `bin`: project's console commands:
+  * `transfer-generate`: generate transfer objects from configuration files
+  * `transfer-generate-bulk`: generate transfer objects by the list of configuration files
+  * `definition-generate`: generate definition files
+
+> Installing the project by composer, the console commands are available in the vendor's bin directory.
 
 ### Config
 
@@ -51,7 +56,7 @@ Directory Structure
   * each transfer object generator run will overwrite all the files in the directory
   * can be used across modules
 - `src/Generated/_tmp`: temporary directory includes newly generated transfer objects before they are finally moved to the `src/Generated`
-  * in case of an unexpected error, it is possible that directory is not deleted
+  * in case of an unexpected error, the directory might not be deleted
 - `src/Shared`: contains code shared across modules
   * can be used across modules
 - `src/Transfer`: transfer object module
@@ -74,9 +79,9 @@ Directory Structure
 Code Style
 ----------
 
-- code style should follow [PSR12](https://www.php-fig.org/psr/psr-12/)
+- code style should follow [PER Coding Style 3.0](https://www.php-fig.org/per/coding-style/)
 - each exception should implement `Picamator\TransferObject\Shared\Exception\TransferExceptionInterface`
-- exception messages should follow the same text style and structure across modules
+- exception messages should follow the same text and structure across all modules
 
 ### Classes
 
@@ -125,15 +130,95 @@ Unit and Integration Tests
 - use `PHPUnit` attributes
 - use [PHP generator](https://www.php.net/manual/en/class.generator.php) for the data providers
 
+How To Build/Start/Stop Docker Environment
+-------------------------------------------
+
+Docker Environment can be built by running the following command:
+```console
+docker/sdk build
+```
+
+Docker Environment can be started by running the following command:
+```console
+docker/sdk start
+```
+
+Docker Environment can be stopped by running the following command:
+```console
+docker/sdk stop
+```
+
+How to Generate Internal Transfer Objects
+-----------------------------------------
+
+The all project transfer objects (generator's, examples, tests) can be generated with the following command:
+```console
+docker/sdk to-generate-bulk
+```
+
+To generate only generator's transfer objects, please run the following command:
+```console
+docker/sdk to-generate
+```
+
+How to Generate Transfer Objects By Configuration File
+------------------------------------------------------
+
+Transfer Objects can be generated by configuration file path, relative from the project's root, by running the following command:
+```console
+docker/sdk to-generate [path-to-configuration-file]
+```
+
 How To Run PHPUnit Tests
 ------------------------
 
+### All Tests
+
 All tests can be run with the following command:
 ```console
 docker/sdk phpunit
 ```
 
-A Specific test group can be run with the following command:
+### Specific Group
+
+A test group can be run with the following command:
 ```console
 docker/sdk phpunit-group <group>
 ```
+
+### Specific Test Case
+
+A test case can be run with the following command:
+```console
+docker/sdk phpunit '<test-case-full-qualifided-name>'
+```
+
+For instance, the test case `Picamator\Tests\Unit\TransferObject\Command\Helper\InputNormalizerTest`
+can be run with the following command:
+```console
+docker/sdk phpunit 'Picamator\\Tests\\Unit\\TransferObject\\Command\\Helper\\InputNormalizerTest'
+```
+
+How To Run PHPStan
+------------------
+
+PHPStan can be run with the following command:
+```console
+docker/sdk phpstan
+```
+
+How To Run PHP CodeSniffer
+--------------------------
+
+PHP CodeSniffer can be run with the following command:
+```console
+docker/sdk phpcs
+```
+
+How To Run Composer
+-------------------
+
+PHPStan can be run with the following command:
+```console
+docker/sdk composer
+```