Laravel architecture

Laravel Architecture Patterns

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

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

Reference	When to Use
container.md	Dependency injection, binding, resolution
providers.md	Service registration, bootstrapping
facades.md	Static proxies, real-time facades
contracts.md	Interfaces, loose coupling
structure.md	Directory organization
lifecycle.md	Request handling flow

Configuration & Setup

Reference	When to Use
configuration.md	Environment, config files
installation.md	New project setup
upgrade.md	Version upgrades, breaking changes
releases.md	Release notes, versioning

Development Environments

Reference	When to Use
sail.md	Docker development
valet.md	macOS native development
homestead.md	Vagrant (legacy)
octane.md	High-performance servers

Utilities & Tools

Reference	When to Use
artisan.md	CLI commands, custom commands
helpers.md	Global helper functions
filesystem.md	File storage, S3, local
processes.md	Shell command execution
context.md	Request-scoped data sharing

Advanced Features

Reference	When to Use
pennant.md	Feature flags
mcp.md	Model Context Protocol
concurrency.md	Parallel execution

Operations

Reference	When to Use
deployment.md	Production deployment
envoy.md	SSH task automation
logging.md	Log channels, formatting
errors.md	Exception handling
packages.md	Creating packages

---

Templates

Template	Purpose
UserService.php.md	Service + repository pattern
AppServiceProvider.php.md	DI bindings, bootstrapping
ArtisanCommand.php.md	CLI commands, signatures, I/O
McpServer.php.md	MCP servers, tools, resources, prompts
PennantFeature.php.md	Feature flags, A/B testing
Envoy.blade.php.md	SSH deployment automation
sail-config.md	Docker Sail configuration
octane-config.md	FrankenPHP, Swoole, RoadRunner

---

Feature Matrix

Feature	Reference	Priority
Service Container	container.md	High
Service Providers	providers.md	High
Directory Structure	structure.md	High
Configuration	configuration.md	High
Installation	installation.md	High
Octane (Performance)	octane.md	High
Sail (Docker)	sail.md	High
Artisan CLI	artisan.md	Medium
Deployment	deployment.md	Medium
Envoy (SSH)	envoy.md	Medium
Facades	facades.md	Medium
Contracts	contracts.md	Medium
Valet (macOS)	valet.md	Medium
Upgrade Guide	upgrade.md	Medium
Logging	logging.md	Medium
Errors	errors.md	Medium
Lifecycle	lifecycle.md	Medium
Filesystem	filesystem.md	Medium
Helpers	helpers.md	Low
Pennant (Flags)	pennant.md	Low
Context	context.md	Low
Processes	processes.md	Low
Concurrency	concurrency.md	Low
MCP	mcp.md	Low
Packages	packages.md	Low
Releases	releases.md	Low
Homestead	homestead.md	Low

---

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

Sujet	Avant (12)	Après (13)
PHP minimum	8.2	8.3
PHPUnit	11	12
Pest	3	4
CSRF	VerifyCsrfToken	PreventRequestForgery (origin-aware)
Cache prefix	underscore	hyphens par défaut (configurer CACHE_PREFIX, REDIS_PREFIX, SESSION_COOKIE pour rétro-compat)
Beanstalk	pheanstalk 7.x	pheanstalk 8.0+
Symfony	7.x	7.4 / 8.0
Model boot	toléré	new Model() → LogicException
Config	—	nouveau serializable_classes (allowlist hardening)

# 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