Quick Start - Grazulex/laravel-arc GitHub Wiki

🚀 Quick Start Guide

Get up and running with Laravel Arc in just 5 minutes! This guide will walk you through installation, creating your first DTO, and using it in your Laravel application.

📦 1. Installation

Requirements

  • PHP 8.3+
  • Laravel 12+
  • Composer

Install via Composer

composer require grazulex/laravel-arc

That's it! Laravel Arc will auto-register its service provider.

🎯 2. Create Your First DTO

Option A: Manual Creation

Create a new DTO class anywhere in your application:

<?php

namespace App\Data;

use Grazulex\Arc\LaravelArcDTO;
use Grazulex\Arc\Attributes\Property;

class UserDTO extends LaravelArcDTO
{
    #[Property(type: 'string', required: true, validation: 'max:255')]
    public string $name;

    #[Property(type: 'string', required: true, validation: 'email')]
    public string $email;

    #[Property(type: 'int', required: true, validation: 'min:0|max:150')]
    public int $age;

    #[Property(type: 'string', required: false, default: 'user')]
    public string $role;
}

Option B: Artisan Command (Recommended)

Use the built-in Artisan command for automatic generation:

# Basic DTO generation
php artisan make:dto User

# Generate from existing model (with intelligent type detection)
php artisan make:dto User --model=User

# Custom path
php artisan make:dto User --path=app/Data

🎨 3. Use Your DTO

Basic Usage

use App\Data\UserDTO;

// Create DTO with automatic validation
$user = new UserDTO([
    'name' => 'John Doe',
    'email' => '[email protected]',
    'age' => 30
    // 'role' will use default value 'user'
]);

// Direct property access - no getters/setters needed!
echo $user->name;     // "John Doe"
echo $user->email;    // "[email protected]"
echo $user->age;      // 30
echo $user->role;     // "user" (default)

Direct Property Assignment

// Modify properties directly with automatic type validation
$user->name = 'Jane Doe';
$user->age = 25;
$user->role = 'admin';

// Invalid assignment will throw TypeValidationException
// $user->age = 'not a number'; // ❌ Throws exception

Array and JSON Conversion

// Convert to array
$array = $user->toArray();
// [
//     'name' => 'Jane Doe',
//     'email' => '[email protected]',
//     'age' => 25,
//     'role' => 'admin'
// ]

// Convert to JSON
$json = $user->toJson();
// {"name":"Jane Doe","email":"[email protected]","age":25,"role":"admin"}

// Create from JSON
$userFromJson = new UserDTO(json_decode($json, true));

✅ 4. Automatic Validation

Laravel Arc automatically generates validation rules from your Property attributes:

// Get validation rules
$rules = UserDTO::rules();
// Result:
// [
//     'name' => 'required|string|max:255',
//     'email' => 'required|string|email',
//     'age' => 'required|integer|min:0|max:150',
//     'role' => 'nullable|string'
// ]

// Use in Laravel controllers
class UserController extends Controller
{
    public function store(Request $request)
    {
        // Validate using DTO rules
        $validated = $request->validate(UserDTO::rules());
        
        // Create DTO with validated data
        $userDTO = new UserDTO($validated);
        
        // Use DTO in your business logic
        return $this->userService->createUser($userDTO);
    }
}

🎆 5. Advanced Example

Let's create a more complex DTO with enums and nested DTOs:

// Define an enum
enum UserStatus: string
{
    case ACTIVE = 'active';
    case INACTIVE = 'inactive';
    case PENDING = 'pending';
}

// Address DTO
class AddressDTO extends LaravelArcDTO
{
    #[Property(type: 'string', required: true)]
    public string $street;

    #[Property(type: 'string', required: true)]
    public string $city;

    #[Property(type: 'string', required: true, validation: 'size:2')]
    public string $country_code;
}

// Enhanced User DTO
class UserDTO extends LaravelArcDTO
{
    #[Property(type: 'string', required: true, validation: 'max:255')]
    public string $name;

    #[Property(type: 'string', required: true, validation: 'email')]
    public string $email;

    #[Property(type: 'enum', class: UserStatus::class, default: UserStatus::PENDING)]
    public UserStatus $status;

    #[Property(type: 'nested', class: AddressDTO::class, required: false)]
    public ?AddressDTO $address;

    #[Property(type: 'date', required: false, format: 'Y-m-d')]
    public ?Carbon $birth_date;
}

// Usage
$user = new UserDTO([
    'name' => 'John Doe',
    'email' => '[email protected]',
    'status' => 'active',  // Automatically converted to UserStatus::ACTIVE
    'address' => [
        'street' => '123 Main St',
        'city' => 'Brussels',
        'country_code' => 'BE'
    ],
    'birth_date' => '1990-05-15'  // Automatically converted to Carbon
]);

// Access nested properties
echo $user->address->city;           // "Brussels"
echo $user->status->value;           // "active"
echo $user->birth_date->format('d/m/Y'); // "15/05/1990"

🔧 6. Debug Your DTOs

Laravel Arc includes powerful debugging tools:

# Analyze DTO structure
php artisan dto:analyze UserDTO

# Validate data against DTO
php artisan dto:validate UserDTO --data='{"name":"John","email":"[email protected]"}'

# Interactive validation
php artisan dto:validate UserDTO

🎉 Congratulations!

You've successfully created and used your first Laravel Arc DTO!

📚 What's Next?

🤔 Need Help?

⬅️ Back to: Home | ➡️ Next: Property Attributes