Laravel Architecture

Laravel Architecture Patterns

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:

1. fuse-ai-pilot:explore-codebase - Analyze existing architecture
2. fuse-ai-pilot:research-expert - Verify Laravel patterns via Context7
3. mcp__context7__query-docs - Check service container and DI patterns

After implementation, run fuse-ai-pilot:sniper for validation.

Overview

Laravel architecture focuses on clean separation of concerns, dependency injection, and maintainable code organization. This skill covers everything from project structure to production deployment.

When to Use

• Structuring new Laravel projects
• Implementing services, repositories, actions
• Setting up dependency injection
• Configuring development environments
• Deploying to production

Critical Rules

1. Thin controllers - Delegate business logic to services
2. Interfaces in app/Contracts/ - Never alongside implementations
3. DI over facades - Constructor injection for testability
4. Files < 100 lines - Split larger files per SOLID
5. Environment separation - .env never committed

Architecture

app/
├── Actions/              # Single-purpose action classes
├── Contracts/            # Interfaces (DI)
├── DTOs/                 # Data transfer objects
├── Enums/                # PHP 8.1+ enums
├── Events/               # Domain events
├── Http/
│   ├── Controllers/      # Thin controllers
│   ├── Middleware/       # Request filters
│   ├── Requests/         # Form validation
│   └── Resources/        # API transformations
├── Jobs/                 # Queued jobs
├── Listeners/            # Event handlers
├── Models/               # Eloquent models only
├── Policies/             # Authorization
├── Providers/            # Service registration
├── Repositories/         # Data access layer
└── Services/             # Business logic

Reference Guide

Core Architecture

Configuration & Setup

Development Environments

Utilities & Tools

Advanced Features

Operations

Templates

Feature Matrix

Quick Reference

Service Injection

public function __construct(
    private readonly UserServiceInterface $userService,
) {}

Service Provider Binding

public function register(): void
{
    $this->app->bind(UserServiceInterface::class, UserService::class);
    $this->app->singleton(CacheService::class);
}

Artisan Command

php artisan make:provider CustomServiceProvider
php artisan make:command ProcessOrders

Environment Access

$debug = env('APP_DEBUG', false);
$config = config('app.name');

Laravel 13 Notes

Stack mis à jour

• Symfony 7.4 et 8.0 supportés en parallèle (HttpFoundation, Console, Mailer)
• PHP 8.3 minimum (8.2 retiré)
• pda/pheanstalk 8.0+ requis si driver Beanstalk

Cache::touch() API

Nouvelle méthode pour rafraîchir le TTL sans recalculer la valeur.

Cache::touch('user:123', now()->addHour());
Cache::touch(['user:123', 'user:456'], 3600);

Queue::route() pour routing dynamique

Voir [[laravel-queues]] pour le routing déclaratif par job (connexion/queue cible via configuration plutôt que sur chaque job).

new Model() dans boot() → LogicException

Laravel 13 jette une LogicException si vous instanciez un modèle Eloquent dans register() d'un ServiceProvider (container pas prêt). Utiliser boot() ou un listener.

Migration Laravel 12 → 13

# Rétro-compat cache prefixes pour upgrade depuis L12
CACHE_PREFIX=laravel_cache_
REDIS_PREFIX=laravel_database_
SESSION_COOKIE=laravel_session

// config/app.php — durcissement deserialize
'serializable_classes' => [
    App\DTO\PaymentDto::class,
    App\DTO\OrderDto::class,
],

Best Practices

DO

• Utiliser final readonly class pour DTOs et Value Objects (PHP 8.3+)
• Injecter via constructor promotion + interface (DI inversion)
• Logger via Context::add() pour propager metadata entre jobs/requêtes
• Configurer serializable_classes en production
• Préférer app(Contract::class) sur App::make() (typage strict)

DON'T

• Instancier des modèles dans register() (→ LogicException L13)
• Hardcoder des chemins absolus (utiliser base_path(), storage_path())
• Mélanger Repository et Service (un par responsabilité)
• Bypasser le container avec new ConcreteClass()
• Ignorer le bump du préfixe cache lors d'un upgrade depuis L12