allow vendord

vendor/cuyz/valinor/README.md

@@ -0,0 +1,129 @@
+<div align="center">
+
+![Valinor banner](docs/pages/img/valinor-banner.svg)
+
+<div>— From boring old arrays to shiny typed objects —</div>
+
+<br>
+
+[![Latest Stable Version](https://poser.pugx.org/cuyz/valinor/v)][link-packagist]
+[![PHP Version Require](https://poser.pugx.org/cuyz/valinor/require/php)][link-packagist]
+[![Total Downloads](https://poser.pugx.org/cuyz/valinor/downloads)][link-packagist]
+[![Mutation testing badge](https://img.shields.io/endpoint?style=flat&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2FCuyZ%2FValinor%2Fmaster)](https://dashboard.stryker-mutator.io/reports/github.com/CuyZ/Valinor/master)
+
+</div>
+
+---
+
+Valinor takes care of the construction and validation of raw inputs (JSON, plain
+arrays, etc.) into objects, ensuring a perfectly valid state. It allows the
+objects to be used without having to worry about their integrity during the
+whole application lifecycle.
+
+The validation system will detect any incorrect value and help the developers by
+providing precise and human-readable error messages.
+
+The mapper can handle native PHP types as well as other advanced types supported
+by [PHPStan] and [Psalm] like shaped arrays, generics, integer ranges and more.
+
+The library also provides a normalization mechanism that can help transform any
+input into a data format (JSON, CSV, …), while preserving the original 
+structure.
+
+## Installation
+
+```bash
+composer require cuyz/valinor
+```
+
+**📔 Read more on the [online documentation](https://valinor.cuyz.io)**
+
+## Example
+
+```php
+final class Country
+{
+    public function __construct(
+        /** @var non-empty-string */
+        public readonly string $name,
+        
+        /** @var list<City> */
+        public readonly array $cities,
+    ) {}
+}
+
+final class City
+{
+    public function __construct(
+        /** @var non-empty-string */
+        public readonly string $name,
+        
+        public readonly DateTimeZone $timeZone,
+    ) {}
+}
+
+$json = <<<JSON
+    {
+        "name": "France",
+        "cities": [
+            {"name": "Paris", "timeZone": "Europe/Paris"},
+            {"name": "Lyon", "timeZone": "Europe/Paris"}
+        ]
+    }
+JSON;
+
+try {
+    $country = (new \CuyZ\Valinor\MapperBuilder())
+        ->mapper()
+        ->map(Country::class, \CuyZ\Valinor\Mapper\Source\Source::json($json));
+
+    echo $country->name; // France 
+    echo $country->cities[0]->name; // Paris
+} catch (\CuyZ\Valinor\Mapper\MappingError $error) {
+    // Handle the error…
+}
+```
+
+## Documentation
+
+The full documentation is available on [valinor.cuyz.io].
+
+## Credits & thank you
+
+The development of this library is mainly motivated by the kind words and the
+help of many people. I am grateful to everyone, especially to the contributors
+of this repository who directly help to push the project forward:
+
+[![](https://contrib.rocks/image?repo=cuyz/valinor)](https://github.com/cuyz/valinor/graphs/contributors)
+
+### Powered by
+
+[![PhpStorm logo](https://resources.jetbrains.com/storage/products/company/brand/logos/PhpStorm.svg)](https://jb.gg/OpenSourceSupport)
+
+I have to give [JetBrains] credits for providing [a free PhpStorm license] for
+the development of this open-source package.
+
+### Special thanks
+
+I also want to thank
+[![blackfire-logo] Blackfire](https://www.blackfire.io/?utm_source=valinor&utm_medium=readme&utm_campaign=free-open-source)
+for providing a license of their awesome tool, leading to notable performance
+gains when using this library.
+
+[link-packagist]: https://packagist.org/packages/cuyz/valinor
+
+[contributors]: https://github.com/CuyZ/Valinor/graphs/contributors
+
+[PHPStan]: https://phpstan.org/
+
+[Psalm]: https://psalm.dev/
+
+[Jetbrains]: https://www.jetbrains.com/
+
+[a free PhpStorm license]: https://jb.gg/OpenSourceSupport
+
+[Blackfire]: https://www.blackfire.io/?utm_source=valinor&utm_medium=readme&utm_campaign=free-open-source
+
+[blackfire-logo]: docs/pages/img/blackfire-logo.svg "Blackfire logo"
+
+[valinor.cuyz.io]: https://valinor.cuyz.io