laravel-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Laravel Architecture Patterns

Laravel 架构模式

Agent Workflow (MANDATORY)

Agent 工作流（强制要求）

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.

在开始任何实现工作前，使用

TeamCreate

生成3个Agent：

fuse-ai-pilot:explore-codebase - 分析现有架构
fuse-ai-pilot:research-expert - 通过Context7验证Laravel模式
mcp__context7__query-docs - 检查服务容器和DI模式

实现完成后，运行fuse-ai-pilot:sniper进行验证。

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.

Laravel架构专注于关注点清晰分离、依赖注入和可维护的代码组织。本技能涵盖从项目结构到生产部署的所有内容。

When to Use

适用场景

Structuring new Laravel projects
Implementing services, repositories, actions
Setting up dependency injection
Configuring development environments
Deploying to production

构建新的Laravel项目
实现服务、仓库、动作
配置依赖注入
配置开发环境
部署到生产环境

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

轻量控制器 - 将业务逻辑委托给服务
接口存放于app/Contracts/ - 绝不要与实现代码放在一起
优先使用DI而非Facades - 使用构造函数注入以提升可测试性
文件行数<100行 - 按照SOLID原则拆分较大文件
环境分离 - .env文件绝不提交到版本控制

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

text

app/
├── Actions/              # 单一职责的动作类
├── Contracts/            # 接口（用于DI）
├── DTOs/                 # 数据传输对象
├── Enums/                # PHP 8.1+ 枚举
├── Events/               # 领域事件
├── Http/
│   ├── Controllers/      # 轻量控制器
│   ├── Middleware/       # 请求过滤器
│   ├── Requests/         # 表单验证
│   └── Resources/        # API 数据转换
├── Jobs/                 # 队列任务
├── Listeners/            # 事件处理器
├── Models/               # 仅包含Eloquent模型
├── Policies/             # 授权策略
├── Providers/            # 服务注册
├── Repositories/         # 数据访问层
└── Services/             # 业务逻辑层

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

参考文档	适用场景
container.md	依赖注入、绑定、解析
providers.md	服务注册、初始化
facades.md	静态代理、实时Facades
contracts.md	接口、松耦合
structure.md	目录组织
lifecycle.md	请求处理流程

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

参考文档	适用场景
configuration.md	环境配置、配置文件
installation.md	新项目初始化
upgrade.md	版本升级、破坏性变更
releases.md	发布说明、版本管理

Development Environments

开发环境

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

参考文档	适用场景
sail.md	Docker开发环境
valet.md	macOS原生开发环境
homestead.md	Vagrant（遗留方案）
octane.md	高性能服务器

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

参考文档	适用场景
artisan.md	CLI命令、自定义命令
helpers.md	全局辅助函数
filesystem.md	文件存储、S3、本地存储
processes.md	Shell命令执行
context.md	请求作用域数据共享

Advanced Features

高级特性

Reference	When to Use
pennant.md	Feature flags
mcp.md	Model Context Protocol
concurrency.md	Parallel execution

参考文档	适用场景
pennant.md	功能开关
mcp.md	模型上下文协议（Model Context Protocol）
concurrency.md	并行执行

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

参考文档	适用场景
deployment.md	生产环境部署
envoy.md	SSH任务自动化
logging.md	日志通道、格式化
errors.md	异常处理
packages.md	扩展包开发

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

模板	用途
UserService.php.md	服务+仓库模式
AppServiceProvider.php.md	DI绑定、初始化
ArtisanCommand.php.md	CLI命令、签名、输入输出
McpServer.php.md	MCP服务器、工具、资源、提示词
PennantFeature.php.md	功能开关、A/B测试
Envoy.blade.php.md	SSH部署自动化
sail-config.md	Docker Sail配置
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

功能	参考文档	优先级
服务容器	container.md	高
服务提供者	providers.md	高
目录结构	structure.md	高
配置	configuration.md	高
初始化	installation.md	高
Octane（性能优化）	octane.md	高
Sail（Docker）	sail.md	高
Artisan CLI	artisan.md	中
部署	deployment.md	中
Envoy（SSH）	envoy.md	中
Facades	facades.md	中
契约（Contracts）	contracts.md	中
Valet（macOS）	valet.md	中
升级指南	upgrade.md	中
日志	logging.md	中
错误处理	errors.md	中
请求生命周期	lifecycle.md	中
文件系统	filesystem.md	中
辅助函数	helpers.md	低
Pennant（功能开关）	pennant.md	低
请求上下文	context.md	低
进程管理	processes.md	低
并发执行	concurrency.md	低
MCP	mcp.md	低
扩展包开发	packages.md	低
发布说明	releases.md	低
Homestead	homestead.md	低

Quick Reference

快速参考

Service Injection

服务注入

php

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

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

php

public function register(): void
{
    $this->app->bind(UserServiceInterface::class, UserService::class);
    $this->app->singleton(CacheService::class);
}

Artisan Command

Artisan 命令

shell

php artisan make:provider CustomServiceProvider
php artisan make:command ProcessOrders

shell

php artisan make:provider CustomServiceProvider
php artisan make:command ProcessOrders

Environment Access

环境变量访问

php

$debug = env('APP_DEBUG', false);
$config = config('app.name');

php

$debug = env('APP_DEBUG', false);
$config = config('app.name');