Valinor

https://github.com/cuyz/valinor
Admin
Valinor is a PHP library for constructing and validating raw inputs into typed objects, ensuring...
Tokens:282,695
Snippets:1,694
Trust Score:8
License:MIT
Update:13 hours ago
Show doc for...
Tokens:
Raw
### Install Mezzio integration with Composer

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/other/app-and-framework-integration.md

Run this command to install the official Mezzio integration package. Documentation is available at https://docs.mezzio.dev/mezzio-valinor/.

```bash
composer require mezzio/mezzio-valinor
```

--------------------------------

### Install Valinor with Composer

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/getting-started.md

Install the Valinor library via Composer.

```bash
composer require cuyz/valinor
```

--------------------------------

### Install Symfony bundle with Composer

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/other/app-and-framework-integration.md

Run this command to install the official Symfony bundle for Valinor. The bundle's documentation is available on its GitHub repository.

```bash
composer require cuyz/valinor-bundle
```

--------------------------------

### Enum type example

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/usage/type-reference.md

Shows how to use enums as types, including unions of enum cases and pattern matching for case names.

```php
enum SomeEnum
{
    case FOO;
    case BAR;
    case BAZ;
}

final readonly class SomeClass
{
    public function __construct(
        public SomeEnum $enum,

        /** @var SomeEnum::FOO|SomeEnum::BAR */
        public SomeEnum $oneOfTwoCasesOfEnum,

        /** @var SomeEnum::BA* (matches BAR or BAZ) */
        public SomeEnum $casesOfEnumMatchingPattern,
    ) {}
}
```

--------------------------------

### Class constants type example

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/usage/type-reference.md

Shows how to use class constants as types, including unions of constants and pattern matching for constant names.

```php
final readonly class SomeClassWithConstants
{
    public const FOO = 1337;
    
    public const BAR = 'bar';

    public const BAZ = 'baz';
}

final readonly class SomeClass
{
    public function __construct(
        /** @var SomeClassWithConstants::FOO|SomeClassWithConstants::BAR */
        public int|string $oneOfTwoCasesOfConstants,
        
        /** @param SomeClassWithConstants::BA* (matches `bar` or  `baz`) */
        public string $casesOfConstantsMatchingPattern,
    ) {}
}
```

--------------------------------

### Example JSON Input from External API

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/getting-started.md

Example JSON response from an external API describing a thread and its answers. The data is used as input for the mapping examples.

```json
{
    "id": 1337,
    "content": "Do you like potatoes?",
    "date": "1957-07-23 13:37:42",
    "answers": [
        {
            "user": "Ella F.",
            "message": "I like potatoes",
            "date": "1957-07-31 15:28:12"
        },
        {
            "user": "Louis A.",
            "message": "And I like tomatoes",
            "date": "1957-08-13 09:05:24"
        }
    ]
}
```

--------------------------------

### Unsealed shaped array syntax examples

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-1.12.0.md

Demonstrates the new unsealed shaped array syntax in Valinor 1.12.0. Shows how to define shaped arrays with additional values of a specified type, including key type constraints and advanced types. Includes valid and invalid examples with comments indicating success or failure.

```php
$mapper = (new \CuyZ\Valinor\MapperBuilder())->mapper();

// Default syntax can be used like this:
$mapper->map(
    'array{foo: string, ...array<string>}',
    [
        'foo' => 'foo',
        'bar' => 'bar', // ✅ valid additional value
    ]
);

$mapper->map(
    'array{foo: string, ...array<string>}',
    [
        'foo' => 'foo',
        'bar' => 1337, // ❌ invalid value 1337
    ]
);

// Key type can be added as well:
$mapper->map(
    'array{foo: string, ...array<int, string>}',
    [
        'foo' => 'foo',
        42 => 'bar', // ✅ valid additional key
    ]
);

$mapper->map(
    'array{foo: string, ...array<int, string>}',
    [
        'foo' => 'foo',
        'bar' => 'bar' // ❌ invalid key
    ]
);

// Advanced types can be used:
$mapper->map(
    "array{
        'en_US': non-empty-string,
        ...array<non-empty-string, non-empty-string>
    }",
    [
        'en_US' => 'Hello',
        'fr_FR' => 'Salut', // ✅ valid additional value
    ]
);

$mapper->map(
    "array{
        'en_US': non-empty-string,
        ...array<non-empty-string, non-empty-string>
    }",
    [
        'en_US' => 'Hello',
        'fr_FR' => '', // ❌ invalid value
    ]
);

// If the permissive type is enabled, the following will work:
(new \CuyZ\Valinor\MapperBuilder())
    ->allowPermissiveTypes()
    ->mapper()
    ->map(
        'array{foo: string, ...}',
        ['foo' => 'foo', 'bar' => 'bar', 42 => 1337]
    ); // ✅
```

--------------------------------

### Registering a DynamicConstructor

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/how-to/use-custom-object-constructors.md

This example demonstrates using the DynamicConstructor attribute to register a factory function that instantiates a class based on the provided className argument.

