用途
solid-php 是一个供编码代理使用的 PHP 技能,目标是在 Laravel 13 / PHP 8.3+ 代码中应用 SOLID 原则,并约束文件规模、接口位置与 PHPDoc 规范。其资料同时覆盖 FuseCore 模块化目录结构下的代码放置规则。
强制工作流
资料要求在任何实现之前并行启动 3 个 Agent 调用(每次调用带名称):fuse-ai-pilot:explore-codebase 分析现有架构;fuse-ai-pilot:research-expert 通过 Context7 核对 Laravel/PHP 文档;mcp__context7__query-docs 检查 SOLID 模式。实现完成后运行 fuse-ai-pilot:sniper 进行校验。
DRY:先复用在创建
写任何新代码前:用 Grep 检索代码库中相似的类名、方法或逻辑;检查共享位置 FuseCore/Core/App/Services/、FuseCore/Core/App/Traits/、FuseCore/[Module]/App/Contracts/;若已存在相似代码则扩展复用而非复制;将被 2 个以上功能使用的代码放入共享 Services 或 Traits;将重复 3 次以上的逻辑抽取为共享 helper 或 Trait;编写后确认未引入重复。
架构自动识别
检测到 FuseCore/ 目录或模块中存在 module.json 时,采用 FuseCore Modular 架构,接口放在 FuseCore/[Module]/App/Contracts/。验证方式为 php artisan --version 输出 Laravel 13.x。共享代码位于 FuseCore/Core/App/。
代码放置决策
HTTP 校验 → Http/Requests/;单一操作 → Actions/;业务逻辑 → Services/;数据访问 → Repositories/;数据传输 → DTOs/;接口 → Contracts/;事件 → Events/;授权 → Policies/。模式选择:HTTP 处理用 Controller,校验用 FormRequest,单一操作用 Action,复杂逻辑用 Service,数据访问用 Repository,数据结构用 DTO,抽象用 Interface。
关键规则
- 文件行数须在 FUSE_SOLID_MAX_LINES 以内,且应明显低于上限,不得绕开限制;控制器只处理 HTTP 关注点,模型只放关联与类型转换,服务只放业务逻辑。
- 接口分离:模块接口仅放 FuseCore/[Module]/App/Contracts/,共享接口放 FuseCore/Core/App/Contracts/。
- PHPDoc 强制:公开方法须写明用途、@param、@return、@throws。
参考与模板
概念文档包括 solid-principles.md、single-responsibility.md、open-closed.md、liskov-substitution.md、interface-segregation.md、dependency-inversion.md、anti-patterns.md、decision-guide.md、php85-features.md、laravel12-structure.md、fusecore-structure.md。模板包括 code-templates.md(Service、DTO、Repository、Interface)、controller-templates.md(Controller、Action、FormRequest、Policy)、refactoring-guide.md(旧代码迁移)。
禁止项与修复
文件超过行数上限 → 拆分;控制器含业务逻辑 → 抽取到 Service;接口写在实现文件中 → 移至 Contracts;模型含业务逻辑 → 抽取到 Service;直接 new Class() → 通过 ModuleServiceProvider 注入;缺少 PHPDoc → 补充;缺少 strict_types → 所有文件添加;类过于臃肿(超过 5 个公开方法)→ 拆分职责;逻辑重复 → 抽取到 Service/Trait;编码前未 Grep → 先检索。
最佳实践
使用构造器属性提升、依赖接口而非具体类、使用 final readonly class、使用 declare(strict_types=1)、提前拆分文件、用 DTO 而非数组传输数据。
Laravel 13 说明
Laravel 13 最低要求 PHP 8.3。资料列出对 SOLID 友好的特性:readonly 类、类型化类常量(const int MAX_RETRIES = 3;)、#[\Override] 属性(声明覆写父类方法)、原生 json_validate()、动态类常量获取($class::{$name})。更严格的规则包括:DTO/值对象优先使用 final readonly class;每个继承方法加 #[\Override](可在 CI 中捕获);使用类型化常量。资料给出示例:
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
{
// ...
}
}
限制
资料未提供该技能的安装命令、收费信息、支持的代理平台范围及实际使用效果数据,这些内容暂未提供。