# 📝 Understanding YAML Structure The heart of Laravel Arc is the YAML definition file. This page explains the complete YAML schema and how it translates to powerful PHP DTOs. ## The YAML → PHP Flow ``` YAML Definition → Laravel Arc Parser → Generated DTO Class ↓ ↓ ↓ Schema Rules → Code Generation → Type-Safe PHP ``` Understanding this flow is key to mastering Laravel Arc. ## Complete YAML Schema Here's the full structure of a Laravel Arc YAML file: ```yaml # Header section - Defines the class metadata header: class: UserDto # Generated class name namespace: App\DTOs # PHP namespace description: "User DTO" # Class documentation extends: BaseDto # Optional parent class implements: [UserInterface] # Optional interfaces traits: [HasTimestamps, HasUuid] # Behavioral traits # Fields section - Defines all properties fields: field_name: type: string # Field type (required) required: true # Validation rule default: "value" # Default value description: "Field docs" # Property documentation transformers: [trim, title] # Data transformers validation: ["min:3"] # Custom validation # Relations section - Defines nested DTOs relations: address: type: has_one class: AddressDto # Export section - Configure output formats export: formats: [json, xml, csv] # Validation section - Global validation settings validation: stop_on_first_failure: true ``` ## Header Section The `header` section defines metadata about your generated DTO class: ```yaml header: # Required fields class: ProductDto # The generated class name namespace: App\DTOs\Products # PHP namespace for the class # Optional fields description: "Product data object" # Class docblock description extends: BaseDto # Parent class to extend implements: [JsonSerializable] # Interfaces to implement traits: [HasTimestamps, HasUuid] # Behavioral traits to use final: true # Make class final (default: true) readonly: true # Make properties readonly (default: true) ``` ### Generated Header Example ```yaml header: class: UserDto namespace: App\DTOs description: "User data transfer object with validation" traits: [HasTimestamps] ``` Generates: ```php ['required', 'email', 'max:255', 'unique:users,email'], ]; } ``` ### Custom Validation Rules ```yaml fields: password: type: string required: true validation: ["min:8", "confirmed", "regex:/^.*(?=.{3,})(?=.*[a-zA-Z])(?=.*[0-9]).*$/"] ``` ## Behavioral Traits Add common functionality with traits: ```yaml header: traits: [HasTimestamps, HasUuid, SoftDeletes, HasTags] # HasTimestamps adds: # - created_at: datetime # - updated_at: datetime # HasUuid adds: # - uuid: string (auto-generated) # SoftDeletes adds: # - deleted_at: datetime|null # HasTags adds: # - tags: array of strings ``` ## Export Configuration Configure how DTOs export data: ```yaml export: formats: [json, xml, csv, yaml] # Available export formats exclude: [password, secret_key] # Fields to exclude from exports include_nulls: false # Include null values in exports date_format: "Y-m-d H:i:s" # Date formatting ``` ## Complete Real-World Example Here's a comprehensive example showcasing all features: ```yaml header: class: AdvancedUserDto namespace: App\DTOs\Users description: "Advanced user DTO with full feature set" traits: [HasTimestamps, HasUuid] fields: # Basic information name: type: string required: true max_length: 255 transformers: [trim, title_case] description: "User's full name" email: type: email required: true unique: true transformers: [trim, lowercase] validation: ["email:rfc,dns"] # Numeric fields age: type: integer min: 18 max: 120 description: "User's age in years" # Enums and defaults status: type: string default: "pending" enum: [pending, active, inactive, banned] # Geographic data location: type: point nullable: true description: "User's geographic location" # JSON data preferences: type: json default: {} description: "User preferences as JSON" # Collections tags: type: array items: type: string transformers: [trim, lowercase] relations: profile: type: has_one class: UserProfileDto addresses: type: has_many class: AddressDto export: formats: [json, xml] exclude: [password_hash] date_format: "c" # ISO 8601 format validation: stop_on_first_failure: false ``` ## YAML Best Practices ### 1. Consistent Naming ```yaml # Good - snake_case for field names fields: first_name: { type: string } last_name: { type: string } created_at: { type: datetime } # Avoid - inconsistent naming fields: firstName: { type: string } # camelCase last_name: { type: string } # snake_case CreatedAt: { type: datetime } # PascalCase ``` ### 2. Logical Field Grouping ```yaml fields: # Personal information first_name: { type: string, required: true } last_name: { type: string, required: true } birth_date: { type: date } # Contact information email: { type: email, required: true } phone: { type: string } # System fields status: { type: string, default: "active" } created_at: { type: datetime, auto_fill: true } ``` ### 3. Clear Documentation ```yaml fields: payment_amount: type: decimal precision: 10 scale: 2 min: 0 description: "Payment amount in cents (e.g., 1000 = $10.00)" example: 1500 ``` ## Common YAML Patterns ### API Request DTO ```yaml header: class: CreateUserRequestDto namespace: App\DTOs\Requests fields: name: { type: string, required: true, max_length: 255 } email: { type: email, required: true, unique: true } password: { type: string, required: true, min_length: 8 } terms_accepted: { type: boolean, required: true } ``` ### API Response DTO ```yaml header: class: UserResponseDto namespace: App\DTOs\Responses traits: [HasTimestamps] fields: id: { type: integer, required: true } name: { type: string, required: true } email: { type: email, required: true } status: { type: string, required: true } export: exclude: [password, secret_key] ``` ### Configuration DTO ```yaml header: class: DatabaseConfigDto namespace: App\DTOs\Config fields: host: { type: string, default: "localhost" } port: { type: integer, default: 3306 } database: { type: string, required: true } username: { type: string, required: true } password: { type: string, required: true, hidden: true } charset: { type: string, default: "utf8mb4" } ssl: { type: boolean, default: false } ``` ## What's Next? Now that you understand the YAML structure: - **[Field Types](Field-Types.md)** - Explore all 65+ available field types - **[Field Transformers](Field-Transformers.md)** - Learn about data transformation - **[Behavioral Traits](Behavioral-Traits.md)** - Add common functionality - **[Generated DTO Structure](Generated-DTO-Structure.md)** - Understand the generated code --- *The YAML structure is the foundation of Laravel Arc. Master it, and you'll be able to create powerful, type-safe DTOs effortlessly.* 🚀