Laravel Best Practices

# Laravel 13 Best Practices - Complete Guide

**Version:** 2.1.0
**Laravel Version:** 13.x
**PHP Version:** 8.3+
**Organization:** Laravel Community
**Date:** March 2026

## Overview

Comprehensive best practices guide for Laravel 13 applications, designed for AI agents and LLMs. Contains 31 rules across 7 categories, prioritized by impact from critical (architecture and database patterns) to incremental (performance optimization). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations using PHP 8.3 and Laravel 13 features, and specific impact metrics to guide automated refactoring and code generation.

### Key Features

- Service classes for business logic separation
- Eager loading to prevent N+1 queries
- Form request classes for validation
- Resource controllers following REST conventions
- Eloquent relationships and query scopes
- Mass assignment protection
- API resources for response transformation
- Modern PHP 8.3 syntax (readonly properties, constructor promotion)
- Laravel 13 patterns and conventions

## Categories

This guide is organized into 7 categories, prioritized by their impact on application quality:

1. **Architecture & Structure (CRITICAL)** - Foundational patterns for organizing Laravel applications
2. **Eloquent & Database (CRITICAL)** - Efficient database operations and ORM usage
3. **Controllers & Routing (HIGH)** - RESTful conventions and proper request handling
4. **Validation & Requests (HIGH)** - Form request classes and validation patterns
5. **Security (HIGH)** - Protection against common vulnerabilities
6. **Performance (MEDIUM)** - Caching strategies and optimization techniques
7. **API Design (MEDIUM)** - RESTful API patterns and resource transformers

### References

- [Laravel 13 Documentation](https://laravel.com/docs/13.x)
- [Laravel Eloquent](https://laravel.com/docs/13.x/eloquent)
- [Laravel Controllers](https://laravel.com/docs/13.x/controllers)
- [Laravel Validation](https://laravel.com/docs/13.x/validation)
- [PHP Type Declarations](https://php.net/manual/en/language.types.declarations.php)

---

## 1. Architecture & Structure (CRITICAL)

**Impact:** CRITICAL  
**Description:** Foundational patterns for organizing Laravel applications. Service classes, action classes, DTOs, and proper separation of concerns are essential for maintainable, scalable codebases. These patterns determine long-term code quality and team productivity.

**Rules in this category:** 7

---

## Value Objects

**Impact: MEDIUM (Enforces business rules and improves type safety)**

Encapsulate domain concepts with value objects to enforce business rules and improve type safety.

## Bad Example

```php
// Primitive obsession - using strings/numbers for domain concepts
class User extends Model
{
    public function setEmailAttribute(string $value): void
    {
        // Validation scattered across the codebase
        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
            throw new InvalidArgumentException('Invalid email');
        }
        $this->attributes['email'] = strtolower($value);
    }
}

class Order extends Model
{
    public function calculateTotal(): float
    {
        // Money as float - precision issues
        return $this->subtotal + $this->tax - $this->discount;
    }

    public function applyDiscount(float $amount): void
    {
        // No validation of negative values
        $this->discount = $amount;
    }
}

// Phone number without structure
$user->phone = '+1-555-123-4567';
// Later...
$cleanPhone = preg_replace('/[^0-9]/', '', $user->phone); // Manual parsing
```

## Good Example

```php
// Email value object
namespace App\ValueObjects;

use InvalidArgumentException;

readonly class Email
{
    public function __construct(
        private string $value
    ) {
        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
            throw new InvalidArgumentException("Invalid email address: {$value}");
        }
    }

    public fu