```php
interface InterfaceWithStaticConstructor
{
    public static function from(string $value): self;
}

final readonly class ClassWithInheritedStaticConstructor implements InterfaceWithStaticConstructor
{
    private function __construct(private SomeValueObject $value) {}

    public static function from(string $value): self
    {
        return new self(new SomeValueObject($value));
    }
}

(new \CuyZ\Valinor\MapperBuilder())
    ->registerConstructor(
        #[\CuyZ\Valinor\Mapper\Object\DynamicConstructor]
        function (string $className, string $value): InterfaceWithStaticConstructor {
            return $className::from($value);
        }
    )
    ->mapper()
    ->map(ClassWithInheritedStaticConstructor::class, 'foo');
```

--------------------------------

### Registering a global key converter

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/how-to/convert-input.md

Use registerKeyConverter to remap source keys globally. This example strips a 'billing_' prefix from input keys to match class properties.

```php
$mapper = (new \CuyZ\Valinor\MapperBuilder())
    ->registerKeyConverter(static function (string $key): string {
        // Strips the `billing_` prefix from source keys
        if (str_starts_with($key, 'billing_')) {
            return substr($key, 8);
        }

        return $key;
    })
    ->mapper();

final readonly class BillingAddress
{
    public function __construct(
        public string $street,
        public string $city,
        public string $country,
    ) {}
}

$source = [
    'billing_street' => '221B Baker Street',
    'billing_city' => 'London',
    'billing_country' => 'UK',
];

// Works with classes
$mapper->map(BillingAddress::class, $source);

// Also works with shaped arrays
$mapper->map('array{street: string, city: string, country: string}', $source);
```

--------------------------------

### Union type example

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/usage/type-reference.md

Shows how to define a class with various union types, including simple unions, class-string unions, arrays of unions, literal types, and unions of literal values.

```php
final readonly class SomeClass
{
    public function __construct(
        public int|string $simpleUnion,
        
        /** @var class-string<SomeInterface|AnotherInterface> */
        public string $unionOfClassString,
        
        /** @var array<SomeInterface|AnotherInterface> */
        public array $unionInsideArray,
        
        /** @var int|true */
        public int|bool $unionWithLiteralTrueType,
        
        /** @var int|false */
        public int|bool $unionWithLiteralFalseType,
        
        /** @var 404.42|1337.42 */
        public float $unionOfFloatValues,
        
        /** @var 42|1337 */
        public int $unionOfIntegerValues,
        
        /** @var 'foo'|'bar' */
        public string $unionOfStringValues,
    ) {}
}
```

--------------------------------

### Example for class constants

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-0.15.0.md

Defines a class with constants and uses the wildcard type 'SomeClassWithConstants::BA*' to map values that match the prefix 'BA'. The mapper returns an error for values that do not match.

```php
final class SomeClassWithConstants
{
    public const FOO = 1337;

    public const BAR = 'bar';

    public const BAZ = 'baz';
}

$mapper = (new MapperBuilder())->mapper();

$mapper->map('SomeClassWithConstants::BA*', 1337); // error
$mapper->map('SomeClassWithConstants::BA*', 'bar'); // ok
$mapper->map('SomeClassWithConstants::BA*', 'baz'); // ok
```

--------------------------------

### Mapping to an array of classes with static analysis errors

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/other/static-analysis.md

Example of mapping to an array of SomeClass instances. The static analysis tools will report errors for invalid operations on properties and undefined properties.

```php
final readonly class SomeClass
{
    public function __construct(
        public string $foo,
        public int $bar,
    ) {}
}

$objects = (new \CuyZ\Valinor\MapperBuilder())
    ->mapper()
    ->map(
        'array<' . SomeClass::class . '>',
        [/* … */]
    );

foreach ($objects as $object) {
    // ✅
    echo $object->foo;

    // ✅
    echo $object->bar * 2;

    // ❌ Cannot perform operation between `string` and `int`
    echo $object->foo * $object->bar;

    // ❌ Property `SomeClass::$fiz` is not defined
    echo $object->fiz;
}
```

--------------------------------

### Union of objects inference examples

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-0.4.0.md

Shows how Valinor infers the correct object type when mapping to a union of objects. The class definitions are provided, followed by two mapping calls that demonstrate the inference based on the provided source keys.

```php
final class UnionOfObjects
{
    public readonly SomeFooObject|SomeBarObject $object;
}

final class SomeFooObject
{
    public readonly string $foo;
}

final class SomeBarObject
{
    public readonly string $bar;
}

// Will map to an instance of `SomeFooObject`
(new \CuyZ\Valinor\MapperBuilder())
    ->mapper()
    ->map(UnionOfObjects::class, ['foo' => 'foo']);

// Will map to an instance of `SomeBarObject`
(new \CuyZ\Valinor\MapperBuilder())
    ->mapper()
    ->map(UnionOfObjects::class, ['bar' => 'bar']);
```

--------------------------------

### Example for enum

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-0.15.0.md

Defines an enum and uses the wildcard type 'SomeEnum::BA*' to map values that match the prefix 'BA', demonstrating the same wildcard feature for enums.

