README

Generate modern, type-safe Data Transfer Objects (DTOs) in Laravel from clean YAML definitions — with automatic validation, nested support, and fluent collection handling.

Overview

Laravel Arc is a powerful Laravel package that simplifies Data Transfer Object (DTO) management through YAML-driven generation. Define your DTOs in simple YAML files and let Laravel Arc generate type-safe, validated PHP classes with automatic property access and comprehensive collection support.

Think of it as Laravel API Resources, but with stronger typing, automatic validation, and generated from YAML definitions.

🎯 Key Features

• 🏗️ YAML-Driven Generation - Define DTOs in clean, readable YAML
• 🔒 Type Safety - Full PHP 8.3+ type enforcement with readonly properties
• ✅ Automatic Validation - Generate Laravel validation rules from field definitions
• � ModelSchema Integration - 65+ advanced field types (geometric, JSON, enhanced validation)
• �🔄 Field Transformers - Built-in data transformation (trim, slugify, normalize, etc.)
• 📊 Export Formats - Convert to JSON, XML, CSV, YAML, and more
• 🎯 Behavioral Traits - Timestamps, UUIDs, soft deletes, and tagging
• 🚀 Modern PHP - Leverages PHP 8.3+ features and best practices

🔧 Advanced Field Types (ModelSchema Integration)

Laravel Arc integrates with grazulex/laravel-modelschema to provide 65+ advanced field types:

# Traditional Arc types
fields:
  name:
    type: string
  age:
    type: integer

# Advanced ModelSchema types  
fields:
  coordinates:
    type: point          # Geographic point
  boundary:
    type: polygon        # Geographic polygon
  metadata:
    type: json           # JSON with validation
  tags:
    type: set            # Set collection
  email:
    type: email          # Enhanced email validation
  settings:
    type: jsonb          # PostgreSQL JSONB

Supported Advanced Types:

• 🌍 Geometric: point, polygon, geometry, linestring
• 📋 JSON: json, jsonb, set, array
• 📧 Enhanced String: email, uuid, url, slug, phone
• 🔢 Numeric Variations: bigint, tinyint, decimal, money
• 📅 Date/Time: datetime, timestamp, date, time

📚 Complete Documentation

➡️ Visit the Wiki for complete documentation, examples, and guides

The wiki contains:

• Installation & Setup
• Your First DTO
• Field Types
• Field Transformers
• Artisan Commands
• Complete Examples

📦 Quick Installation

composer require grazulex/laravel-arc
php artisan vendor:publish --provider="Grazulex\LaravelArc\LaravelArcServiceProvider"

🚀 Quick Start

1. Create a DTO definition:

php artisan dto:definition-init UserDTO --model=App\\Models\\User --table=users

1. Generate the DTO class:

php artisan dto:generate user.yaml

1. Use your DTO:

$userData = ['name' => 'John Doe', 'email' => 'john@example.com'];
$userDto = UserDTO::fromArray($userData);

echo $userDto->name; // 'John Doe'
echo $userDto->toJson(); // JSON representation

⚠️ Important Notes

YAML Validation Rules with Commas

When using validation rules that contain commas (like exists:table,column), wrap them in quotes:

# ❌ Wrong - gets split into separate rules
rules: [required, exists:users,id]

# ✅ Correct - stays as one rule  
rules: [required, "exists:users,id"]

This applies to rules like: "exists:table,column", "unique:table,column", "in:value1,value2,value3", etc.

📖 Learn More

• 📚 Complete Documentation - Full guides and API reference
• 🚀 Installation & Setup - Installation and first steps
• 💡 Complete Examples - Real-world usage examples
• 🔧 Behavioral Traits - Advanced features and traits

🔧 Requirements

• PHP: ^8.3
• Laravel: ^12.19
• Carbon: ^3.10

🧪 Testing

composer test

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

🔒 Security

Please review our Security Policy for reporting vulnerabilities.

📄 License

Laravel Arc is open-sourced software licensed under the MIT license.

Made with ❤️ by Jean-Marc Strauven