This notation is mainly useful when several cases in constants of a
class share a common prefix.
```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
```
This notation can be used when several cases in an enum share a common
prefix.
```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
```
The new class `\CuyZ\Valinor\Mapper\Tree\Message\MessageBuilder` can be
used to easily create an instance of (error) message.
This new straightforward way of creating messages leads to the
depreciation of `\CuyZ\Valinor\Mapper\Tree\Message\ThrowableMessage`.
```php
$message = MessageBuilder::newError('Some message / {some_parameter}.')
->withCode('some_code')
->withParameter('some_parameter', 'some_value')
->build();
```
```php
(new \CuyZ\Valinor\MapperBuilder())
// Both `Cookie` and `ATOM` formats will be accepted
->supportDateFormats(DATE_COOKIE, DATE_ATOM)
->mapper()
->map(DateTimeInterface::class, 'Monday, 08-Nov-1971 13:37:42 UTC');
```
A new constructor can be registered to declare which format(s) are
supported during the mapping of a date object. By default, any valid
timestamp or ATOM-formatted value will be accepted.
```php
(new \CuyZ\Valinor\MapperBuilder())
// Both COOKIE and ATOM formats will be accepted
->registerConstructor(
new \CuyZ\Valinor\Mapper\Object\DateTimeFormatConstructor(DATE_COOKIE, DATE_ATOM)
)
->mapper()
->map(DateTimeInterface::class, 'Monday, 08-Nov-1971 13:37:42 UTC');
```
The previously very opinionated behaviour has been removed, but can be
temporarily used to help with the migration.
```php
(new \CuyZ\Valinor\MapperBuilder())
->registerConstructor(
new \CuyZ\Valinor\Mapper\Object\BackwardCompatibilityDateTimeConstructor()
)
->mapper()
->map(DateTimeInterface::class, 'Monday, 08-Nov-1971 13:37:42 UTC');
```
In some situations the type handled by a constructor is only known at
runtime, in which case the constructor needs to know what class must be
used to instantiate the object.
For instance, an interface may declare a static constructor that is then
implemented by several child classes. One solution would be to register
the constructor for each child class, which leads to a lot of
boilerplate code and would require a new registration each time a new
child is created. Another way is to use the attribute
`\CuyZ\Valinor\Mapper\Object\DynamicConstructor`.
When a constructor uses this attribute, its first parameter must be a
string and will be filled with the name of the actual class that the
mapper needs to build when the constructor is called. Other arguments
may be added and will be mapped normally, depending on the source given
to the mapper.
```php
interface InterfaceWithStaticConstructor
{
public static function from(string $value): self;
}
final 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\Attribute\DynamicConstructor]
function (string $className, string $value): InterfaceWithStaticConstructor {
return $className::from($value);
}
)
->mapper()
->map(ClassWithInheritedStaticConstructor::class, 'foo');
```
The `\CuyZ\Valinor\Mapper\Tree\Message\Message` interface is no longer
a `Stringable`, however it defines a new method `body` that must return
the body of the message, which can contain placeholders that will be
replaced by parameters.
These parameters can now be defined by implementing the interface
`\CuyZ\Valinor\Mapper\Tree\Message\HasParameters`.
This leads to the deprecation of the no longer needed interface
`\CuyZ\Valinor\Mapper\Tree\Message\TranslatableMessage` which had a
confusing name.
```php
final class SomeException
extends DomainException
implements ErrorMessage, HasParameters, HasCode
{
private string $someParameter;
public function __construct(string $someParameter)
{
parent::__construct();
$this->someParameter = $someParameter;
}
public function body() : string
{
return 'Some message / {some_parameter} / {source_value}';
}
public function parameters(): array
{
return [
'some_parameter' => $this->someParameter,
];
}
public function code() : string
{
// A unique code that can help to identify the error
return 'some_unique_code';
}
}
```
The class `\CuyZ\Valinor\Mapper\Tree\Node` has been refactored to remove
access to unwanted methods that were not supposed to be part of the
public API. Below are a list of all changes:
- New methods `$node->sourceFilled()` and `$node->sourceValue()` allow
accessing the source value.
- The method `$node->value()` has been renamed to `$node->mappedValue()`
and will throw an exception if the node is not value.
- The method `$node->type()` now returns a string.
- The methods `$message->name()`, `$message->path()`, `$message->type()`
and `$message->value()` have been deprecated in favor of the new
method `$message->node()`.
- The message parameter `{original_value}` has been deprecated in favor
of `{source_value}`.
/!\ This change fixes a security issue.
Userland exception thrown in a constructor will not be automatically
caught by the mapper anymore. This prevents messages with sensible
information from reaching the final user — for instance an SQL exception
showing a part of a query.
To allow exceptions to be considered as safe, the new method
`MapperBuilder::filterExceptions()` must be used, with caution.
```php
final class SomeClass
{
public function __construct(private string $value)
{
\Webmozart\Assert\Assert::startsWith($value, 'foo_');
}
}
try {
(new \CuyZ\Valinor\MapperBuilder())
->filterExceptions(function (Throwable $exception) {
if ($exception instanceof \Webmozart\Assert\InvalidArgumentException) {
return \CuyZ\Valinor\Mapper\Tree\Message\ThrowableMessage::from($exception);
}
// If the exception should not be caught by this library, it
// must be thrown again.
throw $exception;
})
->mapper()
->map(SomeClass::class, 'bar_baz');
} catch (\CuyZ\Valinor\Mapper\MappingError $exception) {
// Should print something similar to:
// > Expected a value to start with "foo_". Got: "bar_baz"
echo $exception->node()->messages()[0];
}
```
The mapper is now more type-sensitive and will fail in the following
situations:
- When a value does not match exactly the awaited scalar type, for
instance a string `"42"` given to a node that awaits an integer.
- When unnecessary array keys are present, for instance mapping an array
`['foo' => …, 'bar' => …, 'baz' => …]` to an object that needs only
`foo` and `bar`.
- When permissive types like `mixed` or `object` are encountered.
These limitations can be bypassed by enabling the flexible mode:
```php
(new \CuyZ\Valinor\MapperBuilder())
->flexible()
->mapper();
->map('array{foo: int, bar: bool}', [
'foo' => '42', // Will be cast from `string` to `int`
'bar' => 'true', // Will be cast from `string` to `bool`
'baz' => '…', // Will be ignored
]);
```
When using this library for a provider application — for instance an API
endpoint that can be called with a JSON payload — it is recommended to
use the strict mode. This ensures that the consumers of the API provide
the exact awaited data structure, and prevents unknown values to be
passed.
When using this library as a consumer of an external source, it can make
sense to enable the flexible mode. This allows for instance to convert
string numeric values to integers or to ignore data that is present in
the source but not needed in the application.
---
All these changes led to a new check that runs on all registered object
constructors. If a collision is found between several constructors that
have the same signature (the same parameter names), an exception will be
thrown.
```php
final class SomeClass
{
public static function constructorA(string $foo, string $bar): self
{
// …
}
public static function constructorB(string $foo, string $bar): self
{
// …
}
}
(new \CuyZ\Valinor\MapperBuilder())
->registerConstructor(
SomeClass::constructorA(...),
SomeClass::constructorB(...),
)
->mapper();
->map(SomeClass::class, [
'foo' => 'foo',
'bar' => 'bar',
]);
// Exception: A collision was detected […]
```
It is now mandatory to list all possible class-types that can be
inferred by the mapper. This change is a step towards the library being
able to deliver powerful new features such as compiling a mapper for
better performance.
BREAKING CHANGE: the existing calls to `MapperBuilder::infer` that could
return several class-names must now add a signature to the callback. The
callbacks that require no parameter and always return the same
class-name can remain unchanged.
For instance:
```php
$builder = (new \CuyZ\Valinor\MapperBuilder())
// Can remain unchanged
->infer(SomeInterface::class, fn () => SomeImplementation::class);
```
```php
$builder = (new \CuyZ\Valinor\MapperBuilder())
->infer(
SomeInterface::class,
fn (string $type) => match($type) {
'first' => ImplementationA::class,
'second' => ImplementationB::class,
default => throw new DomainException("Unhandled `$type`.")
}
)
// …should be modified with:
->infer(
SomeInterface::class,
/** @return class-string<ImplementationA|ImplementationB> */
fn (string $type) => match($type) {
'first' => ImplementationA::class,
'second' => ImplementationB::class,
default => throw new DomainException("Unhandled `$type`.")
}
);
```