```php
enum SomeEnum: string
{
    case FOO = 'foo';
    case BAR = 'bar';
    case BAZ = 'baz';
}

$mapper = (new MapperBuilder())->mapper();

$mapper->map('SomeEnum::BA*', 'foo'); // error
$mapper->map('SomeEnum::BA*', 'bar'); // ok
$mapper->map('SomeEnum::BA*', 'baz'); // ok
```

--------------------------------

### Converter registration example that triggers the bug

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-2.2.1.md

Registers a converter that returns null for short strings. Before the fix, this converter was incorrectly called when mapping to 'string', causing an error.

```php
 (new \CuyZ\Valinor\MapperBuilder())
    ->registerConverter(
        // If the string length is lower than 5, we return `null`
        fn (string $val): ?string => strlen($val) < 5 ? null : $val
    )
    ->mapper()
    ->map('string', 'foo');
```

--------------------------------

### Mapping object with one property: before and after

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-1.0.0.md

When a class has a single property, the source must match that property's type directly, not an array with a key. The first example shows the old (incorrect) way; the second shows the correct way.

```php
final class Identifier
{
    public readonly string $value;
}

final class SomeClass
{
    public readonly Identifier $identifier;

    public readonly string $description;
}

(new \CuyZ\Valinor\MapperBuilder())->mapper()->map(SomeClass::class, [
    'identifier' => ['value' => 'some-identifier'], // ❌
    'description' => 'Lorem ipsum…',
]);

(new \CuyZ\Valinor\MapperBuilder())->mapper()->map(SomeClass::class, [
    'identifier' => 'some-identifier', // ✅
    'description' => 'Lorem ipsum…',
]);
```

--------------------------------

### Implementing a Property Value Transformer with AsTransformer

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/serialization/extending-normalizer.md

Create a custom attribute by implementing a normalize method and registering it with the AsTransformer attribute. This example demonstrates transforming string values to uppercase.

```php
namespace My\App;

#[\CuyZ\Valinor\Normalizer\AsTransformer]
#[\Attribute(\Attribute::TARGET_PROPERTY)]
final class Uppercase
{
    public function normalize(string $value, callable $next): string
    {
        return strtoupper($next());
    }
}

final readonly class City
{
    public function __construct(
        public string $zipCode,
        #[\My\App\Uppercase]
        public string $name,
        #[\My\App\Uppercase]
        public string $country,
    ) {}
}

(new \CuyZ\Valinor\NormalizerBuilder())
    ->normalizer(\CuyZ\Valinor\Normalizer\Format::array())
    ->normalize(
        new \My\App\City(
            zipCode: 'NW1 6XE',
            name: 'London',
            country: 'United Kingdom',
        ) 
    );

// [
//     'zipCode' => 'NW1 6XE',
//     'name' => 'LONDON',
//     'country' => 'UNITED KINGDOM',
// ]
```

--------------------------------

### Global key case normalization with NormalizeKeysToSnakeCase

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-2.5.0.md

Configures the normalizer globally to convert all object keys to snake_case. The example shows the output as an array with 'first_name' key.

```php
use CuyZ\Valinor\Normalizer\Configurator\NormalizeKeysToSnakeCase;
use CuyZ\Valinor\Normalizer\Format;
use CuyZ\Valinor\NormalizerBuilder;

$userAsArray = (new NormalizerBuilder())
    ->configureWith(new NormalizeKeysToSnakeCase())
    ->normalizer(Format::array())
    ->normalize($user);

// ['first_name' => 'John']
```

--------------------------------

### Mapping arguments of a callable with static analysis

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/other/static-analysis.md

Example of using argumentsMapper to map arguments for a callable. The static analysis tools will verify the arguments have the correct shape.

```php
$someFunction = function(string $foo, int $bar): string {
    return "$foo / $bar";
};

$arguments = (new \CuyZ\Valinor\MapperBuilder())
    ->argumentsMapper()
    ->mapArguments($someFunction, [
        'foo' => 'some value',
        'bar' => 42,
    ]);

// ✅ Arguments have a correct shape, no error reported
echo $someFunction(...$arguments);
```

--------------------------------

### Registering a custom constructor with registerConstructor

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/how-to/use-custom-object-constructors.md

This example demonstrates using registerConstructor to define a named constructor and an anonymous function for a Color class. Note that registering a constructor disables the native one, so it must be explicitly re-registered if needed.

