Merge pull request #54 from picamator/development

Release 5.4.6

Author: picamator

.aiignore

@@ -4,3 +4,6 @@
 # cache and debug
 var/cache/
 var/xdebug-profile/
+
+# secret
+.env

.github/pull_request_template.md

@@ -14,8 +14,9 @@ Type of Change
 Please delete options that are not relevant:
 
 - [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] Improvements (non-breaking changes such as refactoring, performance optimization, etc.)
 - [ ] New feature (non-breaking change which adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Breaking change (bug fix, new feature, dependency upgrade, etc.)
 - [ ] Documentation update
 - [ ] Other (please specify):
 

AGENTS.md

@@ -43,20 +43,20 @@ Directory Structure
 
 ### Examples
 
-- `examples`: samples how to use `DefinitionGeneratorFacade` and `TransferGeneratorFacade`
+- `examples`: samples on how to use `DefinitionGeneratorFacade` and `TransferGeneratorFacade`
 
 ### Source
 
 - `src`: code source
 - `src/Command`: Symfony console commands to generate definition and transfer object files
 - `src/DefinitionGenerator`: definition generator module
-- `src/Dependency`: wrapper over 3-part dependencies
+- `src/Dependency`: wrapper over third-party dependencies
 - `src/Generated`: directory where generated transfer objects are saved
   * should not contain any custom-written code
-  * each transfer object generator run will overwrite all the files in the directory
+  * each transfer object generator run overwrites 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, the directory might not be deleted
+- `src/Generated/_tmp`: temporary directory including newly generated transfer objects before they are finally moved to the `src/Generated`
+  * 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
@@ -100,20 +100,20 @@ Code Style
 
 ### Tests
 
-- tests classes should be a `final`
+- test classes should be `final`
 - tests should have at least one test group
 
 Module Structure
 ----------------
 
 #### Facade
 
-- each module should have a facade class with an interface
-- the facade class and interface name should include the module name with `Facade` suffix
-- the facade is used for communication between modules
-- the facade used factories
-- the facade should not include any business logic
-- the facade `public` methods should have specification doc-block
+- each module should have a facade class with an interface.
+- the facade class and interface name should include the module name with `Facade` suffix.
+- the facade is used for communication between modules.
+- the facade uses factories.
+- the facade should not include any business logic.
+- the facade `public` methods should have a specification doc-block.
 
 ### Factory
 
@@ -129,34 +129,42 @@ Module Structure
 Unit and Integration Tests
 --------------------------
 
-- tests should follow a similar structure to the existing ones
-- separate test implementation by comment sections: "Arrange", "Act", "Assert" (optionally with "Expect")
-- use `setUp` method to initialize the tested object's stubs and mocks
-- use `PHPUnit` attributes
-- use [PHP generator](https://www.php.net/manual/en/class.generator.php) for the data providers
+- tests should follow a similar structure to the existing ones.
+- separate test implementation by comment sections: "Arrange", "Act", "Assert" (optionally with "Expect").
+- use `setUp` method to initialize the tested object's stubs and mocks.
+- use `PHPUnit` attributes.
+- use [PHP generator](https://www.php.net/manual/en/class.generator.php) for the data providers.
+
+How To Install Project
+----------------------
+
+The project is installed by running the following command:
+```console
+docker/sdk install
+```
 
 How To Build/Start/Stop Docker Environment
 -------------------------------------------
 
-Docker Environment can be built by running the following command:
+Docker Environment is built by running the following command:
 ```console
 docker/sdk build
 ```
 
-Docker Environment can be started by running the following command:
+Docker Environment is started by running the following command:
 ```console
 docker/sdk start
 ```
 
-Docker Environment can be stopped by running the following command:
+Docker Environment is stopped by running the following command:
 ```console
 docker/sdk stop
 ```
 
 How to Run PHP Script
 ---------------------
 
-The PHP script can be run by command:
+The PHP script runs by command:
 ```console
 docker/sdk cli [path-to-script]
 ```
@@ -169,7 +177,7 @@ docker/sdk cli ./examples/try-transfer-generator.php
 How to Generate Internal Transfer Objects
 -----------------------------------------
 
-The all project transfer objects (generator's, examples, tests) can be generated with the following command:
+All project transfer objects (generator's, examples, tests) can be generated with the following command:
 ```console
 docker/sdk to-generate-bulk
 ```
@@ -182,29 +190,29 @@ 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:
+Transfer objects can be generated by a 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
+How to Run PHPUnit Tests
 ------------------------
 
-### All Tests
+### How to Run All Tests
 
 All tests can be run with the following command:
 ```console
 docker/sdk phpunit
 ```
 
-### Specific Group
+### How to Run Test Group
 
 A test group can be run with the following command:
 ```console
 docker/sdk phpunit-group <group>
 ```
 
-### Specific Test Case
+### How to Run Test Case
 
 A test case can be run with the following command:
 ```console
@@ -217,26 +225,54 @@ can be run with the following command:
 docker/sdk phpunit 'Picamator\\Tests\\Unit\\TransferObject\\Command\\Helper\\InputNormalizerTest'
 ```
 
-How To Run PHPStan
+How to Run PHPStan
 ------------------
 
-PHPStan can be run with the following command:
+For all project's files, PHPStan can be run with the following command:
 ```console
 docker/sdk phpstan
 ```
 
-How To Run PHP CodeSniffer
+For the specific file:
+```console
+docker/sdk phpstan <file-path>
+```
+
+How to Run PHP CodeSniffer
 --------------------------
 
-PHP CodeSniffer can be run with the following command:
+For all project's files, PHP CodeSniffer can be run with the following command:
 ```console
 docker/sdk phpcs
 ```
 
-How To Run Composer
+For the specific file:
+```console
+docker/sdk phpcs <file-path>
+```
+
+How to Run PHP Code Beautifier and Fixer
+----------------------------------------
+
+For all project's files, PHP Code Beautifier and Fixer can be run with the following command:
+```console
+docker/sdk phpcbf
+```
+
+For the specific file:
+```console
+docker/sdk phpcbf <file-path>
+```
+
+How to Run Composer
 -------------------
 
-PHPStan can be run with the following command:
+Composer can be run with the following command:
 ```console
 docker/sdk composer
 ```
+
+The command supports multiple arguments, for example:
+```console
+docker/sdk composer install
+```

docker/sdk

@@ -12,7 +12,7 @@ function wrap_in_yellow() {
 
 # function to print a command/option with its description
 function print_command() {
-  printf "  %-35s %s\n" "$(wrap_in_yellow "$1")" "$2"
+  printf "  %-40s %s\n" "$(wrap_in_yellow "$1")" "$2"
 }
 
 # function to print an example with its description
@@ -30,7 +30,7 @@ function show_usage() {
   echo
   echo "Options:"
   print_command "-x" "Enable Xdebug (debug, coverage)"
-  print_command "-p" "Enable Xdebug (profiler)"
+  print_command "-p" "Enable Xdebug (profile)"
   echo
   echo "Commands:"
   print_command "install" "Install development environment"
@@ -39,20 +39,20 @@ function show_usage() {
   print_command "stop" "Stop Docker containers"
   print_command "cli [script]" "Open container shell or execute PHP script"
   print_command "composer <cmd>" "Run composer command"
-  print_command "phpstan" "Run PHPStan"
+  print_command "phpstan [file]" "Run PHPStan for all project's files or for specified one"
   print_command "phpunit [filter]" "Run PHPUnit tests"
-  print_command "phpunit-group <g>" "Run PHPUnit tests by group"
-  print_command "phpcs" "Run PHP CodeSniffer"
-  print_command "phpcbf" "Run PHP Code Beautifier and Fixer"
+  print_command "phpunit-group [group]" "Run PHPUnit tests by group"
+  print_command "phpcs [file]" "Run PHP CodeSniffer for all project's files or for specified one"
+  print_command "phpcbf [file]" "Run PHP Code Beautifier and Fixer for all project's files or for specified one"
   print_command "hook-install" "Install CaptainHook"
-  print_command "hook <cmd>" "Run CaptainHook command"
-  print_command "to-generate [c]" "Generate transfer objects"
-  print_command "to-generate-bulk [b]" "Generate bulk transfer objects"
-  print_command "df-generate" "Generate definitions"
+  print_command "hook [cmd]" "Run CaptainHook command"
+  print_command "to-generate [config]" "Generate Transfer Objects from YML definitions"
+  print_command "to-generate-bulk [bulk]" "Generate Transfer Objects in bulk from a config list"
+  print_command "df-generate" "Generate definition files from JSON blueprints"
   echo
   echo "Examples:"
   print_example "$0 -x start" "Start containers (Xdebug: debug, coverage)"
-  print_example "$0 -p start" "Start containers (Xdebug: profiler)"
+  print_example "$0 -p start" "Start containers (Xdebug: profile)"
   print_example "$0 composer install" "Run composer install inside container"
 }
 
@@ -91,7 +91,7 @@ case $1 in
     if [ "$XDEBUG_MODE" == "" ]; then
       docker compose up -d --remove-orphans
     else
-      XDEBUG_MODE={$XDEBUG_MODE} docker compose up -d --remove-orphans
+      XDEBUG_MODE=${XDEBUG_MODE} docker compose up -d --remove-orphans
     fi
     ;;
   stop)
@@ -108,7 +108,7 @@ case $1 in
     $DOCKER_EXEC composer "${@:2}"
     ;;
   phpstan)
-    $DOCKER_EXEC composer phpstan
+    $DOCKER_EXEC composer phpstan "${@:2}"
     ;;
   phpunit)
     if [ -n "$2" ]; then
@@ -118,13 +118,13 @@ case $1 in
     fi
     ;;
   phpunit-group)
-    $DOCKER_EXEC composer phpunit-group "$2"
+    $DOCKER_EXEC composer phpunit-group "${@:2}"
     ;;
   phpcs)
-    $DOCKER_EXEC composer phpcs
+    $DOCKER_EXEC composer phpcs "${@:2}"
     ;;
   phpcbf)
-    $DOCKER_EXEC composer phpcbf
+    $DOCKER_EXEC composer phpcbf "${@:2}"
     ;;
   hook-install)
     $DOCKER_EXEC composer captainhook install --only-enabled --run-mode=docker --run-exec="docker exec -i $DOCKER_CONTAINER_NAME"

