Laravel Architecture Patterns Skill

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

| 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 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

Agent Skills: Laravel Architecture Patterns

Install this agent skill to your local

Skill Files