Skip to content

Commit 99af5cd

Browse files
rommromm
committed
release: version 1.0.0
🎉
1 parent ea34120 commit 99af5cd

2 files changed

Lines changed: 251 additions & 0 deletions

File tree

‎docs/pages/project/changelog.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,10 @@ hide:
77

88
Below are listed the changelogs for all released version of the library.
99

10+
## Version 1.0
11+
12+
- [`1.0.0` — 28th of November 2022](changelog/version-1.0.0.md)
13+
1014
## Development phase
1115

1216
- [`0.17.0` — 8th of November 2022](changelog/version-0.17.0.md)

‎docs/pages/project/changelog/version-1.0.0.md‎

Lines changed: 247 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,247 @@
1+
# Changelog 1.0.0 — 28th of November 2022
2+
3+
!!! info inline end "[See release on GitHub]"
4+
[See release on GitHub]: https://github.com/CuyZ/Valinor/releases/tag/1.0.0
5+
6+
First stable version! 🥳 🎉
7+
8+
This release marks the end of the initial development phase. The library has
9+
been live for [exactly one year] at this date and is stable enough to start
10+
following the [semantic versioning] — it means that any backward incompatible
11+
change (aka breaking change) will lead to a bump of the major version.
12+
13+
This is the biggest milestone achieved by this project (yet™); I want to thank
14+
everyone who has been involved to make it possible, especially the
15+
[contributors] who submitted high-quality pull requests to improve the library.
16+
17+
There is also one person that I want to thank even more: my best friend
18+
[Nathan](https://github.com/Mopolo/), who has always been so supportive with my
19+
side-projects. Thanks, bro! 🙌
20+
21+
The last year marked a bigger investment of my time in OSS contributions; I've
22+
proven to myself that I am able to follow a stable way of managing my engagement
23+
to this community, and this is why I enabled sponsorship on my profile to allow
24+
people to **❤️ [sponsor my work on GitHub]** — if you use this library in your
25+
applications, please consider offering me a 🍺 from time to time! 🤗
26+
27+
[exactly one year]: https://github.com/CuyZ/Valinor/commit/396f64a5246ccfe3f6f6d3211bac7f542a9c7fc6
28+
[semantic versioning]: https://semver.org
29+
[sponsor my work on GitHub]: https://github.com/sponsors/romm
30+
[contributors]: https://github.com/CuyZ/Valinor/graphs/contributors
31+
32+
## Notable changes
33+
34+
**End of PHP 7.4 support**
35+
36+
PHP 7.4 security support [has ended on the 28th of November
37+
2022](https://www.php.net/supported-versions.php); the minimum version supported
38+
by this library is now PHP 8.0.
39+
40+
**New mapper to map arguments of a callable**
41+
42+
This new mapper can be used to ensure a source has the right shape before
43+
calling a function/method.
44+
45+
The mapper builder can be configured the same way it would be with a tree
46+
mapper, for instance to customize the type strictness.
47+
48+
```php
49+
$someFunction = function(string $foo, int $bar): string {
50+
return "$foo / $bar";
51+
};
52+
53+
try {
54+
$arguments = (new \CuyZ\Valinor\MapperBuilder())
55+
->argumentsMapper()
56+
->mapArguments($someFunction, [
57+
'foo' => 'some value',
58+
'bar' => 42,
59+
]);
60+
61+
// some value / 42
62+
echo $someFunction(...$arguments);
63+
} catch (\CuyZ\Valinor\Mapper\MappingError $error) {
64+
// Do something…
65+
}
66+
```
67+
68+
**Support for `TimeZone` objects**
69+
70+
Native `TimeZone` objects construction is now supported with a proper error
71+
handling.
72+
73+
```php
74+
try {
75+
(new \CuyZ\Valinor\MapperBuilder())
76+
->mapper()
77+
->map(DateTimeZone::class, 'Jupiter/Europa');
78+
} catch (MappingError $exception) {
79+
$error = $exception->node()->messages()[0];
80+
81+
// Value 'Jupiter/Europa' is not a valid timezone.
82+
echo $error->toString();
83+
}
84+
```
85+
86+
**Mapping object with one property**
87+
88+
When a class needs only one value, the source given to the mapper must match the
89+
type of the single property/parameter.
90+
91+
This change aims to bring consistency on how the mapper behaves when mapping an
92+
object that needs one argument. Before this change, the source could either
93+
match the needed type, or be an array with a single entry and a key named after
94+
the argument.
95+
96+
See example below:
97+
98+
```php
99+
final class Identifier
100+
{
101+
public readonly string $value;
102+
}
103+
104+
final class SomeClass
105+
{
106+
public readonly Identifier $identifier;
107+
108+
public readonly string $description;
109+
}
110+
111+
(new \CuyZ\Valinor\MapperBuilder())->mapper()->map(SomeClass::class, [
112+
'identifier' => ['value' => 'some-identifier'], // ❌
113+
'description' => 'Lorem ipsum…',
114+
]);
115+
116+
(new \CuyZ\Valinor\MapperBuilder())->mapper()->map(SomeClass::class, [
117+
'identifier' => 'some-identifier', // ✅
118+
'description' => 'Lorem ipsum…',
119+
]);
120+
```
121+
122+
## Upgrading from 0.x to 1.0
123+
124+
As this is a major release, all deprecated features have been removed, leading
125+
to an important number of breaking changes.
126+
127+
You can click on the entries below to get advice on available replacements.
128+
129+
??? tip "Doctrine annotations support removal"
130+
131+
Doctrine annotations cannot be used anymore, [PHP attributes] must be used.
132+
133+
??? tip "`BackwardCompatibilityDateTimeConstructor` class removal"
134+
135+
You must use the method available in the mapper builder, see [dealing
136+
with dates chapter].
137+
138+
??? tip "Mapper builder `flexible` method removal"
139+
140+
The flexible has been splitted in three disctint modes, see [type strictness
141+
& flexibility chapter].
142+
143+
??? tip "Mapper builder `withCacheDir` method removal"
144+
145+
You must now register a cache instance directly, see [performance &
146+
caching chapter].
147+
148+
??? tip "`StaticMethodConstructor` class removal"
149+
150+
You must now register the constructors using the mapper builder, see [custom
151+
object constructors chapter].
152+
153+
??? tip "Mapper builder `bind` method removal"
154+
155+
You must now register the constructors using the mapper builder, see [custom
156+
object constructors chapter].
157+
158+
??? tip "`ThrowableMessage` class removal"
159+
160+
You must now use the `MessageBuilder` class, see [error handling chapter].
161+
162+
??? tip "`MessagesFlattener` class removal"
163+
164+
You must now use the `Messages` class, see [error handling chapter].
165+
166+
??? tip "`TranslatableMessage` class removal"
167+
168+
You must now use the `HasParameters` class, see [custom exception chapter].
169+
170+
??? tip "Message methods removal"
171+
172+
The following methods have been removed:
173+
174+
- `\CuyZ\Valinor\Mapper\Tree\Message\NodeMessage::name()`
175+
- `\CuyZ\Valinor\Mapper\Tree\Message\NodeMessage::path()`
176+
- `\CuyZ\Valinor\Mapper\Tree\Message\NodeMessage::type()`
177+
- `\CuyZ\Valinor\Mapper\Tree\Message\NodeMessage::value()`
178+
- `\CuyZ\Valinor\Mapper\Tree\Node::value()`
179+
180+
It is still possible to get the wanted values using the method
181+
`\CuyZ\Valinor\Mapper\Tree\Message\NodeMessage::node()`.
182+
183+
The placeholder `{original_value}` has also been removed, the same value can
184+
be fetched with `{source_value}`.
185+
186+
??? tip "`PlaceHolderMessageFormatter` class removal"
187+
188+
Other features are available to format message, see [error messages
189+
customization chapter].
190+
191+
??? tip "`Identifier` attribute removal"
192+
193+
This feature has been part of the library since its first public release,
194+
but it was never documented because it did not fit one of the library's main
195+
philosophy which is to be almost entirely decoupled from an application's
196+
domain layer.
197+
198+
The feature is entirely removed and not planned to be replaced by an
199+
alternative, unless the community really feels like there is a need for
200+
something alike.
201+
202+
[PHP attributes]: https://www.php.net/manual/en/language.attributes.overview.php
203+
[dealing with dates chapter]: ../../how-to/deal-with-dates.md
204+
[type strictness & flexibility chapter]: ../../usage/type-strictness-and-flexibility.md
205+
[performance & caching chapter]: ../../other/performance-and-caching.md
206+
[custom object constructors chapter]: ../../how-to/use-custom-object-constructors.md
207+
[error handling chapter]: ../../usage/error-handling.md
208+
[custom exception chapter]: ../../usage/error-handling.md#custom-exception-messages
209+
[error messages customization chapter]: ../../how-to/customize-error-messages.md
210+
211+
## ⚠ BREAKING CHANGES
212+
213+
* Disallow array when mapping to object with one argument ([72cba3](https://github.com/CuyZ/Valinor/commit/72cba320f582c7cda63865880a1cbf7ea292d2b1))
214+
* Mark tree mapper and arguments mapper as `@pure` ([0d9855](https://github.com/CuyZ/Valinor/commit/0d98555b8289248e84c55873bca7bca6968fc6e0))
215+
* Remove deprecated backward compatibility datetime constructor ([a65e8d](https://github.com/CuyZ/Valinor/commit/a65e8d91f65004ffefe087f4c7b024678f739e83))
216+
* Remove deprecated class `ThrowableMessage` ([d36ca9](https://github.com/CuyZ/Valinor/commit/d36ca9887e0a94d7244fba2df7aa7e24d6b11f8d))
217+
* Remove deprecated class to flatten messages ([f9ed93](https://github.com/CuyZ/Valinor/commit/f9ed93e98c09c7a6120c0911e5e5d598eb86a417))
218+
* Remove deprecated interface `TranslatableMessage` ([ceb197](https://github.com/CuyZ/Valinor/commit/ceb19729c9a683e4f477857916fcdce7256830ee))
219+
* Remove deprecated message methods ([e6557d](https://github.com/CuyZ/Valinor/commit/e6557dde5255857526c637fab2b2757030a6a413))
220+
* Remove deprecated method constructor attribute ([d76467](https://github.com/CuyZ/Valinor/commit/d76467194c43c28912e1af3d85a92308e90db64e))
221+
* Remove deprecated method to enable flexible mode ([a2bef3](https://github.com/CuyZ/Valinor/commit/a2bef3497a535dae78dfb95614aaa2947256380f))
222+
* Remove deprecated method to set cache directory ([b0d6d2](https://github.com/CuyZ/Valinor/commit/b0d6d2fc7ddb2cccc99fa182daaa2a980bde7338))
223+
* Remove deprecated method used to bind a callback ([b79ed8](https://github.com/CuyZ/Valinor/commit/b79ed81253fc8df758e935772fbd0800c3f41317))
224+
* Remove deprecated placeholder message formatter ([c2723d](https://github.com/CuyZ/Valinor/commit/c2723dac0bf8063dacd7e30b91dbe9f684addbf8))
225+
* Remove Doctrine annotations support ([66c182](https://github.com/CuyZ/Valinor/commit/66c1829fcb7b7942947fcbfb11d4b1e4d1cfea15))
226+
* Remove identifier attribute ([8a7486](https://github.com/CuyZ/Valinor/commit/8a7486aa440aa8068a43fe5b1e3731ce880b9daf))
227+
* Remove PHP 7.4 support ([5f5a50](https://github.com/CuyZ/Valinor/commit/5f5a50123be5d5e9f5ebc9ca179bef8a2d6e1a4c))
228+
* Remove support for `strict-array` type ([22c3b4](https://github.com/CuyZ/Valinor/commit/22c3b4fbaba05b05d834cd0492ede6f484b610ee))
229+
230+
## Features
231+
232+
* Add constructor for `DateTimeZone` with error support ([a0a4d6](https://github.com/CuyZ/Valinor/commit/a0a4d63d814a95874d7b7a5410d393bbd95329b7))
233+
* Introduce mapper to map arguments of a callable ([9c7e88](https://github.com/CuyZ/Valinor/commit/9c7e884f13f51842cd038faf61a71467c8d25816))
234+
235+
## Bug Fixes
236+
237+
* Allow mapping `null` to single node nullable type ([0a98ec](https://github.com/CuyZ/Valinor/commit/0a98ec25122a629bd03cd7e71e0d407cd850fb28))
238+
* Handle single argument mapper properly ([d7bf6a](https://github.com/CuyZ/Valinor/commit/d7bf6ab7a9e1e2266d3a9a4755c5042456cbb20a))
239+
* Handle tree mapper call without argument in PHPStan extension ([3f3a01](https://github.com/CuyZ/Valinor/commit/3f3a0173fa33c3796f80e317aa3fbb0d1255e8d1))
240+
* Handle tree mapper call without argument in Psalm plugin ([b425af](https://github.com/CuyZ/Valinor/commit/b425af7ae9511334a536c8ce5919d00c444fa36d))
241+
242+
## Other
243+
244+
* Activate value altering feature only when callbacks are registered ([0f33a5](https://github.com/CuyZ/Valinor/commit/0f33a5b4f34b02e8e5196d374918af60cee75438))
245+
* Bump `psr/simple-cache` supported version ([e4059a](https://github.com/CuyZ/Valinor/commit/e4059a1cc8b7b639a274d5580382090a92a4a911))
246+
* Remove `@` from comments for future PHP versions changes ([68774c](https://github.com/CuyZ/Valinor/commit/68774c778a7aed939b20314114e50b14b781968d))
247+
* Update dependencies ([4afcda](https://github.com/CuyZ/Valinor/commit/4afcda966bd2e8aae8e2c8004156b3aef9add6a7))

0 commit comments

Comments
 (0)