Skip to content

Commit 4ef75c9

Browse files
committed
Add documentation for NameMapper attribute
Introduce a new `NameMapper.md` file explaining the usage of the `MapName` attribute for handling property name mapping and letter case transformations. Update cross-references in `PropertyAttributes.md` and `Quickstart.md` to include this new documentation.
1 parent 95fa678 commit 4ef75c9

File tree

3 files changed

+42
-0
lines changed

3 files changed

+42
-0
lines changed

docs/NameMapper.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
Name Mapper
2+
=
3+
4+
Sometimes we could be expecting payload with different letter case or different naming convention.
5+
In such cases, we can use the `NameMapper` attribute to map the property to the correct key in the data array.
6+
7+
```php
8+
use Nuxtifyts\PhpDto\Data;
9+
use Nuxtifyts\PhpDto\Attributes\Class\MapName;
10+
use Nuxtifyts\PhpDto\Enums\LetterCase;
11+
12+
#[MapName(from: [LetterCase::KEBAB, LetterCase::SNAKE])]
13+
final readonly class UserData extends Data
14+
{
15+
public function __construct(
16+
public string $firstName,
17+
public string $lastName
18+
) {}
19+
}
20+
```
21+
22+
In the above example, passed data with keys `letter_case` and `letter-case` will be mapped to `letterCase` (By default),
23+
and all of these keys will be transformed to the selected letter case.
24+
25+
```php
26+
$user = UserData::from([ 'first-name' => 'John', 'last_name': 'Doe' ]);
27+
```
28+
29+
> **Note:** The `MapName` attribute is applied on every key in the data array.
30+
31+
`MapName` attribute accepts these params:
32+
33+
| Param | Type | Description | Default |
34+
|--------|----------------------------------|----------------------------------|-------------------|
35+
| `from` | `LetterCase`\|`list<LetterCase>` | List of letter cases to map from | - |
36+
| `to` | `LetterCase` | Letter case to map to | LetterCase::CAMEL |

docs/PropertyAttributes.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,11 @@ final readonly class PersonData extends Data
8080

8181
This will make it possible to hydrate properties from multiple array keys.
8282

83+
> **Note:** Sometimes, we may want to apply the `Aliases` attribute to the whole class,
84+
> in case we want to transform letter cases of all the keys in data array.
85+
> In such cases, we can use the [MapName](https://github.com/nuxtifyts/php-dto/blob/main/docs/NameMapper.md)
86+
> attribute.
87+
8388
CipherTarget
8489
-
8590

docs/Quickstart.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,7 @@ can be found here:
7878
- [Supported Types](https://github.com/nuxtifyts/php-dto/blob/main/docs/SupportedTypes.md)
7979
- [Normalizers](https://github.com/nuxtifyts/php-dto/blob/main/docs/Normalizers.md)
8080
- [Property Attributes](https://github.com/nuxtifyts/php-dto/blob/main/docs/PropertyAttributes.md)
81+
- [Name Mapper](https://github.com/nuxtifyts/php-dto/blob/main/docs/NameMapper.md)
8182
- [Data Refiners](https://github.com/nuxtifyts/php-dto/blob/main/docs/DataRefiners.md)
8283
- [Empty Data](https://github.com/nuxtifyts/php-dto/blob/main/docs/EmptyData.md)
8384
- [Cloneable Data](https://github.com/nuxtifyts/php-dto/blob/main/docs/CloneableData.md)

0 commit comments

Comments
 (0)