Merge branch '1.10.x' into 2.0.x

Author: DavidBadura

.github/workflows/mutation-tests-diff.yml

@@ -0,0 +1,42 @@
+# https://help.github.com/en/categories/automating-your-workflow-with-github-actions
+
+name: "Mutation tests on diff"
+
+on:
+    pull_request:
+
+jobs:
+    mutation-tests-diff:
+        name: "Mutation tests on diff"
+
+        runs-on: ${{ matrix.operating-system }}
+
+        strategy:
+            matrix:
+                dependencies:
+                    - "locked"
+                php-version:
+                    - "8.4"
+                operating-system:
+                    - "ubuntu-latest"
+
+        steps:
+            - name: "Checkout"
+              uses: actions/checkout@v4
+              with:
+                  fetch-depth: 0
+
+            - name: "Install PHP"
+              uses: "shivammathur/setup-php@2.33.0"
+              with:
+                  coverage: "pcov"
+                  php-version: "${{ matrix.php-version }}"
+                  ini-values: memory_limit=-1
+                  extensions: pdo_sqlite
+
+            - uses: ramsey/composer-install@3.1.0
+              with:
+                dependency-versions: ${{ matrix.dependencies }}
+
+            - name: "Infection"
+              run: "vendor/bin/roave-infection-static-analysis-plugin --threads=max --git-diff-lines --git-diff-base=origin/$GITHUB_BASE_REF --ignore-msi-with-no-mutations --only-covered --min-msi=90 --min-covered-msi=95"

.github/workflows/mutation-tests.yml

@@ -41,6 +41,6 @@ jobs:
                 dependency-versions: ${{ matrix.dependencies }}
 
             - name: "Infection"
-              run: "vendor/bin/roave-infection-static-analysis-plugin"
+              run: "vendor/bin/roave-infection-static-analysis-plugin --threads=max"
               env:
                   STRYKER_DASHBOARD_API_KEY: ${{ secrets.STRYKER_DASHBOARD_API_KEY }}

Makefile

@@ -35,7 +35,7 @@ phpunit: vendor
 
 .PHONY: infection
 infection: vendor                                                               ## run infection
-	XDEBUG_MODE=coverage vendor/bin/infection
+	XDEBUG_MODE=coverage vendor/bin/roave-infection-static-analysis-plugin --threads=max
 
 .PHONY: static
 static: psalm phpstan phpcs-check                                               ## run static analyser

README.md

