Changelog 1.8.0 — 26th of December 2023¶
Notable changes¶
Normalizer service (serialization)
This new service can be instantiated with the MapperBuilder. It allows
transformation of a given input into scalar and array values, while preserving
the original structure.
This feature can be used to share information with other systems that use a data format (JSON, CSV, XML, etc.). The normalizer will take care of recursively transforming the data into a format that can be serialized.
Below is a basic example, showing the transformation of objects into an array of scalar values.
namespace My\App;
$normalizer = (new \CuyZ\Valinor\MapperBuilder())
->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',
// ],
// ];
A normalizer can be extended by using so-called transformers, which can be either an attribute or any callable object.
In the example below, a global transformer is used to format any date found by the normalizer.
(new \CuyZ\Valinor\MapperBuilder())
->registerTransformer(
fn (\DateTimeInterface $date) => $date->format('Y/m/d')
)
->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',
// ]
This date transformer could have been an attribute for a more granular control, as shown below.
namespace My\App;
#[\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())
->registerTransformer(\My\App\DateTimeFormat::class)
->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',
// ]
More features are available, details about it can be found in the documentation.
Features¶
- Introduce normalizer service (1c9368)