SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillslaravel-architecture

laravel-architecture

General & other

View repository

Updated 10-15 21:48

About this skill

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