Laravel Architecture Patterns
Agent Workflow (MANDATORY)
Before ANY implementation, use TeamCreate to spawn 3 agents:
- fuse-ai-pilot:explore-codebase - Analyze existing architecture
- fuse-ai-pilot:research-expert - Verify Laravel patterns via Context7
- 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
- Thin controllers - Delegate business logic to services
- Interfaces in app/Contracts/ - Never alongside implementations
- DI over facades - Constructor injection for testability
- Files < 100 lines - Split larger files per SOLID
- 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
| 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 13 → 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