```php
(new \CuyZ\Valinor\MapperBuilder())
    ->registerConstructor(
        // When another constructor is registered for the class, the native
        // constructor is disabled. To enable it again, it is mandatory to
        // explicitly register it again by giving the class name to this method.
        Color::class,

        // Register a named constructor
        Color::fromHex(...),

        /**
         * An anonymous function can also be used, for instance when the desired
         * object is an external dependency that cannot be modified.
         * 
         * @param 'red'|'green'|'blue' $color
         * @param 'dark'|'light' $darkness
         */
        function (string $color, string $darkness): Color {
            $main = $darkness === 'dark' ? 128 : 255;
            $other = $darkness === 'dark' ? 0 : 128;
 
            return new Color(
                $color === 'red' ? $main : $other,
                $color === 'green' ? $main : $other,
                $color === 'blue' ? $main : $other,
            );
        }
    )
    ->mapper()
    ->map(Color::class, [/* … */]);

final readonly class Color
{
    /**
     * @param int<0, 255> $red
     * @param int<0, 255> $green
     * @param int<0, 255> $blue
     */
    public function __construct(
        public int $red,
        public int $green,
        public int $blue
    ) {}

    /**
     * @param non-empty-string $hex
     */
    public static function fromHex(string $hex): self
    {
        if (strlen($hex) !== 6) {
            throw new DomainException('Must be 6 characters long');
        }

        /** @var int<0, 255> $red */
        $red = hexdec(substr($hex, 0, 2));
        /** @var int<0, 255> $green */
        $green = hexdec(substr($hex, 2, 2));
        /** @var int<0, 255> $blue */
        $blue = hexdec(substr($hex, 4, 2));

        return new self($red, $green, $blue);
    }
}
```

--------------------------------

### Advanced array-key handling: supported key types

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-1.6.0.md

Seven examples demonstrating that any string or integer can now be used as an array key in mapped types. Each line maps an array type with a specific key type (literal, positive-int, negative-int, int range, non-empty-string, class-string) to a corresponding value.

```php
$mapper->map("array<'foo'|'bar', string>", ['foo' => 'foo']);
```

```php
$mapper->map('array<42|1337, string>', [42 => 'foo']);
```

```php
$mapper->map('array<positive-int, string>', [42 => 'foo']);
```

```php
$mapper->map('array<negative-int, string>', [-42 => 'foo']);
```

```php
$mapper->map('array<int<-42, 1337>, string>', [42 => 'foo']);
```

```php
$mapper->map('array<non-empty-string, string>', ['foo' => 'foo']);
```

```php
$mapper->map('array<class-string, string>', ['SomeClass' => 'foo']);
```

--------------------------------

### Use JSON_PRETTY_PRINT with JSON normalizer

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-1.14.0.md

Shows how to use the JSON normalizer with the JSON_PRETTY_PRINT option to format the output with whitespace and line breaks. The example includes an input array and the resulting pretty-printed JSON output.

```php
$input = [
    'value' => 'foo',
    'list' => [
        'foo',
        42,
        ['sub']
    ],
    'associative' => [
        'value' => 'foo',
        'sub' => [
            'string' => 'foo',
            'integer' => 42,
        ],
    ],
];

(new \CuyZ\Valinor\MapperBuilder())
    ->normalizer(\CuyZ\Valinor\Normalizer\Format::json())
    ->withOptions(\JSON_PRETTY_PRINT)
    ->normalize($input);

// Result:
// {
//     "value": "foo",
//     "list": [
//         "foo",
//         42,
//         [
//             "sub"
//         ]
//     ],
//     "associative": {
//         "value": "foo",
//         "sub": {
//             "string": "foo",
//             "integer": 42
//         }
//     }
// }
```

--------------------------------

### Force array as object with JSON_FORCE_OBJECT

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-1.14.0.md

Shows how to use the JSON_FORCE_OBJECT option with the JSON normalizer to force an array to be output as an object. The example normalizes an array and shows the resulting JSON object output.

```php
(new \CuyZ\Valinor\MapperBuilder())
    ->normalizer(Format::json())
    ->withOptions(JSON_FORCE_OBJECT)
    ->normalize(['foo', 'bar']);

// {"0":"foo","1":"bar"}
```

--------------------------------

### Mapping HttpRequest to an object with FromRoute and FromBody attributes

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/how-to/map-http-request.md

Defines a PostComment class with constructor parameters annotated with FromRoute and FromBody attributes, then maps an HttpRequest instance to it. The example shows how route parameters and body values are extracted and assigned to the object's properties.

```php
use CuyZ\Valinor\Mapper\Http\FromBody;
use CuyZ\Valinor\Mapper\Http\FromRoute;
use CuyZ\Valinor\Mapper\Http\HttpRequest;
use CuyZ\Valinor\MapperBuilder;

final readonly class PostComment
{
    public function __construct(
        /** @var positive-int */
        #[FromRoute] public int $postId,
        /** @var non-empty-string */
        #[FromBody] public string $author,
        /** @var non-empty-string */
        #[FromBody] public string $content,
    ) {}
}

$request = new HttpRequest(
    routeParameters: ['postId' => 1337],
    bodyValues: [
        'author' => 'jane.doe@example.com',
        'content' => 'Great article, thanks for sharing!',
    ],
);

$comment = (new MapperBuilder())
    ->mapper()
    ->map(PostComment::class, $request);

// $comment->postId  === 1337
// $comment->author  === 'jane.doe@example.com'
// $comment->content === 'Great article, thanks for sharing!'
```

--------------------------------

### Object constructors with type inference

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-1.13.0.md

This example shows a class with two constructors that have the same parameter name but different types. The improved type inference allows the mapper to correctly choose the constructor based on the input type, mapping both an integer and a string with a currency symbol.

