# 🎯 Your First DTO

Create your first Laravel Arc DTO in just 5 minutes. This guide walks you through the complete process from YAML definition to using your generated DTO.

## The YAML → DTO Journey

Laravel Arc follows a simple flow:

```
1. Write YAML Definition → 2. Generate DTO → 3. Use in Your Code
```

Let's build a **User DTO** step by step.

## Step 1: Create the YAML Definition

Create `resources/arc/user.yaml` using a real-world example:

```yaml
# Simple user DTO example with modern trait-based system
header:
  dto: UserDTO
  table: users
  model: App\Models\User
  namespace: App\DTO
  traits:
    - HasUuid
    - HasTimestamps
  use:
    - App\DTO\ProfileDTO
  extends: BaseDTO

fields:
  name:
    type: string
    required: true
    validation: [required, string, min:2, max:100]
    transformers: [trim, title_case]
  
  email:
    type: string
    required: true
    validation: [required, email, unique:users]
    transformers: [trim, lowercase]
  
  email_verified_at:
    type: datetime
    required: false
    validation: [nullable, date]
  
  # Profile as nested DTO
  profile:
    type: dto
    dto: ProfileDTO
    required: false

relations:
  posts:
    type: hasMany
    target: App\Models\Post
  
  roles:
    type: belongsToMany
    target: App\Models\Role

# The HasUuid trait automatically adds:
# - id field (UUID type)
# - UUID validation and generation methods

# The HasTimestamps trait automatically adds:
# - created_at and updated_at fields
# - touch() method for updating timestamps
# - wasRecentlyCreated() method
```

### Understanding the Real YAML Structure

- **`header`**: Contains metadata about the DTO including traits and inheritance
- **`fields`**: Defines properties with validation and transformers
- **`relations`**: Defines Eloquent relationships
- **`traits`**: Behavioral traits that add automatic functionality
- **`transformers`**: Automatic data cleaning (trim, title_case, lowercase)

## Step 2: Generate the DTO

Run the generation command:

```bash
php artisan arc:generate resources/arc/user.yaml
```

You should see output like:
```
✅ DTO generated successfully: App\DTOs\UserDto
📁 File created: app/DTOs/UserDto.php
```

## Step 3: Examine the Generated Code

Laravel Arc generates a modern PHP class at `app/DTOs/UserDto.php`:

```php
<?php

declare(strict_types=1);

namespace App\DTOs;

use Grazulex\LaravelArc\Support\Traits\ValidatesData;
use Grazulex\LaravelArc\Support\Traits\ConvertsData;

final readonly class UserDto
{
    use ValidatesData, ConvertsData;

    public function __construct(
        public string $name,
        public string $email,
        public ?\DateTime $email_verified_at = null,
        public ?ProfileDTO $profile = null,
    ) {}

    public static function validationRules(): array
    {
        return [
            'name' => ['required', 'string', 'min:2', 'max:100'],
            'email' => ['required', 'email', 'unique:users,email'],
            'email_verified_at' => ['nullable', 'date'],
        ];
    }
}
```

### Key Features Generated

✅ **Readonly Properties**: Immutable data objects  
✅ **Type Safety**: Full PHP typing  
✅ **Validation Rules**: Automatic Laravel validation  
✅ **Default Values**: Built-in defaults  
✅ **Helper Traits**: Data conversion and validation methods  

## Step 4: Use Your DTO

Now you can use your DTO in various ways:

### Creating DTOs

```php
use App\DTOs\UserDto;

// From array (most common)
$user = UserDto::from([
    'name' => 'John Doe',
    'email' => 'john@example.com',
    'age' => 30
]);

// With validation
$user = UserDto::fromValidated([
    'name' => 'John Doe',
    'email' => 'john@example.com',
    'age' => 30
]);

// From request (in controllers)
$user = UserDto::fromRequest($request);
```

### Accessing Data

```php
// Direct property access
echo $user->name;      // "John Doe"
echo $user->email;     // "john@example.com"
echo $user->age;       // 30
echo $user->status;    // "active" (default value)
```

### Converting Data

```php
// To array
$array = $user->toArray();

// To JSON
$json = $user->toJson();

// To specific format
$xml = $user->toXml();
$csv = $user->toCsv();
```

## Step 5: Use in a Laravel Controller

Here's a practical example in a controller:

```php
<?php

namespace App\Http\Controllers;

use App\DTOs\UserDto;
use Illuminate\Http\Request;

class UserController extends Controller
{
    public function store(Request $request)
    {
        // Create and validate DTO from request
        $userDto = UserDto::fromValidated($request->all());
        
        // Use the DTO data
        $user = User::create([
            'name' => $userDto->name,
            'email' => $userDto->email,
            'age' => $userDto->age,
            'status' => $userDto->status,
        ]);
        
        // Return JSON response
        return response()->json([
            'user' => $userDto->toArray(),
            'created' => true
        ]);
    }
    
    public function show(User $user)
    {
        // Convert model to DTO
        $userDto = UserDto::from($user->toArray());
        
        return response()->json($userDto->toArray());
    }
}
```

## Step 6: Add More Complexity

Let's enhance our YAML with more advanced features:

```yaml
header:
  class: UserDto
  namespace: App\DTOs
  traits: ["HasTimestamps", "HasUuid"]  # Behavioral traits

fields:
  # Field with transformer
  name:
    type: string
    required: true
    max_length: 255
    transformers: ["trim", "title_case"]
    
  # Field with custom validation
  email:
    type: email
    required: true
    unique: true
    transformers: ["trim", "lowercase"]
    
  # Nested object
  address:
    type: object
    class: AddressDto
    required: false
    
  # Array of objects
  tags:
    type: array
    items:
      type: string
    transformers: ["trim", "lowercase"]
```

## Common Patterns

### 1. API Request DTOs
```yaml
header:
  class: CreateUserRequestDto
  namespace: App\DTOs\Requests

fields:
  name: { type: string, required: true, max_length: 255 }
  email: { type: email, required: true }
  password: { type: string, required: true, min_length: 8 }
```

### 2. API Response DTOs
```yaml
header:
  class: UserResponseDto
  namespace: App\DTOs\Responses

fields:
  id: { type: integer, required: true }
  name: { type: string, required: true }
  email: { type: email, required: true }
  created_at: { type: datetime, required: true }
```

### 3. Configuration DTOs
```yaml
header:
  class: AppConfigDto
  namespace: App\DTOs\Config

fields:
  app_name: { type: string, default: "My App" }
  debug: { type: boolean, default: false }
  cache_ttl: { type: integer, default: 3600 }
```

## What You've Learned

✅ How to write YAML definitions  
✅ How to generate DTOs with Arc  
✅ How to use generated DTOs in your code  
✅ How to integrate DTOs with Laravel features  
✅ Common DTO patterns and use cases  

## What's Next?

Now that you've created your first DTO, explore more advanced features:

- **[Understanding YAML Structure](Understanding-YAML-Structure.md)** - Deep dive into YAML schema
- **[Field Types](Field-Types.md)** - Explore all 65+ field types
- **[Field Transformers](Field-Transformers.md)** - Automatic data transformation
- **[Behavioral Traits](Behavioral-Traits.md)** - Add timestamps, UUIDs, and more
- **[API Integration Example](Example-API-Integration.md)** - Real-world usage examples

---

*🎉 Congratulations! You've created your first Laravel Arc DTO. The journey from YAML to type-safe code is that simple!*