@@ -1,13 +1,21 @@
-[![Mutation testing badge](https://img.shields.io/endpoint?style=flat&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fpatchlevel%2Fhydrator%2F1.0.x)](https://dashboard.stryker-mutator.io/reports/github.com/patchlevel/hydrator/1.0.x)
+[![Mutation testing badge](https://img.shields.io/endpoint?style=flat&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fpatchlevel%2Fhydrator%2F1.10.x)](https://dashboard.stryker-mutator.io/reports/github.com/patchlevel/hydrator/1.10.x)
 [![Type Coverage](https://shepherd.dev/github/patchlevel/hydrator/coverage.svg)](https://shepherd.dev/github/patchlevel/hydrator)
 [![Latest Stable Version](https://poser.pugx.org/patchlevel/hydrator/v)](//packagist.org/packages/patchlevel/hydrator)
 [![License](https://poser.pugx.org/patchlevel/hydrator/license)](//packagist.org/packages/patchlevel/hydrator)
 
 # Hydrator
 
-With this library you can hydrate objects from array into objects and back again 
-with a focus on data processing from and into a database.
-It has now been outsourced by the [event-sourcing](https://github.com/patchlevel/event-sourcing) library as a separate library.
+This library enables seamless hydration of objects to arrays—and back again.
+It’s optimized for both developer experience (DX) and performance.
+
+The library is a core component of [patchlevel/event-sourcing](ttps://github.com/patchlevel/event-sourcing),
+where it powers the storage and retrieval of thousands of objects.
+
+Hydration is handled through normalizers, especially for complex data types.
+The system can automatically determine the appropriate normalizer based on the data type and PHPStan/Psalm annotations.
+
+In most cases, no manual configuration is needed.
+And if customization is required, it can be done easily using attributes.
 
 ## Installation
 
@@ -22,75 +30,124 @@ To use the hydrator you just have to create an instance of it.
 ```php
 use Patchlevel\Hydrator\MetadataHydrator;
 
-$hydrator = new MetadataHydrator();
+$hydrator = MetadataHydrator::create();
 ```
 
 After that you can hydrate any classes or objects. Also `final`, `readonly` classes with `property promotion`.
+These objects or classes can have complex structures in the form of value objects, DTOs or collections.
+Or all nested together. Here's an example:
 
 ```php
 final readonly class ProfileCreated 
 {
+    /**
+     * @param list<Skill> $skills
+     */
     public function __construct(
-        public string $id,
-        public string $name
+        public int $id,
+        public string $name,
+        public Role $role, // enum,
+        public array $skills, // array of objects
+        public DateTimeImmutable $createdAt,
     ) {
     }
 }
 ```
 
 ### Extract Data
 
-To convert objects into serializable arrays, you can use the `extract` method:
+To convert objects into serializable arrays, you can use the `extract` method of the hydrator.
 
 ```php
-$event = new ProfileCreated('1', 'patchlevel');
+$event = new ProfileCreated(
+    1, 
+    'patchlevel',
+    Role::Admin,
+    [new Skill('php', 10), new Skill('event-sourcing', 10)],
+    new DateTimeImmutable('2023-10-01 12:00:00'),
+);
 
 $data = $hydrator->extract($event);
 ```
 
+The result looks like this:
+
 ```php
 [
-  'id' => '1',
-  'name' => 'patchlevel'
+  'id' => 1,
+  'name' => 'patchlevel',
+  'role' => 'admin',
+  'skills' => [
+    [
+      'name' => 'php',
+      'level' => 10,
+    ],
+    [
+      'name' => 'event-sourcing',
+      'level' => 10,
+    ],
+  ],
+  'createdAt' => '2023-10-01T12:00:00+00:00',
 ]
 ```
 
+We could now convert the whole thing into JSON using `json_encode`.
+
 ### Hydrate Object
 
+The process can also be reversed. Hydrate an array back into an object. 
+To do this, we need to specify the class that should be created 
+and the data that should then be written into it.
+
 ```php
 $event = $hydrator->hydrate(
     ProfileCreated::class,
     [
-        'id' => '1',
-        'name' => 'patchlevel'
+      'id' => 1,
+      'name' => 'patchlevel',
+      'role' => 'admin',
+      'skills' => [
+        [
+          'name' => 'php',
+          'level' => 10,
+        ],
+        [
+          'name' => 'event-sourcing',
+          'level' => 10,
+        ],
+      ],
+      'createdAt' => '2023-10-01T12:00:00+00:00',
     ]
 );
 
 $oldEvent == $event // true
 ```
 
+> [!WARNING]
+> It is important to know that the constructor is not called!
+
 ### Normalizer
 
-For more complex structures, i.e. non-scalar data types, we use normalizers. 
-We have some built-in normalizers for standard structures such as objects, enums, datetime etc. 
+For more complex structures, i.e. non-scalar data types, we use normalizers.
+We have some built-in normalizers for standard structures such as objects, arrays, enums, datetime etc. 
 You can find the full list below.
 
-The normalizers can be set on each property by using the specific attribute. 
-For example, `#[DateTimeImmutableNormalizer]`. This tells the Hydrator to normalize or denormalize this property.
+The library attempts to independently determine which normalizers should be used.
+For this purpose, normalizers of this order are determined:
 
-Fortunately, we don't have to do this everywhere. 
-The library tries to independently recognize which normalizers are needed based on the data type.
-For example, if you specify DateTimeImmutable Type, the DateTimeImmutableNormalizer is automatically added.
-You can of course override this if you want. 
-This makes sense, for example, if you want to adjust the format of the normalized string. 
-You can do this by passing parameters to the normalizer.
+1) Does the class property have a normalizer as an attribute? Use this.
+2) The data type of the property is determined.
+   1) If it is a collection, use the ArrayNormalizer (recursive).
+   2) If it is an object, then look for a normalizer as attribute on the class or interfaces and use this.
+   3) If it is an object, then guess the normalizer based on the object. Fallback to the object normalizer.
+
+The normalizer is only determined once because it is cached in the metadata.
+Below you will find the list of all normalizers and how to set them manually or explicitly.
 
 #### Array
 
-If you have a list of objects that you want to normalize, then you must normalize each object individually.
-That's what the `ArrayNormalizer` does for you.
-In order to use the `ArrayNormaliser`, you still have to specify which normaliser should be applied to the individual
-objects. Internally, it basically does an `array_map` and then runs the specified normalizer on each element.
+If you have a collection (array, iterable, list) with a data type that needs to be normalized, 
+you can use the ArrayNormalizer and pass it the required normalizer.
 
 ```php
 use Patchlevel\Hydrator\Normalizer\ArrayNormalizer;
@@ -183,7 +240,6 @@ final class DTO
 #### Enum
 
 Backed enums can also be normalized.
-For this, the enum FQCN must also be pass so that the `EnumNormalizer` knows which enum it is.
 
 ```php
 use Patchlevel\Hydrator\Normalizer\EnumNormalizer;
@@ -252,14 +308,14 @@ final class Name
 
 For this we now need a custom normalizer.
 This normalizer must implement the `Normalizer` interface.
-You also need to implement a `normalize` and `denormalize` method.
-Finally, you have to allow the normalizer to be used as an attribute.
+Finally, you have to allow the normalizer to be used as an attribute,
+best to allow it for properties as well as classes.
 
 ```php
 use Patchlevel\Hydrator\Normalizer\Normalizer;
 use Patchlevel\Hydrator\Normalizer\InvalidArgument;
 
-#[Attribute(Attribute::TARGET_PROPERTY)]
+#[Attribute(Attribute::TARGET_PROPERTY | Attribute::TARGET_CLASS)]
 class NameNormalizer implements Normalizer
 {
     public function normalize(mixed $value): string
@@ -286,9 +342,6 @@ class NameNormalizer implements Normalizer
 }
 ```
 
-> [!WARNING]
-> The important thing is that the result of Normalize is serializable!
-
 Now we can also use the normalizer directly.
 
 ```php
@@ -301,40 +354,48 @@ final class DTO
 
 ### Define normalizer on class level
 
-You can also set the attribute on the value object on class level. 
-For that the normalizer needs to allow to be set on class level.
+Instead of specifying the normalizer on each property, you can also set the normalizer on the class or on an interface.
 
 ```php
-use Patchlevel\Hydrator\Normalizer\Normalizer;
-use Patchlevel\Hydrator\Normalizer\InvalidArgument;
-
-#[Attribute(Attribute::TARGET_PROPERTY | Attribute::TARGET_CLASS)]
-class NameNormalizer implements Normalizer
+#[NameNormalizer]
+final class Name
 {
     // ... same as before
 }
 ```
 
-Then set the attribute on the value object.
+### Guess normalizer
 
+It's also possible to write your own guesser that finds the correct normalizer based on the object. 
+This is useful if, for example, setting the normalizer on the class or interface isn't possible.
 
 ```php
-#[NameNormalizer]
-final class Name
+use Patchlevel\Hydrator\Guesser\Guesser;
+use Symfony\Component\TypeInfo\Type\ObjectType;
+
+class NameGuesser implements Guesser
 {
-    // ... same as before
+    public function guess(ObjectType $object): Normalizer|null
+    {
+        return match($object->getClassName()) {
+            case Name::class => new NameNormalizer(),
+            default => null,
+        };
+    }
 }
 ```
 
-After that the DTO can then look like this.
+To use this Guesser, you must specify it when creating the Hydrator:
 
 ```php
-final class DTO
-{
-    public Name $name
-}
+use Patchlevel\Hydrator\MetadataHydrator;
+
+$hydrator = MetadataHydrator::create([new NameGuesser()]);
 ```
 
+> [!NOTE]
+> The guessers are queried in order, and the first match is returned. Finally, our built-in guesser is executed.
+
 ### Normalized Name
 
 By default, the property name is used to name the field in the normalized result.
@@ -575,4 +636,4 @@ To remove personal data, you need only remove the key from the store.
 
 ```php
 $cipherKeyStore->remove('foo-id');
-```
+```

composer.json

@@ -21,21 +21,20 @@
   "require": {
     "php": "~8.2.0  || ~8.3.0 || ~8.4.0",
     "ext-openssl": "*",
-    "symfony/event-dispatcher": "^5.4.29|^6.4.0|^7.0.0",
+    "psr/cache": "^2.0.0 || ^3.0.0",
+    "psr/simple-cache": "^2.0.0 || ^3.0.0",
+    "symfony/event-dispatcher": "^5.4.29 || ^6.4.0 || ^7.0.0",
     "symfony/type-info": "^7.2.4"
   },
   "require-dev": {
     "infection/infection": "^0.29.10",
     "patchlevel/coding-standard": "^1.3.0",
-    "psr/cache": "^2.0.0|^3.0.0",
-    "psr/simple-cache": "^2.0.0|^3.0.0",
     "phpbench/phpbench": "^1.2.15",
-    "phpspec/prophecy-phpunit": "^2.1.0",
     "phpstan/phpstan": "^2.1.0",
     "phpunit/phpunit": "^11.5.17",
     "psalm/plugin-phpunit": "^0.19.2",
     "roave/infection-static-analysis-plugin": "^1.36.0",
-    "symfony/var-dumper": "^5.4.29|^6.4.0|^7.0.0",
+    "symfony/var-dumper": "^5.4.29 || ^6.4.0 || ^7.0.0",
     "vimeo/psalm": "^6.0.0"
   },
   "config": {