Agent Skills: Laravel Architecture Patterns

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 within FUSE_SOLID_MAX_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