Skip to content

Commit 400d108

Browse files
tuxonicetuxonice
committed
[DTO-13] Update documentation
1 parent f4dbd6e commit 400d108

File tree

5 files changed

+215
-1
lines changed

5 files changed

+215
-1
lines changed

‎README.md‎

Lines changed: 139 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,15 @@
22

33
![Tests](https://github.com/tuxonice/data-transfer-object/actions/workflows/pipeline.yml/badge.svg)
44

5+
In the ever-evolving landscape of software development, efficient and structured data communication is paramount.
6+
DTO package is designed to streamline and enhance the way data is transferred between different layers of your
7+
application,
8+
promoting clarity, maintainability, and robustness.
9+
10+
Whether you're building a RESTful API, a microservices architecture, or a traditional web application,
11+
Data Transfer Objects package empowers you to manage data flow with elegance and precision.
12+
Elevate your code quality and simplify your data handling processes with our intuitive and developer-friendly DTO
13+
solution.
514

615
## Installation
716

@@ -13,7 +22,7 @@ composer require tuxonice/data-transfer-object
1322

1423
## Setup
1524

16-
The goal of this package is to create data transfer objects from json definitions as easy as possible.
25+
The goal of this package is to create data transfer objects from json definitions as easy as possible.
1726

1827
1. In your project create a folder to hold on the definition files.
1928

@@ -61,6 +70,7 @@ class GenerateTransferCommand extends Command
6170
}
6271
}
6372
```
73+
6474
4. For Laravel projects:
6575

6676
```bash
@@ -289,7 +299,135 @@ class CustomerTransfer extends AbstractTransfer
289299

