dev-guide

name	dev-guide
description	Use when developing, testing, or adding new providers to yansongda/pay project. Covers commands, code standards, and provider implementation guide.

yansongda/pay 开发指南

开发命令

对 src/ PHP 代码的任何修改，需运行以下三项检查：

composer cs-fix && composer analyse && composer test

测试

composer test       # PHPUnit 11.x + Mockery 1.6

• 测试前需安装 hyperf/pimple
• Mock HTTP 客户端避免真实请求

代码风格

composer cs-fix     # 代码格式化检查（dry-run）

静态分析

composer analyse    # PHPStan

文档

cd web && pnpm web:dev    # 文档开发
cd web && pnpm web:build  # 文档构建
cd web && pnpm web:serve  # 本地预览

本地开发环境

优先本地 PHP 环境；若无 PHP，使用 Container 作为备选，详见 container-dev Skill。

CI 矩阵

PHP 8.2-8.5 + Laravel/Hyperf/Default

---

代码规范

• declare(strict_types=1); 必须
• use 导入，禁止 \Yansongda\Pay\...
• 日志/异常消息用中文
• 命名：{Action}Plugin.php、{Action}Shortcut.php、{Provider}Trait.php

---

新增 Provider 流程

6 阶段

1. 配置：src/Config/{Provider}Config.php
2. 核心类：src/Provider/{Provider}.php + src/Service/{Provider}ServiceProvider.php（继承 AbstractServiceProvider）
3. 插件：src/Plugin/{Provider}/V{n}/（含 CallbackPlugin）
4. 快捷方式：src/Shortcut/{Provider}/{Action}Shortcut.php
5. Trait：src/Traits/{Provider}Trait.php（get{Provider}Url、verify{Provider}Sign）
6. 注册：Pay.php + Config.php 映射 + Exception.php 常量 + 测试 + 文档

---

常见错误

• 忽略 declare(strict_types=1);
• 直接写完整命名空间
• 回调未验签
• 测试未 Mock HTTP 客户端