Merge pull request #9 from picamator/development

Release 1.5.0

README.md

@@ -8,7 +8,7 @@
 Transfer Object Generator
 ==========================
 
-Would you like to build Transfer Objects (TO) easily?
+Would you like to build lightweight Transfer Objects (TO) easily?
 You're in the right place!
 
 Build TOs Using an Array as Blueprint
@@ -22,7 +22,7 @@ $data = [
 ];
 ```
 
-then facade method converts array into `YML` definition file:
+TO facade method helps to convert array into `YML` definition file:
 ```yml
 Customer:
   firstName:
@@ -31,34 +31,43 @@ Customer:
     type: string
 ```
 
-finally console command generates TO:
+Generator console command builds TO based on definition file:
 ```php
 $customerTransfer = new CustomerTransfer();
 $customerTransfer->firstName = 'Jan';
 $customerTransfer->lastName = 'Kowalski';
 ```
 
 How it works in action can be found on Wiki:
- - [Try Sample with Array](/doc/samples/try-definition-generator.php)
- - [Try Sample with YML Definition](/doc/samples/try-transfer-generator.php)
+ - [Try Sample to generate Definition files](/doc/samples/try-definition-generator.php)
+ - [Try Sample to generate TOs](/doc/samples/try-transfer-generator.php)
+ - [Try Advanced Sample to generate TOs](/doc/samples/try-advanced-transfer-generator.php)
+
+Key Features
+------------
+
+* **Interface methods:** implements `fromArray()`, `toArray()`
+* **Standard interfaces:** implements `IteratorAggregate`, `JsonSerializable`, and `Countable`
+* **Lightweight:** TO includes only data without any business logic
+* **Nullable:** supports both attribute types nullable and not nullable (`required:`)
+* **BackedEnum:** supports `BackedEnum`
+* **Adaptable:** compatible with custom Data Transfer Object (DTO) implementation
 
 Installation
 ------------
 
 Composer installation:
 
 ```shell
-$ composer require-dev picamator/transfer-object
+$ composer require picamator/transfer-object
 ```
 
 Usage
 -----
 
-Transfer Object (TO) generator can be used in two ways:
-
-### I. Via Terminal
+### Terminal
 
-Run command bellow, specifying your configuration file:
+Run command bellow to generate Transfer Objects:
 
 ```shell
 $ ./vendor/bin/generate-transfer [-c|--configuration CONFIGURATION]
