# 🔧 Field Types

Laravel Arc supports 65+ field types through integration with ModelSchema. This comprehensive guide covers all available types and their usage.

## Type Categories

Laravel Arc organizes field types into logical categories:

```yaml
# Basic Types - Core data types
fields:
  name: { type: string }
  age: { type: integer }
  price: { type: decimal }

# Advanced Types - ModelSchema integration  
fields:
  location: { type: point }      # Geographic
  ip: { type: ipAddress }        # Network
  avatar: { type: image }        # File
```

## Basic Types

### String Types

```yaml
fields:
  # Basic string
  name:
    type: string
    max_length: 255
    min_length: 2
    
  # Email with validation
  email:
    type: email
    required: true
    
  # URL validation
  website:
    type: url
    nullable: true
    
  # Text for longer content
  description:
    type: text
    max_length: 1000
    
  # Slug for URL-friendly strings
  slug:
    type: slug
    unique: true
```

### Numeric Types

```yaml
fields:
  # Integer
  age:
    type: integer
    min: 0
    max: 150
    
  # Decimal with precision
  price:
    type: decimal
    precision: 8
    scale: 2
    min: 0
    
  # Float
  rating:
    type: float
    min: 0.0
    max: 5.0
    
  # Big integer for large numbers
  views_count:
    type: bigInteger
    default: 0
```

### Boolean and Date Types

```yaml
fields:
  # Boolean
  is_active:
    type: boolean
    default: true
    
  # Date only
  birth_date:
    type: date
    
  # DateTime with timezone
  created_at:
    type: datetime
    auto_fill: true
    
  # Time only
  meeting_time:
    type: time
    
  # Timestamp
  last_login:
    type: timestamp
    nullable: true
```

## Advanced Types (ModelSchema Integration)

### Geographic Types

Perfect for location-based applications:

```yaml
fields:
  # Point location (latitude, longitude)
  store_location:
    type: point
    description: "Store coordinates"
    example: "POINT(-74.0059 40.7128)"  # New York
    
  # Geographic boundary
  delivery_area:
    type: polygon
    description: "Delivery coverage area"
    
  # Route or path
  delivery_route:
    type: linestring
    description: "Delivery route path"
    
  # Multi-point locations
  branch_locations:
    type: multiPoint
    description: "All branch locations"
    
  # Complex geographic area
  service_zones:
    type: multiPolygon
    description: "Multiple service areas"
```

### Network Types

For network and connectivity data:

```yaml
fields:
  # IP Address (v4 or v6)
  user_ip:
    type: ipAddress
    description: "User's IP address"
    example: "192.168.1.100"
    
  # MAC Address
  device_mac:
    type: macAddress
    description: "Device MAC address"
    example: "00:1B:44:11:3A:B7"
    
  # Domain name
  company_domain:
    type: domain
    description: "Company domain"
    example: "example.com"
    
  # Hostname
  server_host:
    type: hostname
    description: "Server hostname"
    example: "web01.example.com"
```

### File and Media Types

For handling files and media:

```yaml
fields:
  # Image files
  profile_picture:
    type: image
    max_size: "2MB"
    allowed_extensions: [jpg, jpeg, png, gif]
    
  # General files
  resume:
    type: file
    max_size: "5MB"
    allowed_extensions: [pdf, doc, docx]
    
  # Audio files
  podcast:
    type: audio
    max_size: "50MB"
    allowed_extensions: [mp3, wav, ogg]
    
  # Video files
  tutorial:
    type: video
    max_size: "100MB"
    allowed_extensions: [mp4, avi, mov]
```

### Identifier Types

For unique identifiers and codes:

```yaml
fields:
  # UUID (auto-generated)
  uuid:
    type: uuid
    auto_fill: true
    
  # Custom ID format
  product_code:
    type: alphanumeric
    length: 8
    uppercase: true
    
  # SKU code
  sku:
    type: sku
    format: "PRD-{category}-{id}"
    
  # Barcode
  barcode:
    type: barcode
    type_format: "EAN13"
    
  # Hash
  password_hash:
    type: hash
    algorithm: "bcrypt"
    hidden: true
```

### Financial Types

For monetary and financial data:

```yaml
fields:
  # Currency amount
  amount:
    type: money
    currency: "USD"
    precision: 2
    
  # Currency code
  currency:
    type: currency
    default: "USD"
    
  # Percentage
  discount_rate:
    type: percentage
    min: 0
    max: 100
    precision: 2
    
  # Tax rate
  tax_rate:
    type: taxRate
    min: 0
    max: 50
```

### Color and Design Types

For UI and design elements:

```yaml
fields:
  # Hex color
  brand_color:
    type: color
    format: "hex"
    default: "#000000"
    
  # RGB color
  background_color:
    type: rgb
    default: "rgb(255, 255, 255)"
    
  # HSL color
  accent_color:
    type: hsl
    default: "hsl(0, 0%, 100%)"
    
  # CSS class
  css_class:
    type: cssClass
    pattern: "^[a-zA-Z][a-zA-Z0-9_-]*$"
```

### Specialized Types

Unique field types for specific use cases:

```yaml
fields:
  # Language code
  language:
    type: language
    default: "en"
    format: "ISO639-1"
    
  # Country code
  country:
    type: country
    format: "ISO3166-1"
    
  # Timezone
  timezone:
    type: timezone
    default: "UTC"
    
  # Mime type
  content_type:
    type: mimeType
    allowed: ["image/jpeg", "image/png", "application/pdf"]
    
  # Regular expression
  validation_pattern:
    type: regex
    description: "Validation regex pattern"
    
  # Cron expression
  schedule:
    type: cron
    description: "Job schedule expression"
    example: "0 9 * * 1-5"
```

