release: version 1.9.0

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)

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))