SuperAPI AI 工具集

solid-php

编程与开发

查看项目

更新于 10-26 16:21

技能介绍

用途

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。

关键规则

  1. 文件行数须在 FUSE_SOLID_MAX_LINES 以内,且应明显低于上限,不得绕开限制;控制器只处理 HTTP 关注点,模型只放关联与类型转换,服务只放业务逻辑。
  2. 接口分离:模块接口仅放 FuseCore/[Module]/App/Contracts/,共享接口放 FuseCore/Core/App/Contracts/。
  3. 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
    {
        // ...
    }
}

限制

资料未提供该技能的安装命令、收费信息、支持的代理平台范围及实际使用效果数据,这些内容暂未提供。