laravel-architecture

<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

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

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.

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)

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

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