Skip to content

Commit 34cded9

Browse files
hakobyansenhakobyansen
committed
Update documentation
1 parent 60dcb9a commit 34cded9

File tree

1 file changed

+176
-64
lines changed

1 file changed

+176
-64
lines changed

‎README.md‎

Lines changed: 176 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -2,92 +2,112 @@
22
[![Build Status](https://travis-ci.com/c0d3b0t/phpdto.svg?branch=master)](https://travis-ci.com/c0d3b0t/phpdto)
33
[![Total Downloads](https://poser.pugx.org/codebot/phpdto/downloads)](https://packagist.org/packages/codebot/phpdto)
44
[![License](https://poser.pugx.org/codebot/phpdto/license)](https://packagist.org/packages/codebot/phpdto)
5+
56
## About
6-
> CLI tool for PHP Data Transfer Objects generation.
77

8-
This utility gives an ability to generate PHP 7.4 DTO classes based on json pattern (schema).
8+
> A CLI tool for PHP Data Transfer Objects generation.
9+
10+
This utility gives an ability to generate PHP 8 8 DTO classes based on json pattern.
11+
912
## Installation
10-
Install the package via composer:
1113

12-
`composer require --dev codebot/phpdto 0.2.*`
14+
Install the package via composer:
15+
16+
`composer require --dev codebot/phpdto 0.3.*`
1317

14-
**Please consider that the minimum PHP version required by this package is 7.4.**
18+
**Please consider that the minimum PHP version required by this package is 8.0.**
1519

1620
## Initialization
21+
1722
`vendor/bin/phpdto init`
1823

19-
The current working directory is the directory from where you are invoking `phpdto` command.
24+
The current working directory is the directory from where you are invoking `phpdto` command.
2025

21-
This command will initialize the phpdto and create **phpdto.json** configuration file and **phpdto_patterns** directory in your current working directory.
26+
This command will initialize the phpdto and create **phpdto.json** configuration file and **phpdto_patterns** directory
27+
in your current working directory.
2228

2329
## Configuration
24-
**phpdto.json** configuration file contains following variables:
2530

26-
*PHP_DTO_PATTERNS_DIR* - the directory, where you must store json schemas for DTOs.
31+
**phpdto.json** configuration file contains following variables:
32+
33+
*PHP_DTO_PATTERNS_DIR* - the directory, where you must store json patterns for DTOs.
34+
35+
*PHP_DTO_NAMESPACE* - the namespace of generated DTO classes.
2736

28-
*PHP_DTO_NAMESPACE* - the namespace for DTO classes.
29-
30-
*PHP_DTO_CLASS_POSTFIX* - postfix of DTO classes, e.g. Item (without postfix), ItemDto (postfix is "Dto").
37+
*PHP_DTO_CLASS_POSTFIX* - postfix of DTO classes, e.g. Item (no postfix), ItemDto (the postfix is "Dto").
3138

3239
***These variables are stored as environment variables.***
3340

3441
## Usage
35-
To generate DTO class you must create a pattern, which is a json file that contains information about generated class.
3642

37-
##### DTO Pattern
43+
To generate DTO class you must create a pattern, which is a json file that contains information about the generated class.
3844

39-
An example of DTO pattern:
45+
##### DTO JSON Pattern
46+
47+
An example of DTO pattern:
4048

4149
```json
4250
{
43-
"class": "item",
44-
"namespace_postfix": "",
45-
"rules": {
46-
"id": "int",
47-
"count": "nullable|int",
48-
"name": "string",
49-
"description": "nullable|string",
50-
"is_active": "bool"
51-
}
51+
"class": "item",
52+
"namespace_postfix": "",
53+
"rules": {
54+
"id": "int",
55+
"count": "nullable|int",
56+
"name": "string",
57+
"description": "nullable|string",
58+
"is_active": "bool"
59+
}
5260
}
5361
```
5462

55-
**class**
63+
**class**
64+
65+
A class name that will be combined with *PHP_DTO_CLASS_POSTFIX* specified in `phpdto.json` config file.
5666

57-
The class name that will be combined with *PHP_DTO_CLASS_POSTFIX* specified in phpdto.json config file.
67+
So, if the class name is `item`, and the class postfix config value is `Dto`, then the generated class name will be `
68+
ItemDto`.
5869

59-
So, if the class name is "item" and the class postfix config value is "Dto", then the generated class name will be "ItemDto".
60-
61-
**namespace_postfix**
70+
**namespace_postfix**
6271

63-
The postfix of the generated DTO class namespace that will be combined with *PHP_DTO_NAMESPACE* specified in phpdto.json config file.
72+
A postfix of the generated DTO class namespace that will be combined with *PHP_DTO_NAMESPACE* specified in `phpdto.json`
73+
config file.
6474

65-
So, if the namespace postfix is **"\User"** and the default DTO namespace is **"App\Dto"**, then the generated class namespace will be `App\Dto\User`.
75+
So, if the namespace postfix is `\User`, and the default DTO namespace is `App\Dto`, then the namespace of the generated
76+
class will be `App\Dto\User`.
6677

67-
You can leave namespace postfix empty.
78+
You can leave namespace postfix empty.
6879

6980
**rules**
7081

71-
This object contains information about DTO class properties and methods. Keys will be casted to class properties. Values contain information about getters return types.
82+
This object contains information about DTO class properties and methods. Keys will be cast to class properties. Values
83+
contain information about getters return types.
7284

73-
`"description" : "nullable|string"` - due to this pair `$_description` property will be added to DTO class with appropriate `private ?string $_description` property and `getDescription(): ?string` method, that expects return type "string" and allows nullable.
85+
`"description" : "nullable|string"` - due to this pair `$_description` property will be added to DTO class with
86+
appropriate `private ?string $_description` property and `getDescription(): ?string` method, that expects return type "
87+
string" and allows nullable.
7488

7589
##### Generating DTO
7690

7791
Given you have already created pattern as json file named `item.json` in the `phpdto_patterns` folder.
7892

79-
Run `vendor/bin/phpdto -f=item` to have your DTO class generated. It will be stored under namespace specified in the `phpdto.json` config file combined with namespace postfix specified in your pattern.
93+
Run `vendor/bin/phpdto -f=item` to have your DTO class generated. It will be stored under namespace specified in
94+
the `phpdto.json` config file combined with namespace postfix specified in your pattern.
8095

81-
Given your are generating DTO class from the pattern shown in "DTO Pattern" section, then you will have following class generated.
96+
Given you are generating DTO class from the pattern shown in "DTO JSON Pattern" section, then you will have following class
97+
generated.
8298

8399
```php
84100
<?php
85101

86102
namespace App\Dto;
87103

88-
class ItemDto extends \PhpDto\Dto
104+
use PhpDto\Dto;
105+
use PhpDto\DtoSerialize;
106+
use PhpDto\ToArray;
107+
108+
class ItemDto extends Dto
89109
{
90-
use \PhpDto\DtoSerialize;
110+
use DtoSerialize, ToArray;
91111

92112
private int $_id;
93113
private ?int $_count;
@@ -97,53 +117,54 @@ class ItemDto extends \PhpDto\Dto
97117

98118
public function __construct( array $item )
99119
{
100-
$this->_id = $item['id'];
101-
$this->_count = $item['count'];
102-
$this->_name = $item['name'];
103-
$this->_description = $item['description'];
104-
$this->_isActive = $item['is_active'];
120+
$this->_id = $item['id'];
121+
$this->_count = $item['count'];
122+
$this->_name = $item['name'];
123+
$this->_description = $item['description'];
124+
$this->_isActive = $item['is_active'];
105125
}
106126

107127
public function getId(): int
108128
{
109-
return $this->_id;
129+
return $this->_id;
110130
}
111131

112132
public function getCount(): ?int
113133
{
114-
return $this->_count;
134+
return $this->_count;
115135
}
116136

117137
public function getName(): string
118138
{
119-
return $this->_name;
139+
return $this->_name;
120140
}
121141

122142
public function getDescription(): ?string
123143
{
124-
return $this->_description;
144+
return $this->_description;
125145
}
126146

127147
public function getIsActive(): bool
128148
{
129-
return $this->_isActive;
149+
return $this->_isActive;
130150
}
131151
}
132152
```
133153

134154
##### How to use
135155

136-
There are 2 mapper methods:
156+
There are 2 mapper methods:
137157

138-
`static function mapArray(array $items, bool $shouldSerialize = false): array`
158+
`static function mapArray(array $items, bool $shouldSerialize = false): array`
139159

140-
`static function mapSingle(array $item, bool $shouldSerialize = false): mixed`
160+
`static function mapSingle(array $item, bool $shouldSerialize = false): Dto|stdClass`
141161

142162
Use `mapArray` when you need to map multidimensional array, otherwise use `mapSingle`.
143163

144-
Mapping example:
164+
Mapping example:
165+
166+
###### Single
145167

146-
Given you have following `$itemData` array that contains *all* data related to item that is not necessary to pass another layer (usually it's a view).
147168
```php
148169
$itemData = [
149170
'id' => 1,
@@ -169,7 +190,7 @@ $item->getCount();
169190
$item->getIsActive();
170191
```
171192

172-
Due to the mapper above we build our DTO that contains data we need.
193+
###### Multidimensional
173194

174195
```php
175196
$itemData = [
@@ -197,11 +218,12 @@ foreach( $items as $item )
197218
}
198219
```
199220

200-
***CONSIDER REFACTORING THE CONSTRUCTOR OF GENERATED DTO CLASS DEPENDING ON THE DATA STRUCTURE OF THE ARRAY DATA YOU WANT TO MAP.***
221+
***CONSIDER REFACTORING THE CONSTRUCTOR OF GENERATED DTO CLASS DEPENDING ON THE DATA STRUCTURE OF THE ARRAY YOU
222+
WANT TO MAP.***
201223

202-
Sometimes you may want to have DTOs as objects that you could pass in AJAX response or whatever you need for.
224+
Sometimes you may want to have DTOs as objects that you could pass in AJAX response or whatever you need for.
203225

204-
Second parameter of mapper methods is a flag that decides if data should be serialized.
226+
The second parameter of the mapper methods is a flag that decides if the data should be serialized.
205227

206228
`ItemDto::mapSingle( $itemData, true )` - this will return you the DTO as a serialized object:
207229

@@ -219,13 +241,15 @@ Same is true for `mapArray` method.
219241

220242
##### DTO Faker
221243

222-
You can generate fake data for your DTOs easily using `PhpDto\Services\DtoFaker` class.
244+
You can generate fake data for your DTOs easily using `PhpDto\Services\DtoFaker` class.
223245

224246
```php
225247
$fakeData = DtoFaker::fakeSingle( ItemDto::class ); // array that contains fake data for ItemDto
226248
$item = ItemDto::mapSingle( $fakeData );
227249
```
250+
228251
Now your item looks like this:
252+
229253
```
230254
{
231255
"id": 993
@@ -235,19 +259,107 @@ Now your item looks like this:
235259
"isActive": false
236260
}
237261
```
238-
All of the values are randomly generated, even the boolean value for isActive field.
239262

240-
You can fake multidimensional array via `DtoFaker::fakeArray` method.
263+
All the values are randomly generated, even the boolean value for isActive field.
264+
265+
You can fake multidimensional array via `DtoFaker::fakeArray` method.
241266

242267
In the example below we want to fake data for 10 items.
268+
243269
```php
244270
$fakeData = DtoFaker::fakeArray( ItemDto::class, 10 );
245271
$items = ItemDto::mapArray( $fakeData );
246272
```
247-
Second parameter of the `Dto::fakeArray` method is the count of generated items.
248273

249-
`Dto::fakeSingle` and `Dto::fakeArray` methods are using PHP Reflection API to get information about properties and getters.
274+
Second parameter of the `Dto::fakeArray` method is the count of generated items.
275+
276+
`Dto::fakeSingle` and `Dto::fakeArray` methods are using PHP Reflection API to get information about properties and
277+
getters.
250278

251-
Alternatively you can use `Dto::fakeSingeFromPattern` and `Dto::fakeArrayFromPattern` methods.
252-
You must pass them full path to your json pattern:
279+
Alternatively you can use `Dto::fakeSingeFromPattern` and `Dto::fakeArrayFromPattern` methods. You must pass them full
280+
path to your json pattern:
253281
`Dto::fakeArrayFromPattern('/full/path/to/pattern.json')`.
282+
283+
###### `ToArray` trait and `toArray(): array` method.
284+
285+
When you need to cast your DTO object to array, you can use the `toArray` method.
286+
287+
```php
288+
<?php
289+
290+
namespace App\Dto;
291+
292+
use PhpDto\Dto;
293+
use PhpDto\ToArray;
294+
295+
class MockDto extends Dto
296+
{
297+
use ToArray;
298+
299+
private ?string $_name;
300+
private int $_count;
301+
private bool $_isTrue;
302+
303+
public function __construct( array $data )
304+
{
305+
$this->_name = $data['name'];
306+
$this->_count = $data['count'];
307+
$this->_isTrue = $data['is_true'];
308+
}
309+
310+
public function getName(): ?string
311+
{
312+
return $this->_name;
313+
}
314+
315+
public function getCount(): int
316+
{
317+
return $this->_count;
318+
}
319+
320+
public function getIsTrue(): bool
321+
{
322+
return $this->_isTrue;
323+
}
324+
}
325+
326+
$mockData = [
327+
'name' => 'Mock name',
328+
'count' => 4,
329+
'is_true' => true
330+
];
331+
332+
$dto = new MockDto($mockData);
333+
334+
$arr = $dto->toArray();
335+
336+
var_dump($arr);
337+
```
338+
339+
The output will be:
340+
```
341+
array(3) {
342+
'name' =>
343+
string(9) "Mock name"
344+
'count' =>
345+
int(4)
346+
'is_true' =>
347+
bool(true)
348+
}
349+
```
350+
351+
Though, if you want to keep array keys format to be same as class fields, you can pass false to `toArray` method:
352+
`$arr = $dto->toArray(false);` or `$arr = $dto->toArray(toSnakeCase: false);`
353+
354+
The output then will be:
355+
```
356+
array(3) {
357+
'name' =>
358+
string(9) "Mock name"
359+
'count' =>
360+
int(4)
361+
'isTrue' =>
362+
bool(true)
363+
}
364+
```
365+
So, now the `isTrue` key is camelCase.

0 commit comments

Comments
 (0)