Back to Details

solid-php

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

SOLID PHP - Laravel 12 + PHP 8.5

SOLID PHP - Laravel 12 + PHP 8.5

Agent Workflow (MANDATORY)

Agent工作流（强制要求）

Before ANY implementation, use 
TeamCreate
to spawn 3 agents:
  1. fuse-ai-pilot:explore-codebase - Analyze existing architecture
  2. fuse-ai-pilot:research-expert - Verify Laravel/PHP docs via Context7
  3. mcp__context7__query-docs - Check SOLID patterns
After implementation, run fuse-ai-pilot:sniper for validation.
在进行任何代码实现之前，请使用
TeamCreate
生成3个Agent：
  1. fuse-ai-pilot:explore-codebase - 分析现有架构
  2. fuse-ai-pilot:research-expert - 通过Context7校验Laravel/PHP官方文档
  3. mcp__context7__query-docs - 检查SOLID设计模式
实现完成后，运行fuse-ai-pilot:sniper进行校验。

DRY - Reuse Before Creating (MANDATORY)

DRY原则 - 编码前优先复用（强制要求）

Before writing ANY new code:
  1. Grep the codebase for similar class names, methods, or logic
  2. Check shared locations: 
    FuseCore/Core/App/Services/
    , 
    FuseCore/Core/App/Traits/
    , 
    FuseCore/[Module]/App/Contracts/
  3. If similar code exists → extend/reuse instead of duplicate
  4. If code will be used by 2+ features → create it in shared Services or Traits
  5. Extract repeated logic (3+ occurrences) into shared helpers or Traits
  6. Verify no duplication introduced after writing
在编写任何新代码之前：
  1. 检索整个代码库查找相似的类名、方法或逻辑
  2. 检查公共代码目录：
    FuseCore/Core/App/Services/
    、
    FuseCore/Core/App/Traits/
    、
    FuseCore/[Module]/App/Contracts/
  3. 如果存在相似代码 → 继承/复用而不是重复编写
  4. 如果代码会被2个以上功能使用 → 放在公共Services或Traits目录中
  5. 将重复出现3次以上的逻辑抽离为公共助手函数或Trait
  6. 编写完成后校验没有引入重复代码

Auto-Detection (Modular MANDATORY)

自动检测（模块化强制要求）

Files DetectedArchitectureInterfaces Location
FuseCore/
directory		FuseCore Modular
FuseCore/[Module]/App/Contracts/
module.json
in modules		FuseCore Modular
FuseCore/[Module]/App/Contracts/
Verification: 
php artisan --version
→ Laravel 12.x Structure: Always FuseCore modular. Shared in 
FuseCore/Core/App/
.
检测到的文件架构类型接口存放位置
FuseCore/
目录		FuseCore 模块化
FuseCore/[Module]/App/Contracts/
模块目录下存在 
module.json
FuseCore 模块化
FuseCore/[Module]/App/Contracts/
校验方式：
php artisan --version
→ 确认是Laravel 12.x 结构要求：始终采用FuseCore模块化结构，公共代码放在
FuseCore/Core/App/
目录下。

Decision Tree: Where to Put Code? (FuseCore Modular)

决策树：代码应该存放在哪里？（FuseCore模块化规范）

New code needed?
├── HTTP validation → FuseCore/[Module]/App/Http/Requests/
├── Single action → FuseCore/[Module]/App/Actions/
├── Business logic → FuseCore/[Module]/App/Services/
├── Data access → FuseCore/[Module]/App/Repositories/
├── Data transfer → FuseCore/[Module]/App/DTOs/
├── Interface → FuseCore/[Module]/App/Contracts/
├── Event → FuseCore/[Module]/App/Events/
└── Authorization → FuseCore/[Module]/App/Policies/
需要新增代码？
├── HTTP校验 → FuseCore/[Module]/App/Http/Requests/
├── 单一场景操作 → FuseCore/[Module]/App/Actions/
├── 业务逻辑 → FuseCore/[Module]/App/Services/
├── 数据访问 → FuseCore/[Module]/App/Repositories/
├── 数据传输 → FuseCore/[Module]/App/DTOs/
├── 接口定义 → FuseCore/[Module]/App/Contracts/
├── 事件 → FuseCore/[Module]/App/Events/
└── 权限校验 → FuseCore/[Module]/App/Policies/

Decision Tree: Which Pattern?

决策树：应该使用哪种设计模式？

NeedPatternLocationMax Lines
HTTP handlingControllerControllers/50
ValidationFormRequestRequests/50
Single operationActionActions/50
Complex logicServiceServices/100
Data accessRepositoryRepositories/100
Data structureDTODTOs/50
AbstractionInterfaceContracts/30
需求场景设计模式存放位置最大行数
HTTP请求处理ControllerControllers/50
请求参数校验FormRequestRequests/50
单一操作逻辑ActionActions/50
复杂业务逻辑ServiceServices/100
数据访问逻辑RepositoryRepositories/100
数据结构定义DTODTOs/50
抽象层定义InterfaceContracts/30

Critical Rules (MANDATORY)

核心规则（强制要求）

1. Files < 100 lines

1. 文件行数不超过100行

  • Split at 90 lines - Never exceed 100
  • Controllers < 50 lines
  • Models < 80 lines (excluding relations)
  • Services < 100 lines
  • 达到90行就拆分 - 绝对不能超过100行
  • Controller文件不超过50行
  • Model文件不超过80行（关联关系定义除外）
  • Service文件不超过100行