```php
final readonly class Money
{
    private function __construct(
        public int $value,
    ) {}

    #[\CuyZ\Valinor\Mapper\Object\Constructor]
    public static function fromInt(int $value): self
    {
        return new self($value);
    }

    #[\CuyZ\Valinor\Mapper\Object\Constructor]
    public static function fromString(string $value): self
    {
        if (! preg_match('/^\d+€$/', $value)) {
            throw new \InvalidArgumentException('Invalid money format');
        }

        return new self((int)rtrim($value, '€'));
    }
}

$mapper = (new \CuyZ\Valinor\MapperBuilder())->mapper();

$mapper->map(Money::class, 42); // ✅
$mapper->map(Money::class, '42€'); // ✅
```

--------------------------------

### Map HTTP request with FromRoute and FromQuery attributes

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/how-to/map-http-request.md

Uses #[FromRoute] and #[FromQuery] attributes to map route and query parameters to controller arguments. The example shows a ListArticles controller and an HttpRequest with route and query parameters, followed by mapping and invocation.

```php
use CuyZ\Valinor\Mapper\Http\FromQuery;
use CuyZ\Valinor\Mapper\Http\FromRoute;
use CuyZ\Valinor\Mapper\Http\HttpRequest;
use CuyZ\Valinor\MapperBuilder;

final class ListArticles
{
    /**
     * GET /api/authors/{authorId}/articles?status=X&page=X&limit=X
     * 
     * @param non-empty-string $status
     * @param positive-int $page
     * @param int<10, 100> $limit
     */
    public function __invoke(
        // Comes from the route
        #[FromRoute] string $authorId,

        // All come from query parameters
        #[FromQuery] string $status,
        #[FromQuery] int $page = 1,
        #[FromQuery] int $limit = 10,
    ): ResponseInterface { … }
}

// GET /api/authors/42/articles?status=published&page=2
$request = new HttpRequest(
    routeParameters: ['authorId' => 42],
    queryParameters: [
        'status' => 'published',
        'page' => 2,
    ],
);

$controller = new ListArticles();

$arguments = (new MapperBuilder())
    ->argumentsMapper()
    ->mapArguments($controller, $request);

$response = $controller(...$arguments);
```

--------------------------------

### Using value-of<BackedEnum> type

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-1.13.0.md

This example demonstrates the new `value-of<BackedEnum>` type, which allows mapping a string to a backed enum's value. The mapper returns the string value 'D' for the enum case `Diamonds`.

```php
enum Suit: string
{
    case Hearts = 'H';
    case Diamonds = 'D';
    case Clubs = 'C';
    case Spades = 'S';
}

$suit = (new \CuyZ\Valinor\MapperBuilder())
    ->mapper()
    ->map('value-of<Suit>', 'D');

// $suit === 'D'
```

--------------------------------

### Map JSON to Typed Objects

Source: https://github.com/cuyz/valinor/blob/master/README.md

This example demonstrates defining data classes with type annotations and using the MapperBuilder to map JSON input into those objects. It includes error handling for mapping failures.

```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…
}
```

--------------------------------

### Register pattern-specific enum constructor

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-1.3.0.md

Shows how to register a constructor for a specific enum pattern using a closure. The constructor is only called when the pattern 'SomeEnum::BA*' is requested during mapping. The example includes the enum definition and the mapping call.

```php
enum SomeEnum
{
    case FOO;
    case BAR;
    case BAZ;
}

(new \CuyZ\Valinor\MapperBuilder())
    ->registerConstructor(
        /**
         * This constructor will be called only when pattern
         * `SomeEnum::BA*` is requested during mapping.
         *
         * @return SomeEnum::BA*
         */
        fn (string $value): SomeEnum => /* Some custom domain logic */
    )
    ->mapper()
    ->map(SomeEnum::class . '::BA*', 'some custom value');
```

--------------------------------

### JSON normalizer with JsonNormalizer::withOptions()

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-1.12.0.md

Demonstrates using the new JsonNormalizer::withOptions() method to pass JSON encoding flags like JSON_PRESERVE_ZERO_FRACTION. The example normalizes a Coordinates object and shows the resulting JSON string. Note that JSON_THROW_ON_ERROR is always enforced and not accepted.

```php
namespace My\App;

$normalizer = (new \CuyZ\Valinor\MapperBuilder())
    ->normalizer(\CuyZ\Valinor\Normalizer\Format::json())
    ->withOptions(\JSON_PRESERVE_ZERO_FRACTION);

$lowerManhattanAsJson = $normalizer->normalize(
    new \My\App\Coordinates(
        longitude: 40.7128,
        latitude: -74.0000
    )
);

// `$lowerManhattanAsJson` is a valid JSON string representing the data:
// {"longitude":40.7128,"latitude":-74.0000}
```

--------------------------------

### Basic normalizer usage with Format::array

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/serialization/normalizer.md

Builds a normalizer using NormalizerBuilder and Format::array, then normalizes a User object with nested Country into an array. The output is an array that can be serialized to any data format. The example shows the expected normalized array structure.

