diff --git a/docs/pages/project/changelog.md b/docs/pages/project/changelog.md index c21e7814..12fa5a06 100644 --- a/docs/pages/project/changelog.md +++ b/docs/pages/project/changelog.md @@ -9,6 +9,7 @@ Below are listed the changelogs for all released versions of the library. ## Version 1 +- [`1.9.0` — 2nd of February 2024](changelog/version-1.9.0.md) - [`1.8.2` — 8th of January 2024](changelog/version-1.8.2.md) - [`1.8.1` — 8th of January 2024](changelog/version-1.8.1.md) - [`1.8.0` — 26th of December 2023](changelog/version-1.8.0.md) diff --git a/docs/pages/project/changelog/version-1.9.0.md b/docs/pages/project/changelog/version-1.9.0.md new file mode 100644 index 00000000..01aba221 --- /dev/null +++ b/docs/pages/project/changelog/version-1.9.0.md @@ -0,0 +1,90 @@ +# Changelog 1.9.0 — 2nd of February 2024 + +!!! info inline end "[See release on GitHub]" + [See release on GitHub]: https://github.com/CuyZ/Valinor/releases/tag/1.9.0 + +## Notable changes + +**JSON normalizer** + +The normalizer is able to normalize a data structure to JSON without using the +native `json_encode()` function. + +Using the normalizer instead of the native `json_encode()` function offers some +benefits: + +- Values will be recursively normalized using the default transformations +- All registered transformers will be applied to the data before it is formatted +- The JSON can be streamed to a PHP resource in a memory-efficient way + +Basic usage: + +```php +namespace My\App; + +$normalizer = (new \CuyZ\Valinor\MapperBuilder()) + ->normalizer(\CuyZ\Valinor\Normalizer\Format::json()); + +$userAsJson = $normalizer->normalize( + new \My\App\User( + name: 'John Doe', + age: 42, + country: new \My\App\Country( + name: 'France', + code: 'FR', + ), + ) +); + +// `$userAsJson` is a valid JSON string representing the data: +// {"name":"John Doe","age":42,"country":{"name":"France","code":"FR"}} +``` + +By default, the JSON normalizer will return a JSON string representing the data +it was given. Instead of getting a string, it is possible to stream the JSON +data to a PHP resource: + +```php +$file = fopen('path/to/some_file.json', 'w'); + +$normalizer = (new \CuyZ\Valinor\MapperBuilder()) + ->normalizer(\CuyZ\Valinor\Normalizer\Format::json()) + ->streamTo($file); + +$normalizer->normalize(/* … */); + +// The file now contains the JSON data +``` + +Another benefit of streaming the data to a PHP resource is that it may be more +memory-efficient when using generators — for instance when querying a database: + +```php +// In this example, we assume that the result of the query below is a +// generator, every entry will be yielded one by one, instead of +// everything being loaded in memory at once. +$users = $database->execute('SELECT * FROM users'); + +$file = fopen('path/to/some_file.json', 'w'); + +$normalizer = (new \CuyZ\Valinor\MapperBuilder()) + ->normalizer(\CuyZ\Valinor\Normalizer\Format::json()) + ->streamTo($file); + +// Even if there are thousands of users, memory usage will be kept low +// when writing JSON into the file. +$normalizer->normalize($users); +``` + +## Features + +* Introduce JSON normalizer ([959740](https://github.com/CuyZ/Valinor/commit/9597407db04ff9d6e59ac8c6b8895d5fcf9caaa5)) + +## Bug Fixes + +* Add default transformer for `DateTimeZone` ([acf097](https://github.com/CuyZ/Valinor/commit/acf0976ae0f63604fef28240531048a9f5633375)) +* Detect circular references linearly through objects ([36aead](https://github.com/CuyZ/Valinor/commit/36aead96bd8b5696a321bc2df7386aa16264ab58)) + +## Other + +* Refactor attribute definition to include class definition ([4b8cf6](https://github.com/CuyZ/Valinor/commit/4b8cf65080088c77c5257ae2e7da2d1fdee2fb2e))