Skip to content

Commit 42999bd

Browse files
dereuromarkdereuromark
committed
Add documentation
1 parent 36cdb07 commit 42999bd

File tree

3 files changed

+334
-0
lines changed

3 files changed

+334
-0
lines changed

‎docs/Configuration.md‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# Configuration
2+
3+
## Package Configuration
4+
5+
After publishing the config file with:
6+
7+
```bash
8+
php artisan vendor:publish --provider="PhpCollective\LaravelDto\DtoServiceProvider"
9+
```
10+
11+
You'll have `config/dto.php`:
12+
13+
```php
14+
return [
15+
/*
16+
|--------------------------------------------------------------------------
17+
| DTO Configuration Path
18+
|--------------------------------------------------------------------------
19+
|
20+
| The path where your DTO configuration files are located.
21+
| Supports dto.php, dto.xml, dto.yml, or dto.yaml
22+
|
23+
*/
24+
'config_path' => config_path(),
25+
26+
/*
27+
|--------------------------------------------------------------------------
28+
| DTO Output Path
29+
|--------------------------------------------------------------------------
30+
|
31+
| The path where generated DTO classes will be written.
32+
|
33+
*/
34+
'output_path' => app_path('Dto'),
35+
36+
/*
37+
|--------------------------------------------------------------------------
38+
| DTO Namespace
39+
|--------------------------------------------------------------------------
40+
|
41+
| The namespace for generated DTO classes.
42+
|
43+
*/
44+
'namespace' => 'App\\Dto',
45+
];
46+
```
47+
48+
## DTO Definition Formats
49+
50+
### XML Format
51+
52+
Create `config/dto.xml` or `config/dtos.xml`:
53+
54+
```xml
55+
<?xml version="1.0" encoding="UTF-8"?>
56+
<dtos xmlns="php-collective-dto">
57+
<dto name="User">
58+
<field name="id" type="int"/>
59+
<field name="name" type="string"/>
60+
<field name="email" type="string" nullable="true"/>
61+
<field name="roles" type="Role[]"/>
62+
</dto>
63+
64+
<dto name="Role">
65+
<field name="id" type="int"/>
66+
<field name="name" type="string"/>
67+
</dto>
68+
</dtos>
69+
```
70+
71+
### YAML Format
72+
73+
Create `config/dto.yml` or `config/dto.yaml`:
74+
75+
```yaml
76+
User:
77+
fields:
78+
id: int
79+
name: string
80+
email: string?
81+
roles: Role[]
82+
83+
Role:
84+
fields:
85+
id: int
86+
name: string
87+
```
88+
89+
### PHP Format
90+
91+
Create `config/dtos.php` (use `dtos.php` to avoid conflict with package config):
92+
93+
```php
94+
use PhpCollective\Dto\Builder\Dto;
95+
use PhpCollective\Dto\Builder\Field;
96+
use PhpCollective\Dto\Builder\Schema;
97+
98+
return Schema::create()
99+
->dto(Dto::create('User')->fields(
100+
Field::int('id'),
101+
Field::string('name'),
102+
Field::string('email')->nullable(),
103+
Field::array('roles', 'Role'),
104+
))
105+
->dto(Dto::create('Role')->fields(
106+
Field::int('id'),
107+
Field::string('name'),
108+
))
109+
->toArray();
110+
```
111+
112+
## Command Options
113+
114+
The `dto:generate` command supports:
115+
116+
```bash
117+
# Preview changes without writing
118+
php artisan dto:generate --dry-run
119+
120+
# Verbose output
121+
php artisan dto:generate -v
122+
123+
# Both
124+
php artisan dto:generate --dry-run -v
125+
```
126+
127+
## Directory Structure
128+
129+
Recommended structure:
130+
131+
```
132+
app/
133+
├── Dto/
134+
│ ├── UserDto.php # Generated
135+
│ └── RoleDto.php # Generated
136+
config/
137+
├── dto.php # Package config
138+
└── dtos.xml # DTO definitions
139+
```
140+
141+
## Multiple Config Files
142+
143+
You can organize DTOs in a subdirectory:
144+
145+
```
146+
config/
147+
└── dto/
148+
├── user.xml
149+
├── order.xml
150+
└── product.xml
151+
```
152+
153+
Update config:
154+
155+
```php
156+
'config_path' => config_path('dto'),
157+
```
158+
159+
## Further Reading
160+
161+
See the main [php-collective/dto documentation](https://github.com/php-collective/dto) for complete configuration options.

‎docs/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Documentation
2+
3+
- [Configuration](Configuration.md) - Package and DTO configuration options
4+
- [Usage](Usage.md) - Usage patterns and examples
5+
6+
## Main Library Documentation
7+
8+
For complete documentation on the core DTO library, see [php-collective/dto](https://github.com/php-collective/dto).

‎docs/Usage.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# Usage Guide
2+
3+
## Controller Integration
4+
5+
### From Request Data
6+
7+
```php
8+
use App\Dto\UserDto;
9+
use Illuminate\Http\Request;
10+
11+
class UserController extends Controller
12+
{
13+
public function store(Request $request): JsonResponse
14+
{
15+
// From validated request
16+
$dto = new UserDto($request->validated());
17+
18+
// Or with ignoreMissing for partial updates
19+
$dto = UserDto::createFromArray($request->all(), ignoreMissing: true);
20+
21+
return response()->json($dto->toArray());
22+
}
23+
}
24+
```
25+
26+
### From Eloquent Models
27+
28+
```php
29+
public function show(int $id): JsonResponse
30+
{
31+
$user = User::findOrFail($id);
32+
$dto = new UserDto($user->toArray());
33+
34+
return response()->json($dto);
35+
}
36+
```
37+
38+
## Collection Factory
39+
40+
The service provider automatically configures Laravel collections for DTO collection fields:
41+
42+
```php
43+
// In your DTO with collection fields
44+
$activeRoles = $dto->getRoles()->filter(fn ($role) => $role->isActive());
45+
$roleNames = $dto->getRoles()->pluck('name');
46+
```
47+
48+
## Validation
49+
50+
Validate DTOs using Laravel's validator:
51+
52+
```php
53+
use Illuminate\Support\Facades\Validator;
54+
55+
$dto = new UserDto($request->all(), ignoreMissing: true);
56+
57+
$validator = Validator::make($dto->toArray(), [
58+
'name' => 'required|string|max:255',
59+
'email' => 'required|email|unique:users',
60+
]);
61+
62+
if ($validator->fails()) {
63+
return response()->json(['errors' => $validator->errors()], 422);
64+
}
65+
```
66+
67+
## Form Requests
68+
69+
Combine with Form Requests for clean validation:
70+
71+
```php
72+
// app/Http/Requests/StoreUserRequest.php
73+
class StoreUserRequest extends FormRequest
74+
{
75+
public function rules(): array
76+
{
77+
return [
78+
'name' => 'required|string|max:255',
79+
'email' => 'required|email|unique:users',
80+
];
81+
}
82+
83+
public function toDto(): UserDto
84+
{
85+
return new UserDto($this->validated());
86+
}
87+
}
88+
89+
// In controller
90+
public function store(StoreUserRequest $request): JsonResponse
91+
{
92+
$dto = $request->toDto();
93+
// ...
94+
}
95+
```
96+
97+
## API Resources
98+
99+
Use DTOs with API Resources:
100+
101+
```php
102+
// app/Http/Resources/UserResource.php
103+
class UserResource extends JsonResource
104+
{
105+
public function toArray($request): array
106+
{
107+
$dto = new UserDto($this->resource->toArray());
108+
return $dto->toArray();
109+
}
110+
}
111+
```
112+
113+
## Service Layer Pattern
114+
115+
```php
116+
// app/Services/UserService.php
117+
class UserService
118+
{
119+
public function createUser(UserDto $dto): User
120+
{
121+
return User::create($dto->toArray());
122+
}
123+
124+
public function updateUser(User $user, UserDto $dto): User
125+
{
126+
$user->update($dto->toArray());
127+
return $user->fresh();
128+
}
129+
}
130+
```
131+
132+
## Nested DTOs
133+
134+
When your DTO has nested DTO fields:
135+
136+
```php
137+
// config/dtos.xml
138+
<dto name="Order">
139+
<field name="id" type="int"/>
140+
<field name="customer" type="Customer"/>
141+
<field name="items" type="OrderItem[]"/>
142+
</dto>
143+
144+
// Usage
145+
$order = new OrderDto([
146+
'id' => 1,
147+
'customer' => ['name' => 'John', 'email' => 'john@example.com'],
148+
'items' => [
149+
['product' => 'Widget', 'quantity' => 2],
150+
['product' => 'Gadget', 'quantity' => 1],
151+
],
152+
]);
153+
154+
// Access nested data
155+
$customerName = $order->getCustomer()->getName();
156+
$totalItems = $order->getItems()->count();
157+
```
158+
159+
## Further Reading
160+
161+
See the main [php-collective/dto documentation](https://github.com/php-collective/dto) for:
162+
- DTO configuration options
163+
- Type support
164+
- Custom casters
165+
- Advanced patterns

0 commit comments

Comments
 (0)