@@ -68,9 +77,10 @@ Please check Wiki for more details:
 - [Command Configuration](https://github.com/picamator/transfer-object/wiki/Command-Configuration)
 - [Definition File](https://github.com/picamator/transfer-object/wiki/Definition-File)
 
-### II. Via Facade Interface
+### Facade Interface
 
-Directly call facade interfaces `TransferGeneratorFacadeInterface`, `DefinitionGeneratorFacadeInterface`.
+Facade interface `DefinitionGeneratorFacadeInterface` is used to generate `YML` definition file
+based on array.
 
 Please check Wiki for more details:
 - [Facade Interfaces](https://github.com/picamator/transfer-object/wiki/Facade-Interfaces)
@@ -79,8 +89,7 @@ Please check Wiki for more details:
 Acknowledgment
 --------------
 
-Many thanks to everyone for you contribution, supports and feedback!
-Have fun with using Transfer Object generator!
+Many thanks for your contribution, supports, feedback and simply using Transfer Object Generator!
 
 Contribution
 ------------

SECURITY.md

@@ -4,11 +4,10 @@ Security Policy
 Reporting a Vulnerability
 -------------------------
 
-When you found an security vulnerability on Transfer Object Generator,
-please report it by private message to one of project's maintainer using
-any publicly available maintainer GitHub profile.
+If you discover a security vulnerability in the Transfer Object Generator, please report it privately to one of the project's maintainers.
+You can reach them through their GitHub profiles contact data.
 
 ### Important note
 
-Please don't report security issues in publicly available way neither via GitHub issues
-nor discussions or pull requests.
+Please do not report security issues through public channels such as GitHub issues, discussions, or pull requests.
+This ensures that security vulnerabilities are addressed quicky and do not pose a risk to users.

composer.json

@@ -1,7 +1,7 @@
 {
   "name": "picamator/transfer-object",
   "description": "Transfer Object Generator based on property hooks and FixedArray.",
-  "keywords": ["generator", "code generator", "data transfer object", "dto", "dev"],
+  "keywords": ["generator", "code generator", "data transfer object", "dto"],
   "license": "MIT",
   "authors": [
     {

config/definition/transfer-generator.transfer.yml

@@ -57,6 +57,8 @@ DefinitionProperty:
   isNullable:
     type: bool
     required:
+  namespace:
+    type: string
 
 DefinitionValidator:
   isValid:

doc/samples/Advanced/CredentialsData.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Picamator\Doc\Samples\TransferObject\Advanced;
+
+use Picamator\TransferObject\Transfer\DummyTransferAdapterTrait;
+use Picamator\TransferObject\Transfer\TransferInterface;
+
+class CredentialsData implements TransferInterface
+{
+    use DummyTransferAdapterTrait;
+
+    public string $login {
+        get => $this->login;
+        set => $this->login = $value;
+    }
+
+    public string $token {
+        get => $this->token;
+        set => $this->token = $value;
+    }
+}

doc/samples/config/advanced-transfer-generator/definition/advanced-customer.transfer.yml

@@ -0,0 +1,5 @@
+AdvancedCustomer:
+  customer:
+    type: "Picamator\\Doc\\Samples\\TransferObject\\Generated\\TransferGenerator\\CustomerTransfer"
+  credentials:
+    type: "Picamator\\Doc\\Samples\\TransferObject\\Advanced\\CredentialsData"

doc/samples/config/advanced-transfer-generator/generator.config.yml

@@ -0,0 +1,4 @@
+generator:
+  transferNamespace: "Picamator\\Doc\\Samples\\TransferObject\\Generated\\AdvancedTransferGenerator"
+  transferPath: "${PROJECT_ROOT}/doc/samples/Generated/AdvancedTransferGenerator"
+  definitionPath: "${PROJECT_ROOT}/doc/samples/config/advanced-transfer-generator/definition"

doc/samples/try-advanced-transfer-generator.php

@@ -0,0 +1,110 @@
+<?php
+
+declare(strict_types=1);
+
+use Picamator\Doc\Samples\TransferObject\Advanced\CredentialsData;
+use Picamator\Doc\Samples\TransferObject\Generated\AdvancedTransferGenerator\AdvancedCustomerTransfer;
+use Picamator\Doc\Samples\TransferObject\Generated\TransferGenerator\CustomerTransfer;
+use Picamator\TransferObject\TransferGenerator\TransferGeneratorFacade;
+
+require_once __DIR__ . '/../../vendor/autoload.php';
+
+echo <<<'STORY'
+=========================================================
+       How to use custom Data Transfer Object
+                        &
+      apply Transfer Object cross modules link
+=========================================================
+
+STORY;
+
+echo <<<'STORY'
+============================================================================
+         Lets take CustomerTransfer form Generated\TransferGenerator
+============================================================================
+
+STORY;
+$customerTransfer = new CustomerTransfer();
+$customerTransfer->firstName = 'Jan';
+$customerTransfer->lastName = 'Kowalski';
+
+echo <<<'STORY'
+============================================================================
+            Lets take CredentialsData form Advanced
+                             &
+       implements TransferInterface using DummyTransferAdapterTrait
+============================================================================
+
+STORY;
+$credentialsData = new CredentialsData();
+$credentialsData->login = 'jan.kowalski';
+$credentialsData->token = 'some-random-token';
+
+$encodedCredentialsData = json_encode($credentialsData);
+
+$serializedCredentialsData = serialize($credentialsData);
+$unserializedCredentialsData = unserialize($serializedCredentialsData);
+
+$iteratedCredentialsData = implode(', ', iterator_to_array($credentialsData->getIterator()));
+
+echo <<<DEBUG
+Count: {$credentialsData->count()}
+JSON encode: $encodedCredentialsData
+Serialized: $serializedCredentialsData
+Iterated: [$iteratedCredentialsData]
+
+DEBUG;
+
+echo <<<'STORY'
+===================================================================
+           Create a Definition file combining both objects
+===================================================================
+
+AdvancedCustomer:
+  customer:
+    type: 'Picamator\\Doc\\Samples\\TransferObject\\Generated\\TransferGenerator\\CustomerTransfer'
+  credentials:
+    type: 'Picamator\\Doc\\Samples\\TransferObject\\Advanced\\CredentialsData'
+
+
+STORY;
+
+echo <<<'STORY'
+======================================================
+           Generate Transfer Objects
+======================================================
+
+STORY;
+$configPath = __DIR__ . '/config/advanced-transfer-generator/generator.config.yml';
+new TransferGeneratorFacade()->generateTransfersOrFail($configPath);
+
+echo <<<'STORY'
+======================================================
+        Try newly Generated Transfer Object
+                    &
+                  Debug
+======================================================
+
+STORY;
+
+$advancedCustomerTransfer = new AdvancedCustomerTransfer();
+$advancedCustomerTransfer->customer = $customerTransfer;
+$advancedCustomerTransfer->credentials = $credentialsData;
+
+var_dump($advancedCustomerTransfer->toArray());
+
+echo <<<'STORY'
+======================================================
+                Convert fromArray
+======================================================
+
+STORY;
+$advancedCustomerTransfer = new AdvancedCustomerTransfer()->fromArray([
+    AdvancedCustomerTransfer::CUSTOMER => [
+        CustomerTransfer::FIRST_NAME => 'Max',
+        CustomerTransfer::LAST_NAME => 'Mustermann',
+    ],
+    AdvancedCustomerTransfer::CREDENTIALS => [],
+]);
+
+var_dump($advancedCustomerTransfer->toArray());

src/Transfer/AbstractTransfer.php

@@ -9,7 +9,7 @@
 
 abstract class AbstractTransfer implements TransferInterface
 {
-    use PropertyTypeTrait;
+    use AttributeTransferTrait;
 
     protected const int META_DATA_SIZE = 0;
 

src/Transfer/PropertyTypeTrait.php → src/Transfer/AttributeTransferTrait.php

@@ -8,7 +8,7 @@
 use ReflectionAttribute;
 use ReflectionClassConstant;
 
-trait PropertyTypeTrait
+trait AttributeTransferTrait
 {
     final protected function getConstantAttribute(string $constantName): ?PropertyTypeAttributeInterface
     {