290300
```
291301

302+
6. Create definition file(s)
303+
304+
You can define one or more transfer objects definitions for each json file.
305+
Start by creating a json object that will contain your definitions:
306+
307+
```json
308+
{
309+
"transfers": [
310+
]
311+
}
312+
```
313+
314+
and inside the transfers array define your transfer:
315+
316+
```json
317+
{
318+
"name": "Customer",
319+
"properties": [
320+
{
321+
"name": "firstName",
322+
"type": "string"
323+
},
324+
{
325+
"name": "lastName",
326+
"type": "string"
327+
},
328+
{
329+
"name": "isActive",
330+
"type": "bool"
331+
}
332+
]
333+
}
334+
```
335+
336+
- transfer class
337+
338+
| field | type | required | Description |
339+
|------------------------|--------|----------|-----------------------------------------------------------------------------------------------------------------------|
340+
| name | string | yes | The transfer object name. The result class name will be this name concatenated with "Transfer". E.g. CustomerTransfer |
341+
| properties | array | yes | An array of objects with definition of each class property |
342+
| deprecationDescription | string | no | If present and not empty, will add an annotation with @deprecated, to mark this class as deprecated |
343+
344+
- class properties
345+
346+
| field | type | required | Description |
347+
|------------------------|--------|----------------------------------|-------------------------------------------------------------------------------------------------------|
348+
| name | string | yes | field name in camelCase |
349+
| type | string | yes | The field type. Can be a native type (string, int, float, bool), or any other class |
350+
| deprecationDescription | string | no | If present and with a text, will add an annotation with @deprecated, to mark this field as deprecated |
351+
| nullable | bool | no | Set if the property can be null |
352+
| namespace | string | yes if the type is another class | Namespace for the class in case the property type is another class |
353+
| singular | string | yes if the type is an array | Singular form of the property if the type is an array |
354+
355+
## Example of property definitions
356+
357+
- integer
358+
```
359+
...
360+
{
361+
"name": "id",
362+
"type": "int"
363+
}
364+
...
365+
```
366+
367+
- nullable string
368+
```
369+
...
370+
{
371+
"name": "firstName",
372+
"type": "string",
373+
"nullable": true
374+
}
375+
...
376+
```
377+
378+
- another transfer object as property
379+
```
380+
...
381+
{
382+
"name": "customer",
383+
"type": "CustomerTransfer"
384+
}
385+
...
386+
```
292387

388+
- DateTime property
389+
```
390+
...
391+
{
392+
"name": "createdAt",
393+
"type": "DateTime",
394+
"namespace": "DateTime"
395+
}
396+
...
397+
```
398+
399+
- Array of strings
400+
```
401+
...
402+
{
403+
"name": "tags",
404+
"type": "string[]",
405+
"singular": "tag"
406+
}
407+
...
408+
```
409+
410+
- Array of transfer objects
411+
```
412+
...
413+
{
414+
"name": "categories",
415+
"type": "CategoryTransfer[]",
416+
"singular": "category"
417+
},
418+
...
419+
```
420+
421+
- Symfony Response
422+
```
423+
...
424+
{
425+
"name": "response",
426+
"type": "Response",
427+
"namespace": "\\Symfony\\Component\\HttpFoundation\\Response"
428+
},
429+
...
430+
```
293431

294432
## License
295433

‎tests/Data/sample.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"transfers": [
3+
{
4+
"name": "Sample",
5+
"properties": [
6+
{
7+
"name": "response",
8+
"type": "Response",
9+
"namespace": "\\Symfony\\Component\\HttpFoundation\\Response"
10+
}
11+
]
12+
}
13+
]
14+
}

‎tests/Expected/SampleTransfer.php‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
<?php
2+
3+
namespace Tlab\Tests\Generated;
4+
5+
use Symfony\Component\HttpFoundation\Response;
6+
use Tlab\TransferObjects\AbstractTransfer;
7+
8+
/**
9+
* !!! THIS TRANSFER CLASS FILE IS AUTO-GENERATED, CHANGES WILL BREAK YOUR PROJECT
10+
* !!! DO NOT CHANGE ANYTHING IN THIS FILE
11+
*/
12+
class SampleTransfer extends AbstractTransfer
13+
{
14+
/**
15+
* @var Response
16+
*/
17+
private Response $response;
18+
19+
/**
20+
* @return Response
21+
*/
22+
public function getResponse(): Response
23+
{
24+
return $this->response;
25+
}
26+
27+
/**
28+
* @param Response $response
29+
*
30+
* @return $this
31+
*/
32+
public function setResponse(Response $response): self
33+
{
34+
$this->response = $response;
35+
36+
return $this;
37+
}
38+
39+
}

‎tests/Unit/DataTransferBuilderTest.php‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,10 @@ public function testBuildTransfer(): void
4141
self::assertFileEquals($expectedFiles[1], $generatedFiles[1]);
4242
self::assertFileEquals($expectedFiles[2], $generatedFiles[2]);
4343
self::assertFileEquals($expectedFiles[3], $generatedFiles[3]);
44+
self::assertFileEquals($expectedFiles[4], $generatedFiles[4]);
45+
self::assertFileEquals($expectedFiles[5], $generatedFiles[5]);
46+
self::assertFileEquals($expectedFiles[6], $generatedFiles[6]);
47+
self::assertFileEquals($expectedFiles[7], $generatedFiles[7]);
4448
}
4549

4650
public function testCanExportTransferClassToArray(): void

‎tests/Unit/DefinitionProviderTest.php‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -275,6 +275,25 @@ public function testProvide(): void
275275
],
276276
]
277277
],
278+
[
279+
'namespace' => 'TestNamespace',
280+
'className' => 'SampleTransfer',
281+
'abstractClass' => 'AbstractTransfer',
282+
'deprecationDescription' => null,
283+
'useNamespaces' => [
284+
'Symfony\Component\HttpFoundation\Response',
285+
'Tlab\TransferObjects\AbstractTransfer'
286+
],
287+
'properties' => [
288+
[
289+
'type' => 'Response',
290+
'camelCaseName' => 'response',
291+
'namespace' => 'Symfony\Component\HttpFoundation\Response',
292+
'nullable' => false,
293+
'deprecationDescription' => null,
294+
]
295+
],
296+
],
278297
], $definitionProvider->provide());
279298
}
280299
}

0 commit comments

Comments
 (0)