README

ThinkPHP 通用工具扩展包（HTTP / 支付 / 上传 / 缓存锁 / 加密 / 第三方服务封装）。

单元测试约定

包内所有单元测试统一使用 PHPUnit，用例类放在 tests/ 目录（*Test.php，命名空间 yicmf\tools\tests，统一继承 yicmf\tools\tests\TestCase 基类）。

运行方式（用带 bcmath / openssl / mbstring 等扩展的 PHP，如项目的 D:\phpEnv\php\php-8.3\php.exe）：

# 项目根目录执行
php vendor/bin/phpunit -c vendor/yicmf/tools/phpunit.xml

# 仅跑依赖外网的真实请求用例（默认排除）
php vendor/bin/phpunit -c vendor/yicmf/tools/phpunit.xml --group network

说明：

• tests/bootstrap.php 负责引导：优先加载宿主项目 composer autoload，并在 PHPUnit 安装错误处理器之前完成 think 框架初始化（FlowSn / RedisLock / UploadService 等依赖框架的用例通过 requireFramework() 引导，失败时自动跳过）。
• 基类 TestCase 提供 protected 成员反射访问（invokeProtected / getProtected / setProtected）、assertThrows() 异常断言与框架引导。
• 依赖外网真实请求的用例标注 @group network，默认在 phpunit.xml 中排除。
• 依赖特定扩展（bcmath / openssl / mbstring）或外部服务的用例在 setUp() 中检测并 markTestSkipped()。
• 不再新增脚本式断言测试（自写 assert + exit code），一律走 PHPUnit。

代码覆盖率（需 ext-pcov 或 ext-xdebug）

日常回归不采集覆盖率；需要覆盖率时用单独的 phpunit.coverage.xml（两套配置并存、互不影响）：

# 在包根目录执行；phpunit 二进制取宿主项目的（本包目录内没有可用的 vendor/bin）
php -d pcov.directory="<本包绝对路径>/src" \
    "<项目绝对路径>/vendor/phpunit/phpunit/phpunit" \
    -c phpunit.coverage.xml --coverage-text

# 生成可浏览的 HTML 报告（输出到 outputs/coverage_html/）
php -d pcov.directory="<本包绝对路径>/src" \
    "<项目绝对路径>/vendor/phpunit/phpunit/phpunit" \
    -c phpunit.coverage.xml --coverage-html outputs/coverage_html

⚠️ 两个必须，漏一个覆盖率就是 0%：

1. pcov.directory 必须显式传 —— pcov 默认只采样自己 pcov.directory 下的文件， 不传就采不到，--coverage-text 会打出 Lines: 0.00% (0/6949)。
2. 必须用 tests/bootstrap-coverage.php —— PHPUnit 从宿主项目 vendor 启动时， 项目 autoload 会把 yicmf\tools\ 解析到 vendor/yicmf/tools/src/；该引导前置注册了 指向本包 src/ 的自动加载器，否则 <source> 指到 src/ 也采不到行。

基线（2026-09-21，504 tests）：Classes 20.90%、Methods 34.39%、Lines 42.68%； QrCode 为 Methods 67.16% / Lines 88.36%。覆盖率低的大多是依赖外网 / 微信 token / 支付宝证书的类。