Hướng dẫn nâng cấp

TCPDF-Next hiện đang ở dòng release 1.x. Trang này giải thích chính sách versioning và cách cập nhật.

Semantic Versioning

TCPDF-Next tuân theo Semantic Versioning 2.0.0:

Loại nâng cấp	Ý nghĩa	An toàn để cập nhật?
Patch (1.0.x)	Sửa lỗi, tài liệu, refactor nội bộ	Có — hoàn toàn tương thích ngược
Minor (1.x.0)	Tính năng mới, bổ sung không phá vỡ	Có — không cần thay đổi code hiện có
Major (x.0.0)	Thay đổi API gây phá vỡ	Đọc hướng dẫn di chuyển trước

Trong dòng 1.x, API công khai được coi là ổn định. Mọi thay đổi gây phá vỡ sẽ được giữ cho bản major tiếp theo kèm hướng dẫn di chuyển chi tiết.

Kiểm tra Changelog

Trước khi nâng cấp, xem CHANGELOG trên GitHub. Mỗi release liệt kê:

• Added — tính năng và class mới
• Changed — thay đổi hành vi hiện có
• Deprecated — API sẽ bị loại bỏ ở phiên bản major tiếp theo
• Fixed — sửa lỗi
• Security — bản vá lỗ hổng bảo mật (nâng cấp ngay)

Cập nhật qua Composer

# Cập nhật lên phiên bản tương thích mới nhất theo constraint
composer update yeeefang/tcpdf-next

# Hoặc ghim phiên bản cụ thể
composer require yeeefang/tcpdf-next:^1.2

Sau khi cập nhật, chạy test suite để xác minh:

composer test

Di chuyển từ thư viện khác

Nếu bạn đến từ thư viện PDF khác, các hướng dẫn sau sẽ giúp bạn ánh xạ các khái niệm quen thuộc sang TCPDF-Next:

Từ TCPDF cũ

TCPDF-Next không phải là fork. Đây là bản viết lại hoàn toàn từ đầu với API mới hoàn toàn. Khác biệt chính:

• Hằng số cấu hình static thay bằng typed enum và value object.
• Global state được loại bỏ — mỗi instance Document là độc lập.
• Tất cả class là readonly khi có thể, với declare(strict_types=1) nghiêm ngặt.
• Yêu cầu PHP 8.5+ (xem Tại sao PHP 8.5?).

Từ FPDF / FPDI

Các method cell/multiCell/text/write có tên cố ý tương tự, nên đường cong học tập là tối thiểu. Khác biệt chính:

• Named parameter và enum thay thế cờ số nguyên theo vị trí.
• Output dùng enum OutputDestination thay vì chuỗi ký tự đơn.
• Quản lý font qua FontConfig thay vì đặt file thủ công.

Từ Dompdf / wkhtmltopdf

Nếu bạn quen chuyển đổi HTML-to-PDF, xem package Artisan cung cấp pipeline render CSS3 đầy đủ trên nền TCPDF-Next Core. Để xây dựng PDF theo chương trình, cách tiếp cận API trong Sử dụng cơ bản sẽ hiệu suất và dự đoán được hơn so với tạo dựa trên HTML.