Commit Graph

126 Commits

Author SHA1 Message Date
Romain Canon
6fdd62dfc2 fix: change license in composer.json 2022-02-21 17:05:28 +01:00
Romain Canon
b6b3296638 feat: handle variadic parameters in constructors
Using variadic parameters is now handled properly by the library,
meaning the following example will run:

```php
final class SomeClass
{
    /** @var string[] */
    private array $values;

    public function __construct(string ...$values)
    {
        $this->values = $values;
    }
}

(new \CuyZ\Valinor\MapperBuilder())
    ->mapper()
    ->map(SomeClass::class, ['foo', 'bar', 'baz']);
```
2022-02-19 20:17:03 +01:00
Romain Canon
c1a884fadd qa: require and include phpstan/phpstan-phpunit rules 2022-02-19 19:58:28 +01:00
Romain Canon
6d427088f7 feat!: improve object binding API
The method `MapperBuilder::bind()` can be used to define a custom way to
build an object during the mapping.

The return type of the callback will be resolved by the mapping to know
when to use it.

The callback can take any arguments, that will automatically be mapped
using the given source. These arguments can then be used to instantiate
the object in the desired way.

Example:

```php
(new \CuyZ\Valinor\MapperBuilder())
    ->bind(function(string $string, OtherClass $otherClass): SomeClass {
        $someClass = new SomeClass($string);
        $someClass->addOtherClass($otherClass);

        return $someClass;
    })
    ->mapper()
    ->map(SomeClass::class, [
        // …
    ]);
```
2022-02-19 19:58:28 +01:00
Romain Canon
422e6a8b27 feat: improve value altering API 2022-02-19 19:58:28 +01:00
Romain Canon
380961247e feat: introduce method to get parameter by index 2022-02-19 19:58:28 +01:00
Romain Canon
d6e778aff7 refactor: regroup object inferring strategies
Inferring object unions and named constructor are now done using the
same algorithm — in class `ObjectBuilderFilterer` — which is called from
a unique entry point in `ClassNodeBuilder`.
2022-02-19 19:58:28 +01:00
Romain Canon
30d4479aef misc: check value acceptance in separate node builder 2022-02-19 19:58:28 +01:00
Romain Canon
06e9dedfd8 misc: narrow union types during node build 2022-02-19 19:58:28 +01:00
Romain Canon
b49ebf37be feat: introduce function definition repository 2022-02-19 19:58:28 +01:00
Nathan Boiron
d9465222f4
feat: introduce a camel case source key modifier 2022-02-19 19:47:04 +01:00
mtouellette
18ccbebb9a
fix: ensure native mixed types remain valid 2022-02-16 15:50:14 +01:00
Marek Mikula
1b80a1df9d
fix: write temporary cache file inside cache subdirectory
Prevents potential issues with permissions on the system default 
temporary directory returned by `sys_get_temp_dir()`.
2022-02-15 23:24:15 +01:00
Romain Canon
810c1abc6f release: version 0.5.0 2022-01-26 19:57:43 +01:00
Fred-Jan van der Eijken
66aa4d688a
fix: return indexed list of attributes when filtering on type 2022-01-26 18:59:57 +01:00
Romain Canon
718d3c1bc2 feat: introduce automatic named constructor resolution
An object may have several ways of being created — in such cases it is
common to use so-called named constructors, also known as static factory
methods. If one or more are found, they can be called during the mapping
to create an instance of the object.

What defines a named constructor is a method that:

1. is public
2. is static
3. returns an instance of the object
4. has one or more arguments

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

    /**
     * @param int<0, 255> $red
     * @param int<0, 255> $green
     * @param int<0, 255> $blue
     */
    public static function fromRgb(
        int $red,
        int $green,
        int $blue,
    ): self {
        return new self($red, $green, $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);
    }
}
```
2022-01-25 18:32:28 +01:00
Romain Canon
7869cbd09c refactor: remove unnecessary ClassSignature
This abstraction layer was not useful, so it is removed to simplify the
API around `ClassDefinition`.

A new method `ClassDefinition::type()` is also added, giving access to
the `ClassType` instance when working with a class definition.
2022-01-25 18:32:28 +01:00
Marco Pivetta
e280033941 feat: simplify type signature of TreeMapper#map()
This also brings `TreeMapper#map()` closer to PHPStorm support, whilst
still benefiting from more precise `vimeo/psalm:4.18.x` types thanks to
the conditional return specification.

Ref: https://github.com/CuyZ/Valinor/pull/59#discussion_r782362428
2022-01-13 19:55:20 +01:00
Marco Pivetta
f9b04c5c27 fix: improve type definitions to allow Psalm automatic inferring 2022-01-13 19:55:20 +01:00
Marco Pivetta
7a49f45175 test: configure vimeo/psalm to verify type inference
This is mostly to include type inference in regression tests: out-of-the
box type inference for 99% of usages is based on
`TreeMapper#map(class-string<T>, mixed): T`, and it is worth preserving
that behavior without the need of plugins.