```php
namespace My\App;

$normalizer = (new \CuyZ\Valinor\NormalizerBuilder())
    ->normalizer(\CuyZ\Valinor\Normalizer\Format::array());

$userAsArray = $normalizer->normalize(
    new \My\App\User(
        name: 'John Doe',
        age: 42,
        country: new \My\App\Country(
            name: 'France',
            countryCode: 'FR',
        ),
    ),
);

// `$userAsArray` is now an array and can be manipulated much more easily, for
// instance to be serialized to the wanted data format.
//
// [
//     'name' => 'John Doe',
//     'age' => 42,
//     'country' => [
//         'name' => 'France',
//         'countryCode' => 'FR',
//     ],
// ];
```

--------------------------------

### Handle MappingError with try/catch and message formatting

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/usage/validation-and-error-handling.md

Wrap the mapping call in a try/catch to handle \CuyZ\Valinor\Mapper\MappingError. Use $error->messages() to get a flattened list of all detected messages, optionally format them with MessageMapFormatter and TranslationMessageFormatter, then iterate and echo each message.

```php
try {
    (new \CuyZ\Valinor\MapperBuilder())
        ->mapper()
        ->map(SomeClass::class, [/* … */ ]);
} catch (\CuyZ\Valinor\Mapper\MappingError $error) {
    // Get a flattened list of all messages detected during mapping
    $messages = $error->messages();

    // Formatters can be added and will be applied on all messages
    $messages = $messages->formatWith(
        new \CuyZ\Valinor\Mapper\Tree\Message\Formatter\MessageMapFormatter([
            // …
        ]),
        (new \CuyZ\Valinor\Mapper\Tree\Message\Formatter\TranslationMessageFormatter())
            ->withTranslations([
                // …
            ])
    );

    foreach ($messages as $message) {
        echo $message;
    }
}
```

--------------------------------

### Building HttpRequest from PSR-7 ServerRequestInterface

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/how-to/map-http-request.md

Shows how to create an HttpRequest from a PSR-7 ServerRequestInterface using the fromPsr factory method. The example then maps arguments to a controller using the argumentsMapper. The factory extracts query parameters from getQueryParams() and body values from getParsedBody(), and passes the original PSR-7 request through for potential injection.

```php
use CuyZ\Valinor\Mapper\Http\HttpRequest;
use CuyZ\Valinor\MapperBuilder;

// `$psrRequest` is a PSR-7 `ServerRequestInterface` instance
// `$routeParameters` are the parameters extracted by the router
$request = HttpRequest::fromPsr($psrRequest, $routeParameters);

$arguments = (new MapperBuilder())
    ->argumentsMapper()
    ->mapArguments($controller, $request);
```

--------------------------------

### Allow non-sequential lists with MapperBuilder::allowNonSequentialList()

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-1.17.0.md

Allows the mapper to convert associative arrays to a list with sequential keys. By default, list types only accept sequential keys starting from 0. The example maps an associative array to a list<int>, resulting in [0 => 42, 1 => 1337].

```php
(new \CuyZ\Valinor\MapperBuilder())
    ->allowNonSequentialList()
    ->mapper()
    ->map('list<int>', [
        'foo' => 42,
        'bar' => 1337,
    ]);

// => [0 => 42, 1 => 1337]
```

--------------------------------

### Import JSON, YAML, and file sources

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/how-to/import-formatted-source.md

Shows how to create a Source from a JSON string, YAML string, or a file with valid JSON/YAML content and valid extension, then map it to a class.

```php
$source = \CuyZ\Valinor\Mapper\Source\Source::json($jsonString);

// or…

$source = \CuyZ\Valinor\Mapper\Source\Source::yaml($yamlString);

// or…

// File containing valid Json or Yaml content and with valid extension
$source = \CuyZ\Valinor\Mapper\Source\Source::file(
    new SplFileObject('path/to/my/file.json')
);

(new \CuyZ\Valinor\MapperBuilder())
    ->mapper()
    ->map(SomeClass::class, $source);
```

--------------------------------

### Build source with Source::json() and path mapping

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-0.7.0.md

Shows the new Source builder entry point. Use Source::json() to wrap a JSON string, then chain camelCaseKeys() and map() to transform keys and paths before passing to the mapper.

```php
$source = \CuyZ\Valinor\Mapper\Source\Source::json($jsonString)
    ->camelCaseKeys()
    ->map([
        'towns' => 'cities',
        'towns.*.label' => 'name',
    ]);

$result = (new \CuyZ\Valinor\MapperBuilder())
    ->mapper()
    ->map(SomeClass::class, $source);
```

--------------------------------

### AsTransformer attribute usage example

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-1.11.0.md

Complete example of using the AsTransformer attribute to register a transformer for the normalizer. It defines a DateTimeFormat attribute, applies it to a property, and shows the normalized output.

