Laravel Architecture

---
name: laravel-architecture
description: Use when structuring a Laravel project, creating services/repositories/actions, implementing dependency injection, or organizing code layers.
versions:
  laravel: "13.0"
  php: "8.3"
user-invocable: true
references: 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.md
related-skills: solid-php, laravel-api, laravel-eloquent
---

<objective>
Covers Laravel application architecture end to end: project structure
(Actions, Contracts, DTOs, Services, Repositories layout), the service
container and dependency injection, service providers and facades,
environment/configuration, development environments (Sail, Valet, Homestead,
Octane), Artisan CLI, filesystem/processes/context, feature flags (Pennant),
MCP servers, concurrency, and production deployment (including Envoy,
logging, error handling, and package authoring).
</objective>

# Laravel Architecture Patterns

## Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:

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

```text
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](references/container.md) | Dependency injection, binding, resolution |
| [providers.md](references/providers.md) | Service registration, bootstrapping |
| [facades.md](references/facades.md) | Static proxies, real-time facades |
| [contracts.md](references/contracts.md) | Interfaces, loose coupling |
| [structure.md](references/structure.md) | Directory organization |
| [lifecycle.md](references/lifecycle.md) | Request handling flow |

### Configuration & Setup

| Reference | When to Use |
|-----------|-------------|
| [configuration.md](references/configuration.md) | Environment, config files |
| [installation.md](references/installation.md) | New project setup |
| [upgrade.md](references/upgrade.md) | Version upgrades, breaking changes |
| [releases.md](references/releases.md) | Release notes, versioning |

### Development Environments

| Reference | When to Use |
|-----------|-------------|
| [sail.md](references/sail.md) | Docker development |
| [valet.md](references/valet.md) | macOS native development |
| [homestead.md](references/homestead.md) | Vagrant (legacy) |
| [octane.md](references/octane.md) | High-performance servers |

### Utilities & Tools

| Reference | When to Use |
|-----------|-------------|
| [artisan.md](references/artisan.md) | CLI commands, custom commands |
| [helpers.md](references/helpers.md) | Global helper functions |
| [filesystem.md](references/filesystem.md) | File storage, S3, local |
| [processes.md](references/processes.md) | Shell command execution |
| [context.md](references/context.md) | Request-scoped data sharing |

### Advanced Features

| Reference | When to Use |
|-----------|-------------|
| [pennant.md](references/pennant.md) | Feature flags |
| [mcp.md](references/mcp.md) | Model Context Protocol |
| [concurrency.md](references/concurrency.md) | Parallel execution |

### Operations

| Reference | When to Use |
|-----------|-------------|
| [deployment.md](references/deployment.md) | Production deployment |
| [envoy.md](references/envoy.md) | SSH task automation |
| [logging.md](references/logging.md) | Log channels, formatting |
| [errors.md](references/errors.md) | Exception handling |
| [packages.md](references/packages.md) | Creating packages |

---

## Templates

| Template | Purpose |
|----------|---------|
| [UserService.php.md](references/templates/UserService.php.md) | Service + repository pattern |
| [AppServiceProvider.php.md](references/templates/AppServiceProvider.php.md) | DI bindings, bootstrapping |
| [ArtisanCommand.php.md](references/templates/ArtisanCommand.php.md) | CLI commands, signatures, I/O |
| [McpServer.php.md](references/templates/McpServer.php.md) | MCP servers, tools, resources, prompts |
| [PennantFeature.php.md](references/templates/PennantFeature.php.md) | Feature flags, A/B testing |
| [Envoy.blade.php.md](references/templates/Envoy.blade.php.md) | SSH deployment automation |
| [sail-config.md](references/templates/sail-config.md) | Docker Sail configuration |
| [octane-config.md](references/templates/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

```php
public function __construct(
    private readonly UserServiceInterface $userService,
) {}
```

### Service Provider Binding

```php
public function register(): void
{
    $this->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

### Updated stack
- **Symfony 7.4 and 8.0** supported side by side (HttpFoundation, Console, Mailer)
- **PHP 8.3 minimum** (8.2 dropped)
- **pda/pheanstalk 7.x / 8.x** required for the Beanstalk driver (5.x dropped)
- Current stable version: **13.33** (September 2026)

### Cache::touch() API
New method to refresh the TTL without recomputing the value.

```php
Cache::touch('user:123', 3600);
Cache::touch('user:123', now()->addHour());
```

### Queue::route() for dynamic routing
See [[laravel-queues]] for declarative routing per job class (`Queue::route(ProcessPodcast::class, connection: 'redis', queue: 'podcasts')`) and `Queue::forward()` (13.26+).

### Nested model boot → LogicException
Laravel 13 throws a `LogicException` when a model is instantiated during its own boot (`new static()` inside the model's `boot()` or a trait's `boot*()`). Move that logic out of the boot cycle.

### What's new in 13.x (13.1 → 13.33)
- **`php artisan dev`** (13.16+): runs the server, `queue:listen`, Pail and Vite in a single terminal; customizable via `Illuminate\Foundation\DevCommands::artisan('horizon', 'horizon')` in `AppServiceProvider::boot()`, listed via `php artisan dev:list` (requires Node 22.13+)
- **`#[BindWhen(Impl::class, static fn () => ...)]`** (13.22+): conditional binding declared on the interface — requires **PHP 8.5**
- Enum (`UnitEnum`) support in most managers (`Cache::store()`, `Queue`, `Log`, `Mail`, `Auth::guard()`…) (13.3 → 13.7)
- Guzzle 8 supported (13.26+)

## Migration Laravel 12 → 13

| Topic | Before (12) | After (13) |
|-------|-----------|------------|
| PHP minimum | 8.2 | **8.3** |
| PHPUnit | 11 | **12** (13 supported) |
| Pest | 3 | **4** (5 with PHP 8.4+) |
| CSRF | `VerifyCsrfToken` | **`PreventRequestForgery`** (origin check via `Sec-Fetch-Site`) |
| Cache prefix | underscore | **hyphens by default** (set `CACHE_PREFIX`, `REDIS_PREFIX`, `SESSION_COOKIE` for backward compatibility) |
| Beanstalk | pheanstalk 5.x | **pheanstalk 7.x / 8.x** |
| Symfony | 7.x | **7.4 / 8.0** |
| Model boot | tolerated | **nested instantiation during the model's boot → LogicException** |
| Config | — | new `cache.serializable_classes` (allowlist hardening, default `false`) |

```env
# Backward-compatible cache prefixes when upgrading from L12
CACHE_PREFIX=laravel_cache_
REDIS_PREFIX=laravel_database_
SESSION_COOKIE=laravel_session
```

```php
// config/cache.php — deserialization hardening
'serializable_classes' => [
    App\DTO\PaymentDto::class,
    App\DTO\OrderDto::class,
],
```

## Best Practices

### DO
- Use `final readonly class` for DTOs and Value Objects (PHP 8.3+)
- Inject via constructor promotion + `interface` (dependency inversion)
- Log via `Context::add()` to propagate metadata across jobs/requests
- Configure `serializable_classes` in production
- Prefer `app(Contract::class)` over `App::make()` (strict typing)

### DON'T
- Instantiate a model during its own boot (`new static()` inside `boot()` → LogicException in L13)
- Hardcode absolute paths (use `base_path()`, `storage_path()`)
- Mix Repository and Service (one per responsibility)
- Bypass the container with `new ConcreteClass()`
- Ignore the cache prefix change when upgrading from L12