Laravel Architecture Patterns
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- 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
| 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
1---2name: laravel-architecture3description: Use when structuring a Laravel project, creating services/repositories/actions, implementing dependency injection, or organizing code layers.4versions:5 laravel: "13.0"6 php: "8.3"7user-invocable: true8references: references/container.md, references/providers.md, references/facades.md, references/contracts.md, references/structure.md, references/lifecycle.md, references/configuration.md, references/installation.md, references/upgrade.md, references/releases.md, references/sail.md, references/valet.md, references/homestead.md, references/octane.md, references/artisan.md, references/helpers.md, references/filesystem.md, references/processes.md, references/context.md, references/pennant.md, references/mcp.md, references/concurrency.md, references/deployment.md, references/envoy.md, references/logging.md, references/errors.md, references/packages.md9related-skills: solid-php, laravel-api, laravel-eloquent10metadata:11 source: https://skillmd.com/skills/fusengine/laravel-architecture12---1314<objective>15Covers Laravel application architecture end to end: project structure16(Actions, Contracts, DTOs, Services, Repositories layout), the service17container and dependency injection, service providers and facades,18environment/configuration, development environments (Sail, Valet, Homestead,19Octane), Artisan CLI, filesystem/processes/context, feature flags (Pennant),20MCP servers, concurrency, and production deployment (including Envoy,21logging, error handling, and package authoring).22</objective>2324# Laravel Architecture Patterns2526## Agent Workflow (MANDATORY)2728Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:29301. **fuse-ai-pilot:explore-codebase** - Analyze existing architecture312. **fuse-ai-pilot:research-expert** - Verify Laravel patterns via Context7323. **mcp__context7__query-docs** - Check service container and DI patterns3334After implementation, run **fuse-ai-pilot:sniper** for validation.3536---3738## Overview3940Laravel architecture focuses on clean separation of concerns, dependency injection, and maintainable code organization. This skill covers everything from project structure to production deployment.4142### When to Use4344- Structuring new Laravel projects45- Implementing services, repositories, actions46- Setting up dependency injection47- Configuring development environments48- Deploying to production4950---5152## Critical Rules53541. **Thin controllers** - Delegate business logic to services552. **Interfaces in app/Contracts/** - Never alongside implementations563. **DI over facades** - Constructor injection for testability574. **Files < 100 lines** - Split larger files per SOLID585. **Environment separation** - .env never committed5960---6162## Architecture6364```text65app/66├── Actions/ # Single-purpose action classes67├── Contracts/ # Interfaces (DI)68├── DTOs/ # Data transfer objects69├── Enums/ # PHP 8.1+ enums70├── Events/ # Domain events71├── Http/72│ ├── Controllers/ # Thin controllers73│ ├── Middleware/ # Request filters74│ ├── Requests/ # Form validation75│ └── Resources/ # API transformations76├── Jobs/ # Queued jobs77├── Listeners/ # Event handlers78├── Models/ # Eloquent models only79├── Policies/ # Authorization80├── Providers/ # Service registration81├── Repositories/ # Data access layer82└── Services/ # Business logic83```8485---8687## Reference Guide8889### Core Architecture9091| Reference | When to Use |92|-----------|-------------|93| [container.md](references/container.md) | Dependency injection, binding, resolution |94| [providers.md](references/providers.md) | Service registration, bootstrapping |95| [facades.md](references/facades.md) | Static proxies, real-time facades |96| [contracts.md](references/contracts.md) | Interfaces, loose coupling |97| [structure.md](references/structure.md) | Directory organization |98| [lifecycle.md](references/lifecycle.md) | Request handling flow |99100### Configuration & Setup101102| Reference | When to Use |103|-----------|-------------|104| [configuration.md](references/configuration.md) | Environment, config files |105| [installation.md](references/installation.md) | New project setup |106| [upgrade.md](references/upgrade.md) | Version upgrades, breaking changes |107| [releases.md](references/releases.md) | Release notes, versioning |108109### Development Environments110111| Reference | When to Use |112|-----------|-------------|113| [sail.md](references/sail.md) | Docker development |114| [valet.md](references/valet.md) | macOS native development |115| [homestead.md](references/homestead.md) | Vagrant (legacy) |116| [octane.md](references/octane.md) | High-performance servers |117118### Utilities & Tools119120| Reference | When to Use |121|-----------|-------------|122| [artisan.md](references/artisan.md) | CLI commands, custom commands |123| [helpers.md](references/helpers.md) | Global helper functions |124| [filesystem.md](references/filesystem.md) | File storage, S3, local |125| [processes.md](references/processes.md) | Shell command execution |126| [context.md](references/context.md) | Request-scoped data sharing |127128### Advanced Features129130| Reference | When to Use |131|-----------|-------------|132| [pennant.md](references/pennant.md) | Feature flags |133| [mcp.md](references/mcp.md) | Model Context Protocol |134| [concurrency.md](references/concurrency.md) | Parallel execution |135136### Operations137138| Reference | When to Use |139|-----------|-------------|140| [deployment.md](references/deployment.md) | Production deployment |141| [envoy.md](references/envoy.md) | SSH task automation |142| [logging.md](references/logging.md) | Log channels, formatting |143| [errors.md](references/errors.md) | Exception handling |144| [packages.md](references/packages.md) | Creating packages |145146---147148## Templates149150| Template | Purpose |151|----------|---------|152| [UserService.php.md](references/templates/UserService.php.md) | Service + repository pattern |153| [AppServiceProvider.php.md](references/templates/AppServiceProvider.php.md) | DI bindings, bootstrapping |154| [ArtisanCommand.php.md](references/templates/ArtisanCommand.php.md) | CLI commands, signatures, I/O |155| [McpServer.php.md](references/templates/McpServer.php.md) | MCP servers, tools, resources, prompts |156| [PennantFeature.php.md](references/templates/PennantFeature.php.md) | Feature flags, A/B testing |157| [Envoy.blade.php.md](references/templates/Envoy.blade.php.md) | SSH deployment automation |158| [sail-config.md](references/templates/sail-config.md) | Docker Sail configuration |159| [octane-config.md](references/templates/octane-config.md) | FrankenPHP, Swoole, RoadRunner |160161---162163## Feature Matrix164165| Feature | Reference | Priority |166|---------|-----------|----------|167| Service Container | container.md | High |168| Service Providers | providers.md | High |169| Directory Structure | structure.md | High |170| Configuration | configuration.md | High |171| Installation | installation.md | High |172| Octane (Performance) | octane.md | High |173| Sail (Docker) | sail.md | High |174| Artisan CLI | artisan.md | Medium |175| Deployment | deployment.md | Medium |176| Envoy (SSH) | envoy.md | Medium |177| Facades | facades.md | Medium |178| Contracts | contracts.md | Medium |179| Valet (macOS) | valet.md | Medium |180| Upgrade Guide | upgrade.md | Medium |181| Logging | logging.md | Medium |182| Errors | errors.md | Medium |183| Lifecycle | lifecycle.md | Medium |184| Filesystem | filesystem.md | Medium |185| Helpers | helpers.md | Low |186| Pennant (Flags) | pennant.md | Low |187| Context | context.md | Low |188| Processes | processes.md | Low |189| Concurrency | concurrency.md | Low |190| MCP | mcp.md | Low |191| Packages | packages.md | Low |192| Releases | releases.md | Low |193| Homestead | homestead.md | Low |194195---196197## Quick Reference198199### Service Injection200201```php202public function __construct(203 private readonly UserServiceInterface $userService,204) {}205```206207### Service Provider Binding208209```php210public function register(): void211{212 $this->app->bind(UserServiceInterface::class, UserService::class);213 $this->app->singleton(CacheService::class);214}215```216217### Artisan Command218219```shell220php artisan make:provider CustomServiceProvider221php artisan make:command ProcessOrders222```223224### Environment Access225226```php227$debug = env('APP_DEBUG', false);228$config = config('app.name');229```230231---232233## Laravel 13 Notes234235### Stack mis à jour236- **Symfony 7.4 et 8.0** supportés en parallèle (HttpFoundation, Console, Mailer)237- **PHP 8.3 minimum** (8.2 retiré)238- **pda/pheanstalk 8.0+** requis si driver Beanstalk239240### Cache::touch() API241Nouvelle méthode pour rafraîchir le TTL sans recalculer la valeur.242243```php244Cache::touch('user:123', now()->addHour());245Cache::touch(['user:123', 'user:456'], 3600);246```247248### Queue::route() pour routing dynamique249Voir [[laravel-queues]] pour le routing déclaratif par job (connexion/queue cible via configuration plutôt que sur chaque job).250251### `new Model()` dans boot() → LogicException252Laravel 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.253254## Migration Laravel 12 → 13255256| Sujet | Avant (12) | Après (13) |257|-------|-----------|------------|258| PHP minimum | 8.2 | **8.3** |259| PHPUnit | 11 | **12** |260| Pest | 3 | **4** |261| CSRF | `VerifyCsrfToken` | **`PreventRequestForgery`** (origin-aware) |262| Cache prefix | underscore | **hyphens par défaut** (configurer `CACHE_PREFIX`, `REDIS_PREFIX`, `SESSION_COOKIE` pour rétro-compat) |263| Beanstalk | pheanstalk 7.x | **pheanstalk 8.0+** |264| Symfony | 7.x | **7.4 / 8.0** |265| Model boot | toléré | **`new Model()` → LogicException** |266| Config | — | nouveau `serializable_classes` (allowlist hardening) |267268```env269# Rétro-compat cache prefixes pour upgrade depuis L12270CACHE_PREFIX=laravel_cache_271REDIS_PREFIX=laravel_database_272SESSION_COOKIE=laravel_session273```274275```php276// config/app.php — durcissement deserialize277'serializable_classes' => [278 App\DTO\PaymentDto::class,279 App\DTO\OrderDto::class,280],281```282283## Best Practices284285### DO286- Utiliser `final readonly class` pour DTOs et Value Objects (PHP 8.3+)287- Injecter via constructor promotion + `interface` (DI inversion)288- Logger via `Context::add()` pour propager metadata entre jobs/requêtes289- Configurer `serializable_classes` en production290- Préférer `app(Contract::class)` sur `App::make()` (typage strict)291292### DON'T293- Instancier des modèles dans `register()` (→ LogicException L13)294- Hardcoder des chemins absolus (utiliser `base_path()`, `storage_path()`)295- Mélanger Repository et Service (un par responsabilité)296- Bypasser le container avec `new ConcreteClass()`297- Ignorer le bump du préfixe cache lors d'un upgrade depuis L12