Đóng góp

Chúng tôi hoan nghênh mọi hình thức đóng góp — báo lỗi, cải thiện tài liệu, đề xuất tính năng và code. Trang này tóm tắt quy trình. Xem toàn bộ thỏa thuận đóng góp và hướng dẫn chi tiết tại CONTRIBUTING.md trên GitHub.

Thiết lập môi trường phát triển

Điều kiện tiên quyết

Yêu cầu	Phiên bản tối thiểu
PHP	8.5+
Composer	2.x
PHPUnit	12.x
PHPStan	2.x

Bắt đầu

# Clone repository
git clone https://github.com/yeeefang/tcpdf-next.git
cd tcpdf-next

# Cài dependency
composer install

# Xác minh mọi thứ hoạt động
composer test

Chạy test

TCPDF-Next dùng PHPUnit 12 với suite riêng cho unit test và integration test.

# Chạy toàn bộ test suite
composer test

# Chỉ chạy unit test (nhanh, không I/O)
composer test:unit

# Chỉ chạy integration test (file output, font loading, v.v.)
composer test:integration

Tất cả test phải pass trước khi pull request được merge. Pipeline CI chạy toàn bộ suite trên mỗi push.

Phân tích tĩnh

Codebase được phân tích bằng PHPStan ở Level 10 (mức nghiêm ngặt nhất):

composer analyse

Không chấp nhận bất kỳ error nào. Nếu thay đổi của bạn gây ra PHPStan error, CI build sẽ thất bại.

Yêu cầu về code style

• declare(strict_types=1) ở đầu mọi file PHP.
• Tuân thủ PHPStan Level 10 — không có baseline exception cho code mới.
• Ưu tiên readonly class khi không cần mutable state.
• Backed enum cho mọi tập hữu hạn giá trị (không dùng magic string hoặc integer constant).
• Named parameter trong method API công khai để rõ ràng.
• Không dùng mixed type — mọi parameter, return type và property phải được typed rõ ràng.
• Final theo mặc định — class là final trừ khi được thiết kế để mở rộng.

Quy trình Pull Request

1. Fork repository và tạo feature branch từ main.

2. Viết test trước — TCPDF-Next theo workflow hướng TDD. Tính năng mới và sửa lỗi phải kèm test tương ứng.

3. Giữ commit tập trung — một thay đổi logic mỗi commit. Viết commit message rõ ràng.

4. Chạy toàn bộ check suite trước khi push:

   composer analyse && composer test

5. Mở pull request vào main. Điền PR template với:

   • Mô tả thay đổi và lý do.
   • Link đến issue liên quan (dùng cú pháp Closes #123).
   • Mọi breaking change hoặc ghi chú di chuyển.

6. Phản hồi review feedback — maintainer có thể yêu cầu thay đổi. Vui lòng giải quyết hoặc thảo luận từng comment.

Báo lỗi

Mở GitHub Issue với:

• Phiên bản PHP và OS.
• Phiên bản TCPDF-Next (composer show yeeefang/tcpdf-next).
• Code tái tạo tối thiểu.
• Hành vi mong đợi so với thực tế.

Lỗ hổng bảo mật

Không báo cáo vấn đề bảo mật qua GitHub Issues công khai. Dùng GitHub Security Advisories thay thế. Xem FAQ để biết chi tiết.

Cảm ơn

Mọi đóng góp đều làm TCPDF-Next tốt hơn. Dù bạn sửa lỗi chính tả trong tài liệu hay triển khai tính năng lớn, thời gian và công sức của bạn được trân trọng thực sự.