solid-php

对 Laravel 13 + PHP 8.3+ 代码强制执行 SOLID 原则和 DRY：文件少于 100 行（达到 90 行时拆分），接口单独放在 FuseCore/[Module]/App/Contracts/（共享接口则放在 FuseCore/Core/App/Contracts/），并要求所有公共方法都必须编写 PHPDoc。自动检测 Laravel 与 FuseCore 模块化架构，并据此确定代码放置位置 （Controllers/Requests/Actions/Services/Repositories/DTOs/Contracts/Events/ Policies），同时检测反模式（臃肿的类、模型中的业务逻辑、依赖具体实现、缺少 strict_types），并针对每项 SOLID 原则（SRP/OCP/LSP/ISP/DIP）提供重构指导。

SOLID PHP - Laravel 13 + PHP 8.3

Agent 工作流（强制）

在进行任何实现之前，必须并行启动 3 个 Agent，每个调用一次 Agent，并指定 name：

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 - 先复用再创建（强制）

编写任何新代码之前：

1. 在代码库中使用 Grep 搜索类似的类名、方法或逻辑
2. 检查共享位置：FuseCore/Core/App/Services/、FuseCore/Core/App/Traits/、FuseCore/[Module]/App/Contracts/
3. 如果存在类似代码 → 扩展或复用，而不是重复创建
4. 如果代码将被 2 个或更多功能使用 → 在共享 Services 或 Traits 中创建
5. 将重复逻辑（出现 3 次或更多）提取到共享辅助工具或 Traits 中
6. 编写后确认没有引入重复代码

---

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

检测到的文件	架构	接口位置
FuseCore/ 目录	FuseCore 模块化架构	FuseCore/[Module]/App/Contracts/
模块中的 module.json	FuseCore 模块化架构	FuseCore/[Module]/App/Contracts/

验证：php artisan --version → Laravel 13.x 结构：始终采用 FuseCore 模块化架构。共享代码放在 FuseCore/Core/App/。

---

决策树：代码放在哪里？（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 处理	控制器	Controllers/	50
验证	FormRequest	Requests/	50
单项操作	Action	Actions/	50
复杂逻辑	服务	Services/	100
数据访问	Repository	Repositories/	100
数据结构	DTO	DTOs/	50
抽象	接口	Contracts/	30

---

关键规则（强制）

1. 文件少于 100 行

• 达到 90 行时拆分 - 绝不超过 100 行
• 控制器少于 50 行
• 模型少于 80 行（不包括关联关系）
• 服务少于 100 行

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

FuseCore/[Module]/App/Contracts/   # Module interfaces ONLY
├── UserRepositoryInterface.php
└── PaymentGatewayInterface.php
FuseCore/Core/App/Contracts/       # Shared interfaces

3. 必须编写 PHPDoc

/**
 * 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

---

参考指南

概念

主题	参考资料	何时查阅
SOLID 概览	solid-principles.md	快速查阅所有原则
SRP	single-responsibility.md	文件过长、控制器或模型臃肿
OCP	open-closed.md	添加支付方式、渠道
LSP	liskov-substitution.md	接口契约、替换提供方
ISP	interface-segregation.md	接口臃肿、存在未使用的方法
DIP	dependency-inversion.md	耦合紧密、测试、模拟
反模式	anti-patterns.md	检测代码异味
决策	decision-guide.md	选择模式
PHP 8.5	php85-features.md	现代 PHP 特性
结构	laravel12-structure.md	标准 Laravel
FuseCore	fusecore-structure.md	模块化架构

模板

模板	使用时机
code-templates.md	服务、DTO、Repository、接口
controller-templates.md	控制器、Action、FormRequest、Policy
refactoring-guide.md	从旧代码逐步迁移

---

禁止事项

反模式	检测方式	修正方法
文件超过 100 行	行数	拆分成更小的文件
控制器超过 50 行	行数	提取到 Service
在 impl 文件中定义接口	位置	移至 FuseCore/[Module]/App/Contracts/
模型中包含业务逻辑	模型中的代码	提取到 Service
依赖具体实现	new Class()	通过 ModuleServiceProvider 注入
缺少 PHPDoc	无文档块	添加文档说明
缺少 strict_types	无 declare	添加到所有文件
类臃肿	公有方法超过 5 个	拆分职责
逻辑重复	相同代码出现在 2 个或更多文件中	提取到 Service/Trait
编码前未使用 Grep	未搜索便创建	先搜索代码库

---

最佳实践

应做	不要做
使用构造函数属性提升	使用属性赋值
依赖接口	依赖具体类
使用 final readonly class	使用可变类
使用 declare(strict_types=1)	跳过类型声明
在 90 行处分拆	等到 100 行才拆分
使用 DTO 传输数据	使用数组

---

Laravel 13 说明

最低要求为 PHP 8.3

Laravel 13 要求 PHP 8.3（L12 为 8.2）。有助于遵循 SOLID 的特性：

• readonly 类：final readonly class UserDto（完全不可变）
• 类型化类常量：const int MAX_RETRIES = 3;
• #[\Override] 属性：显式声明覆盖父类方法（可捕获拼写错误）
• 原生 json_validate()（比 json_decode + try/catch 更快）
• 动态类常量获取：$class::{$name}

use Override;

final readonly class PaymentService implements PaymentContract
{
    public const int DEFAULT_TIMEOUT = 30;

    public function __construct(
        private StripeClient $stripe,
        private LoggerInterface $logger,
    ) {}

    #[Override]
    public function process(PaymentDto $payment): PaymentResult
    {
        // ...
    }
}

L13 更严格的 SOLID 规则

• 所有 DTO/Value Object 优先使用 final readonly class
• 每个继承的方法都使用 #[\Override]（在 CI 中捕获问题）
• 为常量指定类型（const string ROLE = 'admin';）