CuyZ/Valinor 1.0.0

on GitHub

First stable version! 🥳 🎉

This release marks the end of the initial development phase. The library has been live for exactly one year at this date and is stable enough to start following the semantic versioning — it means that any backward incompatible change (aka breaking change) will lead to a bump of the major version.

This is the biggest milestone achieved by this project (yet™); I want to thank everyone who has been involved to make it possible, especially the contributors who submitted high-quality pull requests to improve the library.

There is also one person that I want to thank even more: my best friend Nathan, who has always been so supportive with my side-projects. Thanks, bro! 🙌

The last year marked a bigger investment of my time in OSS contributions; I've proven to myself that I am able to follow a stable way of managing my engagement to this community, and this is why I enabled sponsorship on my profile to allow people to ❤️ sponsor my work on GitHub — if you use this library in your applications, please consider offering me a 🍺 from time to time! 🤗

Notable changes

End of PHP 7.4 support

PHP 7.4 security support has ended on the 28th of November 2022; the minimum version supported by this library is now PHP 8.0.

New mapper to map arguments of a callable

This new mapper can be used to ensure a source has the right shape before calling a function/method.

The mapper builder can be configured the same way it would be with a tree mapper, for instance to customize the type strictness.

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

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

    // some value / 42
    echo $someFunction(...$arguments);
} catch (\CuyZ\Valinor\Mapper\MappingError $error) {
    // Do something…
}

Support for TimeZone objects

Native TimeZone objects construction is now supported with a proper error handling.

try {
    (new \CuyZ\Valinor\MapperBuilder())
        ->mapper()
        ->map(DateTimeZone::class, 'Jupiter/Europa');
} catch (MappingError $exception) {
    $error = $exception->node()->messages()[0];

    // Value 'Jupiter/Europa' is not a valid timezone.
    echo $error->toString();
}

Mapping object with one property

When a class needs only one value, the source given to the mapper must match the type of the single property/parameter.

This change aims to bring consistency on how the mapper behaves when mapping an object that needs one argument. Before this change, the source could either match the needed type, or be an array with a single entry and a key named after the argument.

See example below:

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…',
]);

Upgrading from 0.x to 1.0

As this is a major release, all deprecated features have been removed, leading to an important number of breaking changes.

You can click on the entries below to get advice on available replacements.

⚠ BREAKING CHANGES

• Disallow array when mapping to object with one argument (72cba3)
• Mark tree mapper and arguments mapper as @pure (0d9855)
• Remove deprecated backward compatibility datetime constructor (a65e8d)
• Remove deprecated class ThrowableMessage (d36ca9)
• Remove deprecated class to flatten messages (f9ed93)
• Remove deprecated interface TranslatableMessage (ceb197)
• Remove deprecated message methods (e6557d)
• Remove deprecated method constructor attribute (d76467)
• Remove deprecated method to enable flexible mode (a2bef3)
• Remove deprecated method to set cache directory (b0d6d2)
• Remove deprecated method used to bind a callback (b79ed8)
• Remove deprecated placeholder message formatter (c2723d)
• Remove Doctrine annotations support (66c182)
• Remove identifier attribute (8a7486)
• Remove PHP 7.4 support (5f5a50)
• Remove support for strict-array type (22c3b4)

Features

• Add constructor for DateTimeZone with error support (a0a4d6)
• Introduce mapper to map arguments of a callable (9c7e88)

Bug Fixes

• Allow mapping null to single node nullable type (0a98ec)
• Handle single argument mapper properly (d7bf6a)
• Handle tree mapper call without argument in PHPStan extension (3f3a01)
• Handle tree mapper call without argument in Psalm plugin (b425af)

Other

• Activate value altering feature only when callbacks are registered (0f33a5)
• Bump psr/simple-cache supported version (e4059a)
• Remove @ from comments for future PHP versions changes (68774c)
• Update dependencies (4afcda)