src/Transfer/AbstractTransfer.php

@@ -13,7 +13,10 @@
  */
 abstract class AbstractTransfer implements TransferInterface
 {
-    use AttributeTrait;
+    use AttributeTrait {
+        getInitiatorAttribute as private;
+        getTransformerAttribute as private;
+    }
 
     /**
      * @var int<0, max>
@@ -115,6 +118,10 @@ final public function toArray(): array
             $index = $metaData[$propertyName];
             $value = $this->_data[$index];
 
+            if ($value === null) {
+                continue;
+            }
+
             $data[$propertyName] = $this->getTransformerAttribute($constantName)->toArray($value);
             unset($metaData[$propertyName]);
         }

src/Transfer/Attribute/AttributeTrait.php

@@ -17,7 +17,7 @@ trait AttributeTrait
      */
     private static array $_attributeCache = [];
 
-    final protected function getInitiatorAttribute(string $constantName): InitiatorAttributeInterface
+    protected function getInitiatorAttribute(string $constantName): InitiatorAttributeInterface
     {
         /** @var \ReflectionAttribute<InitiatorAttributeInterface> $reflectionAttribute */
         $reflectionAttribute = $this->getConstantReflection(
@@ -34,7 +34,7 @@ final protected function getInitiatorAttribute(string $constantName): InitiatorA
     /**
      * @throws \Picamator\TransferObject\Transfer\Exception\AttributeTransferException
      */
-    final protected function getTransformerAttribute(string $constantName): TransformerAttributeInterface
+    protected function getTransformerAttribute(string $constantName): TransformerAttributeInterface
     {
         /** @var \ReflectionAttribute<TransformerAttributeInterface> $reflectionAttribute */
         $reflectionAttribute = $this->getConstantReflection(

src/Transfer/Attribute/Transformer/DateTimeTransformerAttribute.php

@@ -45,10 +45,10 @@ public function fromArray(mixed $data): DateTimeInterface
     }
 
     /**
-     * @param DateTimeInterface|null $data
+     * @param DateTimeInterface $data
      */
-    public function toArray(mixed $data): ?string
+    public function toArray(mixed $data): string
     {
-        return $data?->format(self::DATE_TIME_FORMAT);
+        return $data->format(self::DATE_TIME_FORMAT);
     }
 }

src/Transfer/Attribute/Transformer/EnumTransformerAttribute.php

@@ -35,11 +35,11 @@ public function fromArray(mixed $data): ?BackedEnum
     }
 
     /**
-     * @param BackedEnum|null $data
+     * @param BackedEnum $data
      */
-    public function toArray(mixed $data): string|int|null
+    public function toArray(mixed $data): string|int
     {
-        return $data?->value;
+        return $data->value;
     }
 
     /**

src/Transfer/Attribute/Transformer/NumberTransformerAttribute.php

@@ -40,10 +40,10 @@ public function fromArray(mixed $data): Number
     }
 
     /**
-     * @param \BcMath\Number|null $data
+     * @param \BcMath\Number $data
      */
-    public function toArray(mixed $data): ?string
+    public function toArray(mixed $data): string
     {
-        return $data?->__toString();
+        return $data->__toString();
     }
 }