2. Interfaces Separated (FuseCore Modular MANDATORY)

2. 接口单独存放（FuseCore模块化强制要求）

FuseCore/[Module]/App/Contracts/   # Module interfaces ONLY
├── UserRepositoryInterface.php
└── PaymentGatewayInterface.php
FuseCore/Core/App/Contracts/       # Shared interfaces
FuseCore/[Module]/App/Contracts/   # 仅存放当前模块的接口
├── UserRepositoryInterface.php
└── PaymentGatewayInterface.php
FuseCore/Core/App/Contracts/       # 存放公共接口

3. PHPDoc Mandatory

3. 强制要求编写PHPDoc

php
/**
 * Create a new user from DTO.
 *
 * @param CreateUserDTO $dto User data transfer object
 * @return User Created user model
 * @throws ValidationException If email already exists
 */
public function create(CreateUserDTO $dto): User
php
/**
 * Create a new user from DTO.
 *
 * @param CreateUserDTO $dto User data transfer object
 * @return User Created user model
 * @throws ValidationException If email already exists
 */
public function create(CreateUserDTO $dto): User

Reference Guide

参考指南

Concepts

概念

TopicReferenceWhen to consult
SOLID Overviewsolid-principles.mdQuick reference all principles
SRPsingle-responsibility.mdFile too long, fat controller/model
OCPopen-closed.mdAdding payment methods, channels
LSPliskov-substitution.mdInterface contracts, swapping providers
ISPinterface-segregation.mdFat interfaces, unused methods
DIPdependency-inversion.mdTight coupling, testing, mocking
Anti-Patternsanti-patterns.mdCode smells detection
Decisionsdecision-guide.mdPattern selection
PHP 8.5php85-features.mdModern PHP features
Structurelaravel12-structure.mdStandard Laravel
FuseCorefusecore-structure.mdModular architecture
主题参考文档适用场景
SOLID 总览solid-principles.md快速查阅所有SOLID原则
SRP 单一职责原则single-responsibility.md文件过长、Controller/Model过于臃肿时
OCP 开闭原则open-closed.md新增支付方式、渠道等扩展场景时
LSP 里氏替换原则liskov-substitution.md定义接口契约、切换服务提供商时
ISP 接口隔离原则interface-segregation.md接口过于臃肿、存在大量未使用方法时
DIP 依赖倒置原则dependency-inversion.md代码耦合度高、需要测试、Mock时
反模式anti-patterns.md检测代码坏味道时
决策指南decision-guide.md选择设计模式时
PHP 8.5php85-features.md查阅PHP新特性时
结构规范laravel12-structure.md标准Laravel项目参考
FuseCorefusecore-structure.md模块化架构参考

Templates

模板

TemplateWhen to use
code-templates.mdService, DTO, Repository, Interface
controller-templates.mdController, Action, FormRequest, Policy
refactoring-guide.mdStep-by-step migration from legacy code
模板适用场景
code-templates.mdService、DTO、Repository、Interface编写
controller-templates.mdController、Action、FormRequest、Policy编写
refactoring-guide.md从 legacy 代码逐步迁移重构

Forbidden

禁止行为

Anti-PatternDetectionFix
Files > 100 linesLine countSplit into smaller files
Controllers > 50 linesLine countExtract to Service
Interfaces in impl filesLocationMove to 
FuseCore/[Module]/App/Contracts/
Business logic in ModelsCode in modelExtract to Service
Concrete dependencies
new Class()
Inject via ModuleServiceProvider
Missing PHPDocNo doc blockAdd documentation
Missing strict_typesNo declareAdd to all files
Fat classes> 5 public methodsSplit responsibilities
Duplicated logicSame code in 2+ filesExtract to Service/Trait
No Grep before codingCreating without searchGrep codebase first
反模式检测方式修复方案
文件行数超过100行行数统计拆分为更小的文件
Controller行数超过50行行数统计将逻辑抽离到Service
接口定义放在实现类文件中文件位置检查移动到
FuseCore/[Module]/App/Contracts/
目录
业务逻辑写在Model中代码内容检查将逻辑抽离到Service
硬编码依赖具体实现检测
new Class()
写法		通过ModuleServiceProvider注入依赖
缺失PHPDoc检测是否存在文档块补充对应的文档说明
缺失strict_types声明检测文件头部声明所有文件顶部添加声明
类过于臃肿公共方法超过5个拆分职责到多个类
重复逻辑2个以上文件存在相同代码抽离到Service/Trait
编码前未检索代码库未检索就新增代码编码前先检索整个代码库

Best Practices

最佳实践

DODON'T
Use constructor property promotionUse property assignment
Depend on interfacesDepend on concrete classes
Use 
final readonly class
Use mutable classes
Use 
declare(strict_types=1)
Skip type declarations
Split at 90 linesWait until 100 lines
Use DTOs for data transferUse arrays
推荐做法禁止做法
使用构造函数属性提升语法手动编写属性赋值逻辑
依赖接口依赖具体实现类
使用
final readonly class
使用可变类
声明
declare(strict_types=1)
省略类型声明
达到90行就拆分等到100行才拆分
使用DTO进行数据传输使用数组传输数据