This test covers that.
2022-01-13 19:55:20 +01:00
Marco Pivetta
822865876d chore: downgrade dependencies to a dependency set that works on 7.4 too
Used for locked tests.
2022-01-13 19:55:20 +01:00
Marco Pivetta
9e66b951b7 test: run tests with lowest, highest and **locked** dependencies
This also uses `ramsey/composer-install@v2` to cache dependencies,
instead of having to set up the automation on our own with
`actions/cache` (messy).
2022-01-13 19:55:20 +01:00
Marco Pivetta
23b6113869 feat: set up dependabot for automated weekly dependency upgrades 2022-01-13 19:55:20 +01:00
Jacob Dreesen
39f0b71b94 fix: correct regex that detects @internal or @api annotations 2022-01-13 18:53:41 +01:00
Romain Canon
4267c20423 misc!: mark classes with @internal or @api annotation
This change filters the scope of the public API that is provided by this
library.

Any class or interface that is not explicitly marked with an `@api`
annotation should never be used outside this library — any change can
and will be made without taking breaking changes rules into account.

When a breaking change happens inside the public API scope, a major
version will be released; refer to https://semver.org for more
information.

A new PHPStan extension is now part of the quality assurance process,
ensuring that all classes/interfaces must provide either `@internal` or
`@api` annotation.
2022-01-13 18:23:47 +01:00
Romain Canon
1e0084c6cd test: upgrade Infection to 0.26
This new version grants a new `--git-diff-lines` options, as well as a
new badge/report system.
2022-01-11 19:19:51 +01:00
Romain Canon
caed069f8a qa: validate composer lock file in workflow 2022-01-11 19:19:51 +01:00
Romain Canon
9326f58f85 misc: remove unneeded packages from composer.lock 2022-01-11 19:19:51 +01:00
Romain Canon
36b7f4d117 release: version 0.4.0 2022-01-07 13:50:26 +01:00
Romain Canon
79d7c266ec feat: introduce automatic union of objects inferring during mapping
When the mapper needs to map a source to a union of objects, it will try
to guess which object it will map to, based on the needed arguments of
the objects, and the values contained in the source.

```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']);
```
2022-01-07 13:41:15 +01:00
Romain Canon
8a74147d4c misc!: allow object builder to yield arguments without source
The `Argument` class must now be instantiated with one of the `required`
or `optional` static constructors.
2022-01-07 13:41:15 +01:00
Romain Canon
e834cdc5d3 fix: treat union type resolving error as message
Will be caught by the mapper and added in the messages list of the
nodes.
2022-01-07 13:41:15 +01:00
Romain Canon
36bd3638c8 fix: treat forbidden mixed type as invalid type 2022-01-07 13:41:15 +01:00
Romain Canon
47ecccee2b test: fix cache directory creation 2022-01-07 13:41:15 +01:00
Romain Canon
a97b406154 feat: introduce helper class MessagesFlattener
Will recursively flatten messages of a node and all its children.

This helper can for instance be used when errors occurred during a
mapping to flatten all caught errors into a basic array of string that
can then easily be used to inform the user of what is wrong.

```
try {
    // …
} catch(MappingError $error) {
    $messages = (new MessagesFlattener($error->node()))->errors();

    foreach ($messages as $message) {
        echo $message;
    }
}
```
2022-01-06 14:11:42 +01:00
Romain Canon
ddf69efaaa feat: introduce helper class MessageMapFormatter
Can be used to customize the content of messages added during a mapping.

An implementation is provided by the library — `MessageMapFormatter`:

The constructor parameter is an array where each key represents either:
- The code of the message to be replaced
- The content of the message to be replaced
- The class name of the message to be replaced

If none of those is found, the content of the message will stay
unchanged unless a default one is given to this class.

If one of these keys is found, the array entry will be used to replace
the content of the message. This entry can be either a plain text or a
callable that takes the message as a parameter and returns a string; it
is for instance advised to use a callable in cases where a translation
service is used — to avoid useless greedy operations.

In any case, the content can contain placeholders that can be used the
same way as `\CuyZ\Valinor\Mapper\Tree\Message\NodeMessage::format()`.

See usage examples below:

