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');