# Laravel Architecture

> Design Laravel app architecture with services, repositories, actions, and clean code patterns. Use when structuring projects, creating services, implementing DI, or organizing code layers.

- **Type:** Skill
- **Install:** `agentstack add skill-fusengine-agents-laravel-architecture`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [fusengine](https://agentstack.voostack.com/s/fusengine)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [fusengine](https://github.com/fusengine)
- **Source:** https://github.com/fusengine/agents/tree/main/plugins/laravel-expert/skills/laravel-architecture

## Install

```sh
agentstack add skill-fusengine-agents-laravel-architecture
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 app->bind(UserServiceInterface::class, UserService::class);
    $this->app->singleton(CacheService::class);
}
```

### Artisan Command

```shell
php artisan make:provider CustomServiceProvider
php artisan make:command ProcessOrders
```

### Environment Access

```php
$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.

```php
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) |

```env
# Rétro-compat cache prefixes pour upgrade depuis L12
CACHE_PREFIX=laravel_cache_
REDIS_PREFIX=laravel_database_
SESSION_COOKIE=laravel_session
```

```php
// 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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [fusengine](https://github.com/fusengine)
- **Source:** [fusengine/agents](https://github.com/fusengine/agents)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-fusengine-agents-laravel-architecture
- Seller: https://agentstack.voostack.com/s/fusengine
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.