贡献指南

我们欢迎各种形式的贡献 — 错误报告、文档改进、功能提案与代码。本页摘要说明流程。完整的贡献者协议与详细指南请参见 GitHub 上的 CONTRIBUTING.md。

开发环境配置

前置需求

需求	最低版本
PHP	8.5+
Composer	2.x
PHPUnit	12.x
PHPStan	2.x

开始

# 克隆仓库
git clone https://github.com/yeeefang/tcpdf-next.git
cd tcpdf-next

# 安装依赖包
composer install

# 验证一切正常
composer test

运行测试

TCPDF-Next 使用 PHPUnit 12，分为单元测试与集成测试套件。

# 运行完整测试套件
composer test

# 只运行单元测试（快速、无 I/O）
composer test:unit

# 只运行集成测试（文件输出、字体加载等）
composer test:integration

所有测试必须通过才能合并 Pull Request。CI 流程在每次推送时执行完整套件。

静态分析

代码库使用 PHPStan level 8（最严格等级）进行分析：

composer analyse

零错误容忍。如果你的变更引入 PHPStan 错误，CI 构建将会失败。

代码风格要求

• 每个 PHP 文件顶部 declare(strict_types=1)。
• PHPStan level 8 合规 — 新代码不接受 baseline 例外。
• 不需要可变状态时，优先使用只读类。
• 所有有限值集合使用具值枚举（不使用魔术字符串或整数常量）。
• 公开 API 方法使用具名参数以提高清晰度。
• 禁止 mixed 类型 — 每个参数、返回类型和属性必须明确标注类型。
• 默认 final — 除非设计为可扩展，类一律为 final。

Pull Request 流程

1. Fork 仓库，从 main 创建功能分支。

2. 先写测试 — TCPDF-Next 采用 TDD 导向工作流。新功能和错误修正必须包含对应的测试。

3. 保持提交聚焦 — 每个提交一个逻辑变更。撰写清晰的提交信息。

4. 推送前运行完整检查套件：

   composer analyse && composer test

5. 对 main 创建 Pull Request。填写 PR 模板：

   • 变更描述及动机。
   • 相关 Issue 链接（使用 Closes #123 语法）。
   • 任何破坏性变更或迁移注意事项。

6. 回应审查反馈 — 维护者可能要求修改。请回应或讨论每则评论。

报告错误

创建 GitHub Issue，包含：

• PHP 版本与操作系统。
• TCPDF-Next 版本（composer show yeeefang/tcpdf-next）。
• 最小复现代码。
• 预期行为 vs. 实际行为。

安全漏洞

请勿通过公开 GitHub Issue 报告安全问题。请改用 GitHub Security Advisories。详见常见问题。

致谢

每一份贡献都让 TCPDF-Next 变得更好。无论你修正文档中的错字还是实现重大功能，你的时间和努力都真诚地受到感谢。