Laravel Data Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require spatie/laravel-data
   

   Ensure you have PHP 8.2+ and Laravel 10+ (or newer, as per latest compatibility).

2. Define a Data Class: Create a class extending Spatie\LaravelData\Data with typed properties:

   use Spatie\LaravelData\Data;
   
   class UserData extends Data
   {
       public function __construct(
           public string $name,
           public int $age,
       ) {}
   }
   

3. First Use Case: Instantiate directly or from request data:

   // Direct instantiation
   $user = new UserData(name: 'John', age: 30);
   
   // From request (auto-validation)
   $user = UserData::fromRequest(request());
   

Where to Look First

• Documentation: Start with the "Getting Started" section.
• Validation Attributes: Explore built-in attributes like #[Max(100)] for property-level validation.
• TypeScript Generation: Use php artisan data:typescript to generate frontend types.

Implementation Patterns

Core Workflows

1. Request Handling: Replace FormRequests with Data classes for validation and type safety:

   class StoreUserRequest extends FormRequest {
       public function rules(): array {
           return UserData::rules(); // Auto-generates rules from Data class
       }
   }
   

2. API Responses: Use Data classes as API resources:

   class UserResource extends JsonResource {
       public function toArray($request): array {
           return $this->resource->toArray(); // Converts Data to array
       }
   }
   

3. Eloquent Integration: Cast model attributes as Data:

   use Spatie\LaravelData\Casts\Data;
   
   class User extends Model {
       protected $casts = [
           'metadata' => Data::class,
       ];
   }
   

4. Lazy Properties: Defer computation until accessed:

   class UserData extends Data {
       public function __construct(public string $name) {}
   
       public function fullName(): string {
           return "User: {$this->name}";
       }
   }
   

Integration Tips

• Validation: Combine with Laravel’s validation pipeline:

  $data = UserData::from($request->all());
  $data->validate(); // Throws ValidationException on failure
  

• TypeScript: Generate types for frontend:

  php artisan data:typescript
  

• Collections: Use DataCollection for arrays of Data:

  $users = DataCollection::from(UserData::class, $rawUsers);
  

Gotchas and Tips

Pitfalls

1. Validation Rules Overrides:

   • Rules in rules() method always run, even if properties have defaults (fixed in v4.23.0).
   • Example:

     class UserData extends Data {
         public function __construct(
             public string $name,
             public ?string $email = null,
         ) {}
     
         public static function rules(): array {
             return [
                 'email' => ['required_if:name,John'], // Now works!
             ];
         }
     }
     

2. PHP 8.4+ Dependencies:

   • Pest conflicts resolved in v4.23.0; ensure phpdocumentor/reflection-docblock is compatible.

3. Lazy Properties in Casts:

   • Lazy properties (e.g., computed fields) are not included in toArray() by default. Use #[Lazy] attribute or override toArray().

4. TypeScript Generation:

   • Cursor pagination properties (e.g., cursor) may need manual fixes (see #1098).

Debugging Tips

• Validation Errors: Use ->validate() to catch issues early:

  try {
      $data->validate();
  } catch (ValidationException $e) {
      dd($e->errors());
  }
  

• Reflection Issues: Clear cached views (php artisan view:clear) if Data classes break after updates.
• Eloquent Casts: Ensure Data casts are registered in $casts with the full namespace.

Extension Points

1. Custom Validation Attributes: Extend Spatie\LaravelData\Attributes\ValidationAttribute for reusable rules:

   #[Attribute]
   class CustomRule extends ValidationAttribute {
       protected string $rule = 'custom_rule';
   }
   

2. Data Transformers: Override toArray() or use #[MapTo] to customize output:

   class UserData extends Data {
       #[MapTo('user_name')]
       public string $name;
   }
   

3. TypeScript Templates: Customize generated TS types via config/data.php:

   'typescript' => [
       'template' => resource_path('templates/data.ts.hbs'),
   ],
   

4. Database Constraints: Use #[DatabaseConstraint] to enforce DB-level rules (v4.22.0+):

   #[DatabaseConstraint('unique', 'users', 'email')]
   public string $email;