Laravel Cursor Rules: PHP Web Application Guide

---
description: Enforces best practices for Laravel development, focusing on Eloquent ORM, Artisan commands, and MVC architecture. Provides comprehensive guidelines for writing clean, maintainable PHP applications with proper context.
globs: **/*.php
---
# Laravel Best Practices

You are an expert in Laravel development and related web technologies.
You understand modern Laravel development practices, architectural patterns, and the importance of providing complete context in code generation.

### Context-Aware Code Generation
- Provide complete module context including models, controllers, requests, and route definitions
- Include relevant config (database, cache, queue) when generating application code
- Generate complete class signatures with proper type hints and PHPDoc
- Document the request lifecycle through middleware, controllers, and Eloquent queries

### Project Structure
- /app/Http/Controllers - HTTP request handlers organized by resource
- /app/Models - Eloquent model definitions with relationships and scopes
- /app/Http/Requests - form request classes with validation rules
- /routes - web.php and api.php route definitions
- /database/migrations - versioned schema change files

### Eloquent ORM & Relationships
- Define relationships (belongsTo, hasMany, belongsToMany) explicitly on all models
- Use scopes for reusable query constraints
- Add casts for date, JSON, and enum field types
- Use route model binding for automatic model injection
- Use eager loading (with()) to prevent N+1 queries

### Form Requests & Validation
- Use FormRequest classes for validating incoming HTTP data
- Define authorization rules in the authorize() method of FormRequest
- Use unique validation rules with proper table and column references
- Return validation errors as JSON for API requests automatically
- Use custom rule objects for complex validation logic

### Security
- Use Laravel's built-in CSRF protection for web routes
- Apply authorization gates and policies for resource access control
- Use rate limiting for API routes to prevent abuse
- Validate file uploads with MIME type and size constraints
- Use environment-based configuration for sensitive credentials

### Testing & Quality
- Write tests with PHPUnit and Laravel's test helpers
- Use factories and faker for test data generation
- Test HTTP endpoints with actingAs() for authenticated requests
- Run Laravel Dusk for browser-level UI testing
- Use Laravel Pint for consistent PSR-12 code style

### Artisan & Deployment
- Use Laravel 11+ for latest features and security patches
- Use Artisan commands for recurring tasks and maintenance
- Queue long-running jobs with Horizon or database driver
- Run migrations with php artisan migrate before deploying new code
- Cache config and routes in production with artisan optimize

// app/Models/User.php — Eloquent model with relationships and casts
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;

class User extends Model
{
    protected $casts = [
        'email_verified_at' => 'datetime',
        'metadata' => 'json',
    ];

    public function posts(): HasMany
    {
        return $this->hasMany(Post::class);
    }
}

// app/Http/Requests/StoreUserRequest.php — Form request with validation
namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class StoreUserRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true;
    }

    public function rules(): array
    {
        return [
            'email' => ['required', 'email', 'unique:users,email'],
            'name' => ['required', 'string', 'max:255'],
            'password' => ['required', 'string', 'min:8', 'confirmed'],
        ];
    }
}