Tổng quan về NextPDF compat-legacy

Tổng quan nhanh

nextpdf/compat-legacy là một giải pháp thay thế tương thích với TCPDF: một lớp tương thích cung cấp public API của TCPDF 6.x trên engine NextPDF Portable Document Format (PDF) 2.0. Nó chỉ có một nhiệm vụ: giúp mã vốn phụ thuộc vào TCPDF 6.x chạy trên engine NextPDF mà không cần viết lại, để bạn có thể di chuyển từng tệp một thay vì làm tất cả cùng lúc.

Nó không phải là bản fork của TCPDF, cũng không phải là bản sao đảm bảo giống hệt về hành vi. Đây là một bản triển khai độc lập giữ nguyên các chữ ký lệnh gọi của TCPDF. Cách mô tả chính xác là: nó bao phủ 94 trong số khoảng 120 phương thức TCPDF 6.x được khảo sát bằng cách ủy quyền trực tiếp, còn các phương thức còn lại có những khác biệt hành vi đã được ghi lại (xem /integrations/tcpdf-compat/method-coverage/).

Nó là gì

Một công cụ hỗ trợ di chuyển. Gói này thuộc họ compat của NextPDF. Nó giúp bạn rời khỏi một thư viện PDF cũ; nó không được tạo ra để trở thành một phụ thuộc lâu dài. Hãy xem nó như phần giàn giáo mà bạn sẽ tháo bỏ sau khi đã chuyển sang API hiện đại.
Một bộ điều hợp bề mặt API. Nó cung cấp tên lớp TCPDF, tên phương thức, thứ tự tham số và các giá trị mặc định của 6.2.13. Nó ủy quyền các lệnh gọi tới một thực thể NextPDF\Core\Document.
Một bản triển khai độc lập, theo phương pháp clean-room. Gói này không sao chép hay chuyển đổi mã nguồn, build artifact, dữ liệu phông chữ của TCPDF, hoặc bất kỳ biểu đạt có bản quyền nào khác. Nó chỉ dùng tên TCPDF để chỉ rõ khả năng tương tác. Tuyên bố chuẩn được nêu trong tệp NOTICE của gói.

Nó không phải là gì

Nó không phải là một “bản thay thế cắm-vào-là-chạy” cho đầu ra giống hệt từng byte. Với các phương thức được ủy quyền, kết quả nhìn thấy là tương thích, nhưng các byte PDF được kết xuất sẽ khác nhau vì bên dưới là một bản triển khai PDF 2.0 riêng biệt, độc lập.
Nó không “tương thích (không phải byte-identical) với TCPDF”. Một tập hợp phương thức xác định chấp nhận các tham số cũ mà engine không tuân theo, hoặc hoàn toàn không làm gì. Các phương thức này được liệt kê và kiểm thử — xem /integrations/tcpdf-compat/method-coverage/.
Bản thân nó không phải là một sản phẩm ký số hay lưu trữ. Chữ ký số và tuân thủ lưu trữ PDF/A chỉ có trong một phiên bản NextPDF thương mại. Tài liệu này không đưa ra bất kỳ tuyên bố nào về chữ ký được chứng nhận, được đảm bảo, hay có hiệu lực pháp lý.

Vì sao nên di chuyển thông qua một lớp tương thích

Việc viết lại mọi lệnh gọi TCPDF trong một ứng dụng lớn mang theo rủi ro và khó phát hành theo từng bước. Lớp tương thích cho phép bạn:

Thay đổi phụ thuộc, rồi chạy bộ kiểm thử hiện có để xác định phần nào vẫn hoạt động mà không cần sửa đổi.
Dùng strict mode như một phép kiểm tra để liệt kê mọi nơi mà hành vi của TCPDF không thể được tái tạo chính xác.
Di chuyển từng vị trí gọi đó sang API NextPDF hiện đại, từng nơi một, để ứng dụng luôn ở trạng thái có thể phát hành trong suốt quá trình.

Trạng thái cuối cùng là dùng API NextPDF\Core\Document hiện đại và đã gỡ bỏ lớp tương thích. Xem /integrations/tcpdf-compat/migration/ để biết chiến lược đầy đủ.

Bạn được lợi gì trên engine NextPDF

Khi bộ điều hợp ủy quyền một lệnh gọi TCPDF, lệnh gọi đó chạy trên một engine PDF 2.0 (ISO 32000-2), với khả năng mã hóa Advanced Encryption Standard (AES)-256 qua standard handler và độ an toàn kiểu PHPStan Level 10 trên toàn bộ bộ điều hợp. Đầu ra luôn được ghi dưới dạng PDF 2.0; bộ điều hợp không thể hạ mục tiêu xuống các phiên bản PDF cũ hơn (xem /integrations/tcpdf-compat/method-coverage/ §4).

Bộ điều hợp tăng cường bảo mật cho một số hành vi lịch sử của TCPDF 6.2.13:

Hành vi cũ	Hành vi của bộ điều hợp
`Error()` gọi `die()` và âm thầm kết thúc tiến trình	`Error()` ném ra `RuntimeException` — có thể quan sát và bắt được
Phương thức HTML có thể thực thi PHP từ markup	Lối thoát đó bị vô hiệu hóa — markup không thể kích hoạt việc thực thi PHP
`Output()` xuất trực tiếp và có thể làm hỏng bộ đệm đầu ra của worker	Đầu ra đi qua một cầu nối đích an toàn
Đệ quy header/footer không được bảo vệ	Được bảo vệ chống đệ quy

Phạm vi và các phiên bản

Lớp tương thích được phân phối trong bản core (nextpdf/compat-legacy, yêu cầu nextpdf/core ^3.0). Mã hóa qua standard handler có sẵn trong core. Chữ ký số và tuân thủ lưu trữ PDF/A yêu cầu một phiên bản NextPDF thương mại; bộ điều hợp có cung cấp các điểm vào, nhưng đường dẫn core không phải là một sản phẩm ký số. Xem /integrations/tcpdf-compat/security-and-operations/ để biết tuyên bố chính xác.

Đi tiếp đến đâu

/integrations/tcpdf-compat/install/ — cài đặt gói và xác minh liên kết engine.
/integrations/tcpdf-compat/quickstart/ — tạo tài liệu đầu tiên chạy được, có kiểm thử hỗ trợ.
/integrations/tcpdf-compat/method-coverage/ — xem chính xác từng phương thức TCPDF làm gì ở đây.
/integrations/tcpdf-compat/migration/ — lập kế hoạch chiến lược di chuyển từng tệp một.
/integrations/tcpdf-compat/configuration/ — cấu hình strict mode và các thiết lập của bộ điều hợp.
/integrations/tcpdf-compat/production-usage/ — chạy bộ điều hợp dưới tải và trong worker.
/integrations/tcpdf-compat/security-and-operations/ — xem xét mã hóa, trạng thái ký số, và việc tăng cường bảo mật.
/integrations/tcpdf-compat/troubleshooting/ — khắc phục các lỗi di chuyển thường gặp.
/integrations/tcpdf-compat/integration/ / /integrations/tcpdf-compat/boot-and-discovery/ — kết nối facade vào ứng dụng và đăng ký các alias lớp toàn cục.

Xem thêm

docs/TCPDF_COVERAGE.md — ma trận độ bao phủ chính thức (trong repo)
Tệp NOTICE của gói — tuyên bố về bản triển khai độc lập