## Collection Types

### Arrays and Lists

```yaml
fields:
  # Array of strings
  tags:
    type: array
    items:
      type: string
      max_length: 50
    max_items: 10
    
  # Array of integers
  scores:
    type: array
    items:
      type: integer
      min: 0
      max: 100
      
  # Array of objects
  addresses:
    type: array
    items:
      type: object
      class: AddressDto
    min_items: 1
    max_items: 5
```

### Key-Value Collections

```yaml
fields:
  # Simple key-value pairs
  metadata:
    type: json
    schema:
      type: object
      properties:
        title: { type: string }
        views: { type: integer }
        
  # Typed collections
  settings:
    type: collection
    key_type: string
    value_type: string
    
  # Nested collections
  categories:
    type: nestedCollection
    structure:
      name: { type: string }
      subcategories: 
        type: array
        items: { type: string }
```

## Type Validation and Constraints

### Common Constraints

```yaml
fields:
  username:
    type: string
    required: true           # Field is required
    nullable: false          # Cannot be null
    min_length: 3           # Minimum length
    max_length: 20          # Maximum length
    pattern: "^[a-zA-Z0-9_]+$"  # Regex pattern
    unique: true            # Must be unique
    
  age:
    type: integer
    min: 18                 # Minimum value
    max: 65                 # Maximum value
    
  email:
    type: email
    domains: ["company.com"] # Restrict to specific domains
```

### Advanced Validation

```yaml
fields:
  phone:
    type: string
    validation: 
      - "regex:/^\+?[1-9]\d{1,14}$/"  # International format
      - "custom:phone_number"          # Custom rule
      
  file_upload:
    type: file
    validation:
      - "mimes:jpeg,png,jpg,gif"
      - "max:2048"  # Max 2MB
      
  password:
    type: string
    validation:
      - "min:8"
      - "confirmed"
      - "regex:/^.*(?=.{3,})(?=.*[a-zA-Z])(?=.*[0-9]).*$/"
```

## Custom Type Definition

Create your own field types:

```yaml
# Define custom type in config/arc.php
'custom_types' => [
    'socialSecurityNumber' => [
        'base_type' => 'string',
        'validation' => ['regex:/^\d{3}-\d{2}-\d{4}$/'],
        'transformers' => ['trim', 'format_ssn'],
        'hidden' => true,
    ],
],

# Use in YAML
fields:
  ssn:
    type: socialSecurityNumber
    required: true
```

## Type Conversion Examples

### From YAML to Generated Code

```yaml
# YAML Definition
fields:
  location:
    type: point
    required: true
    description: "Geographic coordinates"
```

```php
// Generated Property
/**
 * Geographic coordinates
 */
public Point $location,
```

```php
// Generated Validation
public static function validationRules(): array
{
    return [
        'location' => ['required', 'point'],
    ];
}
```

## Real-World Examples

### E-commerce Product DTO

```yaml
header:
  class: ProductDto
  namespace: App\DTOs\Catalog

fields:
  # Basic info
  name: { type: string, required: true, max_length: 255 }
  slug: { type: slug, unique: true, auto_generate: true }
  description: { type: text, max_length: 2000 }
  
  # Pricing
  price: { type: money, currency: "USD", min: 0 }
  sale_price: { type: money, currency: "USD", nullable: true }
  
  # Media
  images: 
    type: array
    items: { type: image, max_size: "5MB" }
    max_items: 10
    
  # Attributes
  weight: { type: decimal, precision: 8, scale: 2, unit: "kg" }
  dimensions: { type: json, schema: { width: number, height: number, depth: number } }
  
  # Categories
  categories:
    type: array
    items: { type: string }
    
  # Metadata
  seo_meta: { type: json, nullable: true }
  is_featured: { type: boolean, default: false }
```

### User Profile DTO

```yaml
header:
  class: UserProfileDto
  namespace: App\DTOs\Users

fields:
  # Personal info
  first_name: { type: string, required: true, max_length: 100 }
  last_name: { type: string, required: true, max_length: 100 }
  birth_date: { type: date, nullable: true }
  
  # Contact
  email: { type: email, required: true, unique: true }
  phone: { type: string, pattern: "^\+?[1-9]\d{1,14}$" }
  
  # Location
  address: { type: text, max_length: 500 }
  city: { type: string, max_length: 100 }
  country: { type: country }
  timezone: { type: timezone, default: "UTC" }
  
  # Preferences
  language: { type: language, default: "en" }
  currency: { type: currency, default: "USD" }
  theme_color: { type: color, default: "#007bff" }
  
  # Social
  avatar: { type: image, max_size: "2MB", nullable: true }
  bio: { type: text, max_length: 500, nullable: true }
  social_links: { type: json, nullable: true }
```

## Type Performance Considerations

### Efficient Types
```yaml
# Good - efficient types
fields:
  id: { type: integer }        # Fast indexing
  status: { type: string, enum: [...] }  # Limited values
  created_at: { type: timestamp }  # Optimized for time queries

# Consider alternatives for large data
fields:
  large_text: { type: text }   # Consider external storage for very large content
  binary_data: { type: file }  # Store files separately, reference by path
```

## What's Next?

Now that you understand field types:

- **[Field Transformers](Field-Transformers.md)** - Automatic data transformation
- **[Generated DTO Structure](Generated-DTO-Structure.md)** - Understanding generated code
- **[Behavioral Traits](Behavioral-Traits.md)** - Add common functionality
- **[Example API Integration](Example-API-Integration.md)** - See types in action

---

*With 65+ field types, Laravel Arc handles any data structure you can imagine. Choose the right type for optimal validation and performance.* 🎯