```php
namespace My\App;

#[\CuyZ\Valinor\Normalizer\AsTransformer]
#[\Attribute(\Attribute::TARGET_PROPERTY)]
final class DateTimeFormat
{
    public function __construct(private string $format) {}

    public function normalize(\DateTimeInterface $date): string
    {
        return $date->format($this->format);
    }
}

final readonly class Event
{
    public function __construct(
        public string $eventName,
        #[\My\App\DateTimeFormat('Y/m/d')]
        public \DateTimeInterface $date,
    ) {}
}

(new \CuyZ\Valinor\MapperBuilder())
    ->normalizer(\CuyZ\Valinor\Normalizer\Format::array())
    ->normalize(new \My\App\Event(
        eventName: 'Release of legendary album',
        date: new \DateTimeImmutable('1971-11-08'),
    ));

// [
//     'eventName' => 'Release of legendary album',
//     'date' => '1971/11/08',
// ]
```

--------------------------------

### Inject and warm up cache with MapperBuilder::withCache()

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-0.9.0.md

Shows how to inject a PSR-16 cache implementation into the mapper builder, optionally wrapping it with FileWatchingCache in development, and how to warm up the cache during build and use it in the application. The cache must be registered before warmup, otherwise the warmup is useless.

```php
$cache = new \CuyZ\Valinor\Cache\FileSystemCache('path/to/cache-directory');

if ($isApplicationInDevelopmentEnvironment) {
    $cache = new \CuyZ\Valinor\Cache\FileWatchingCache($cache);
}

$mapperBuilder = (new \CuyZ\Valinor\MapperBuilder())->withCache($cache);

// During the build:
$mapperBuilder->warmup(SomeClass::class, SomeOtherClass::class);

// In the application:
$mapperBuilder->mapper()->map(SomeClass::class, [/* … */]);
```

--------------------------------

### Attribute-based date/time normalization with NormalizeDateTimeFormat

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-2.5.0.md

Applies the NormalizeDateTimeFormat attribute to a property to format only that property. The example shows the attribute on the 'createdAt' property.

```php
use CuyZ\Valinor\Normalizer\Configurator\NormalizeDateTimeFormat;

final readonly class User
{
    public function __construct(
        public string $name,

        #[NormalizeDateTimeFormat(DATE_ATOM)]
        public DateTimeInterface $createdAt,
    ) {}
}
```

--------------------------------

### Compare benchmarks with composer run-script benchmark-compare

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/internals/benchmarks.md

Compares the current benchmark results against the baseline. If any subject's average execution time goes above the baseline one, within a margin of error of 10%, it will fail the command.

```sh
composer run-script benchmark-compare
```

--------------------------------

### Create baseline with composer run-script benchmark-baseline

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/internals/benchmarks.md

Creates a baseline by running the benchmarks and storing the results. This is the first step before comparing against a baseline.

```sh
composer run-script benchmark-baseline
```

--------------------------------

### Run benchmarks with composer run-script benchmark

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/internals/benchmarks.md

Runs all benchmarks and produces a table with results. The interesting information is located in the table at the bottom.

```sh
composer run-script benchmark
```

--------------------------------

### Attribute-based key case normalization with NormalizeKeysToSnakeCase

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-2.5.0.md

Applies the NormalizeKeysToSnakeCase attribute to a class to convert only its keys. The example shows the resulting array with 'first_name'.

```php
use CuyZ\Valinor\Normalizer\Configurator\NormalizeKeysToSnakeCase;

#[NormalizeKeysToSnakeCase]
final readonly class User
{
    public function __construct(
        public string $firstName,
    ) {}
}

// ['first_name' => 'John']
```

--------------------------------

### Use NormalizerBuilder to register transformer

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-2.0.0.md

Shows how to instantiate a normalizer using the new NormalizerBuilder class, register a transformer for DateTimeInterface, and normalize data to an array format.

```php
$normalizer = (new \CuyZ\Valinor\NormalizerBuilder())
    ->registerTransformer(
        fn (\DateTimeInterface $date) => $date->format('Y/m/d')
    )
    ->normalizer(\CuyZ\Valinor\Normalizer\Format::array())
    ->normalize($someData);
```

--------------------------------

### Custom object normalization transformer

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/serialization/use-provided-normalizer-configurators.md

Implement custom normalization logic by registering a transformer on the NormalizerBuilder. This example checks if an object has a normalize method and uses it if available.

```php
namespace My\App;

final readonly class Address
{
    public function __construct(
        public string $road,
        public string $zipCode,
        public string $town,
    ) {}

    public function normalize(): array
    {
        return [
            'street' => $this->road,
            'postalCode' => $this->zipCode,
            'city' => $this->town,
        ];
    }
}

(new \CuyZ\Valinor\NormalizerBuilder())
    ->registerTransformer(function (object $object, callable $next) {
        return method_exists($object, 'normalize')
            ? $object->normalize()
            : $next();
    })
    ->normalizer(\CuyZ\Valinor\Normalizer\Format::array())
    ->normalize(
        new \My\App\Address(
            road: '221B Baker Street',
            zipCode: 'NW1 6XE',
            town: 'London',
        ),
    );

// [
//     'street' => '221B Baker Street',
//     'postalCode' => 'NW1 6XE',
//     'city' => 'London',
// ]
```

--------------------------------

### Psalm configuration to suppress @pure errors

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/upgrading.md

Add this xi:include to psalm.xml to globally suppress @pure errors reported by Psalm when using Valinor.

