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