```
$formatter = (new MessageMapFormatter([
    // Will match if the given message has this exact code
    'some_code' => 'new content / previous code was: %1$s',

    // Will match if the given message has this exact content
    'Some message content' => 'new content / previous message: %2$s',

    // Will match if the given message is an instance of this class
    SomeError::class => '
        - Original code of the message: %1$s
        - Original content of the message: %2$s
        - Node type: %3$s
        - Node name: %4$s
        - Node path: %5$s
    ',

    // A callback can be used to get access to the message instance
    OtherError::class => function (NodeMessage $message): string {
        if ((string)$message->type() === 'string|int') {
            // …
        }

        return 'Some message content';
    },

    // For greedy operation, it is advised to use a lazy-callback
    'bar' => fn () => $this->translator->translate('foo.bar'),
]))
    ->defaultsTo('some default message')
    // …or…
    ->defaultsTo(fn () => $this->translator->translate('default'));

$content = $formatter->format($message);
```
2022-01-06 14:11:42 +01:00
Romain Canon
cc1bc66bbe feat: introduce helper NodeTraverser for recursive operations on nodes 2022-01-06 14:11:42 +01:00
Romain Canon
2fd0bc10d0 test: fix wrong namespace for some classes 2022-01-06 14:11:42 +01:00
Romain Canon
a805ba0442 feat!: wrap node messages in proper class
A new class `NodeMessage` is used to wrap messages added to a node
during the mapping. This class will allow further features by giving
access to useful data related to the bound node.

BREAKING CHANGE: as of now every message is wrapped into a `NodeMessage`
it is therefore not possible to check whether the message is an instance
of `Throwable` — a new method `$message->isError()` is now to be used
for such cases.
2022-01-06 14:11:42 +01:00
Romain Canon
2c7e1156db test: improve FakeType and introduce FakeNode 2022-01-06 14:11:42 +01:00
Romain Canon
626f135eee fix: use locked package versions for quality assurance workflow 2022-01-06 14:09:25 +01:00
Romain Canon
9537d0a5bb qa: fix PHPStan errors 2022-01-06 14:09:25 +01:00
Romain Canon
85a6a49ce2 misc: ignore changelog configuration file in git export 2022-01-06 14:09:25 +01:00
Romain Canon
b2e810e3ce feat!: allow mapping to any type
Previously, the method `TreeMapper::map` would allow mapping only to an
object. It is now possible to map to any type handled by the library.

It is for instance possible to map to an array of objects:

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

For simple use-cases, an array shape can be used:

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

echo strtolower($array['foo']);
echo $array['bar'] * 2;
```

This new feature changes the possible behaviour of the mapper, meaning
static analysis tools need help to understand the types correctly. An
extension for PHPStan and a plugin for Psalm are now provided and can be
included in a project to automatically increase the type coverage.
2022-01-02 00:48:01 +01:00
Romain Canon
33167d28d0 test: fix cache directory removal 2022-01-02 00:48:01 +01:00
Romain Canon
0144bf084a misc: raise PHPStan version
This enables full PHP 8.1 support 🎉
2021-12-31 13:30:14 +01:00
Aurimas Niekis
d2795bc6b9 fix: handle nested attributes compilation 2021-12-27 20:57:38 +01:00
Romain Canon
54f608e5b1 feat!: add access to root node when error occurs during mapping
When an error occurs during mapping, the root instance of `Node` can now
be accessed from the exception. This recursive object allows retrieving
all needed information through the whole mapping tree: path, values,
types and messages, including the issues that caused the exception.

It can be used like the following:

```php
try {
   (new \CuyZ\Valinor\MapperBuilder())
       ->mapper()
       ->map(SomeClass::class, [/* ... */]);
} catch (\CuyZ\Valinor\Mapper\MappingError $error) {
    // Do something with `$error->node()`
    // See README for more information
}
```

This change removes the method `MappingError::describe()` which provided
a flattened view of messages of all the errors that were encountered
during the mapping. The same behaviour can still be retrieved, see the
example below:

```php
use CuyZ\Valinor\Mapper\Tree\Message\Message;
use CuyZ\Valinor\Mapper\Tree\Node;

/**
 * @implements \IteratorAggregate<string, array<\Throwable&Message>>
 */
final class MappingErrorList implements \IteratorAggregate
{
    private Node $node;

    public function __construct(Node $node)
    {
        $this->node = $node;
    }

    /**
     * @return \Traversable<string, array<\Throwable&Message>>
     */
    public function getIterator(): \Traversable
    {
        yield from $this->errors($this->node);
    }

    /**
     * @return \Traversable<string, array<\Throwable&Message>>
     */
    private function errors(Node $node): \Traversable
    {
        $errors = array_filter(
            $node->messages(),
            static fn (Message $m) => $m instanceof \Throwable
        );

        if (! empty($errors)) {
            yield $node->path() => array_values($errors);
        }

        foreach ($node->children() as $child) {
            yield from $this->errors($child);
        }
    }
}

try {
   (new \CuyZ\Valinor\MapperBuilder())
       ->mapper()
       ->map(SomeClass::class, [/* ... */]);
} catch (\CuyZ\Valinor\Mapper\MappingError $error) {
    $errors = iterator_to_array(new MappingErrorList($error->node()));
}
```

The class `CannotMapObject` is deleted, as it does not provide any
value; this means that `MappingError` which was previously an interface
becomes a class.
2021-12-27 13:52:36 +01:00
Romain Canon
f12ef39e2f release: version 0.3.0 2021-12-18 22:40:24 +01:00
Brandon Savage
179ba3df29
feat: handle common database datetime formats (#40) 2021-12-17 17:55:17 +01:00