```xml

<xi:include href="qa/Psalm/valinor-psalm-suppress-pure-errors.xml"
            xmlns:xi="http://www.w3.org/2001/XInclude"/>
```

--------------------------------

### Global date/time normalization with NormalizeDateTimeFormat

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-2.5.0.md

Configures the normalizer to format all DateTimeInterface instances using DATE_ATOM. The example shows the output array with a formatted 'createdAt' value.

```php
use CuyZ\Valinor\Normalizer\Configurator\NormalizeDateTimeFormat;
use CuyZ\Valinor\Normalizer\Format;
use CuyZ\Valinor\NormalizerBuilder;

$userAsArray = (new NormalizerBuilder())
    ->configureWith(new NormalizeDateTimeFormat(DATE_ATOM))
    ->normalizer(Format::array())
    ->normalize($user);

// [
//     'name' => 'Jane Doe',
//     'createdAt' => '2000-01-01T00:00:00+00:00',
// ]
```

--------------------------------

### Chaining converters with priority

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/how-to/convert-input.md

Shows how to chain converters using a callable parameter and control execution order with priority. Higher priority runs earlier; default is 0.

```php
(new \CuyZ\Valinor\MapperBuilder())
    ->registerConverter(
        fn (string $value, callable $next): string => $next(strtoupper($value))
    )
    ->registerConverter(
        fn (string $value, callable $next): string => $next($value . '!'),
        priority: -10,
    )
    ->registerConverter(
        fn (string $value, callable $next): string => $next($value . '?'),
        priority: 10,
    )
    ->mapper()
    ->map('string', 'hello world'); // 'HELLO WORLD?!'
```

--------------------------------

### Configure cache with FileSystemCache and FileWatchingCache

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/other/performance-and-caching.md

Creates a FileSystemCache instance, optionally wraps it with FileWatchingCache in development to invalidate on file changes. The same cache instance is used for both MapperBuilder and NormalizerBuilder.

```php
$cache = new \CuyZ\Valinor\Cache\FileSystemCache('path/to/cache-directory');

if ($isApplicationInDevelopmentEnvironment) {
    $cache = new \CuyZ\Valinor\Cache\FileWatchingCache($cache);
}

(new \CuyZ\Valinor\MapperBuilder())
    ->withCache($cache)
    ->mapper()
    ->map(SomeClass::class, [/* … */]);
    
(new \CuyZ\Valinor\NormalizerBuilder())
    ->withCache($cache)
    ->normalizer(\CuyZ\Valinor\Normalizer\Format::json())
    ->normalize($someData);
```

--------------------------------

### Chain converters with priority

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-2.0.0.md

Demonstrates chaining multiple converters with a callable parameter to call the next converter, and using priority to control execution order. The default priority is 0; higher priority runs earlier.

```php
(new \CuyZ\Valinor\MapperBuilder())
    ->registerConverter(
        function(string $value, callable $next): string {
            return $next(strtoupper($value));
        }
    )
    ->registerConverter(
        function(string $value, callable $next): string {
            return $next($value . '!');
        },
        priority: -10,
    )
    ->registerConverter(
        function(string $value, callable $next): string {
            return $next($value . '?');
        },
        priority: 10,
    )
    ->mapper()
    ->map('string', 'hello world'); // 'HELLO WORLD?!'
```

--------------------------------

### Using Valinor mapper

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/index.md

Shows how to use Valinor's MapperBuilder to map an array to a Person object, with try-catch for MappingError. This simplifies the process compared to manual validation.

```php
$data = $client->request('GET', 'https://example.com/person/42')->toArray();

try {
    $person = (new \CuyZ\Valinor\MapperBuilder())
        ->mapper()
        ->map(Person::class, $data);
} catch (\CuyZ\Valinor\Mapper\MappingError $error) {
    // Detailed error handling
}
```

--------------------------------

### Mapping to a shaped array with static analysis errors

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/other/static-analysis.md

Example of mapping to a shaped array with string and int values. The static analysis tools will report errors for type mismatches and undefined offsets.

```php
$array = (new \CuyZ\Valinor\MapperBuilder())
    ->mapper()
    ->map(
        'array{foo: string, bar: int}',
        [/* … */]
    );

// ✅
echo $array['foo'];

// ❌ Expected `string` but got `int`
echo strtolower($array['bar']);

// ❌ Cannot perform operation between `string` and `int`
echo $array['foo'] * $array['bar'];

// ❌ Offset `fiz` does not exist on array
echo $array['fiz'];
```

--------------------------------

### PHPStan configuration to include Valinor extension

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/other/static-analysis.md

Add this include to your phpstan.neon file to activate the Valinor PHPStan extension.

```yaml
includes:
    - vendor/cuyz/valinor/qa/PHPStan/valinor-phpstan-configuration.php
```

--------------------------------

### Union class-string handling in docblocks

Source: https://github.com/cuyz/valinor/blob/master/docs/pages/project/changelog/version-0.8.0.md

Demonstrates declaring multiple class names within a class-string docblock.

```php
class Foo
{
    /** @var class-string<SomeClass|SomeOtherClass> */
    public readonly string $className;
}
```
Tokens:
Raw