Phạm vi các phương thức TCPDF trong NextPDF compat-legacy

Tổng quan nhanh

nextpdf/compat-legacy là một lớp tương thích, không phải bản fork của TCPDF hay bản sao hành vi có bảo đảm. Nó cung cấp tên các phương thức công khai, thứ tự tham số và giá trị mặc định của TCPDF 6.x trên nền lõi engine NextPDF. Hầu hết lệnh gọi được ánh xạ trực tiếp tới một thao tác NextPDF Document. Một số ít phương thức được xác định rõ là chấp nhận các tham số kế thừa mà NextPDF không xử lý, hoặc không có tác dụng.

Trang này tóm tắt kết quả kiểm tra theo từng phương thức cho người đọc. Ma trận phạm vi chính thức, đã được kiểm thử xác minh, nằm trong kho mã tại docs/TCPDF_COVERAGE.md. Nếu trang này và ma trận trong kho mã không thống nhất, ma trận trong kho mã có hiệu lực vì bộ kiểm thử xác nhận ma trận đó.

Hãy dùng trang này để trả lời một câu hỏi trước khi bạn di trú: với mỗi phương thức TCPDF mà mã của bạn gọi, adapter thực sự làm gì?

Tóm tắt phạm vi

Bản kiểm tra đã khảo sát khoảng 120 phương thức công khai của TCPDF 6.x. Mỗi phương thức được xếp vào đúng một trong bốn nhóm.

Nhóm	Số lượng	Điều này nghĩa là gì với bạn
Được phản chiếu — ủy quyền hoàn toàn	94	Lệnh gọi được ánh xạ trực tiếp tới một phương thức NextPDF `Document`. Hành vi tương thích với các tham số đã được ghi tài liệu.
Bỏ qua âm thầm — một phần	15	Phương thức vẫn chạy và tạo ra kết quả, nhưng một hoặc nhiều tham số TCPDF không có tác dụng. Đây là khác biệt hành vi đã được ghi tài liệu.
Chưa triển khai — thân hàm rỗng	4	Phương thức tồn tại để tương thích mã nguồn nhưng không làm gì cả.
Không áp dụng	7	Phương thức TCPDF không có tác dụng lên kết quả PDF; được loại trừ có chủ đích.
Các phương thức bổ sung do API hiện đại khác biệt	17	Các phương thức Document của NextPDF v5.1+ được cung cấp trên adapter để mã trộn nhiều API vẫn có thể biên dịch. Những phương thức này không có phương thức TCPDF 6.x tương đương.

Các con số này lấy từ docs/TCPDF_COVERAGE.md §Summary. Bộ kiểm thử xác minh ma trận thông qua tests/Unit/Compat/Tcpdf/TcpdfApiDriftTest.php và tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php.

Lưu ý về cách diễn đạt. Gói này không tuyên bố là một “bản thay thế cắm-vào-là-chạy (drop-in)” hay “tương thích (không phải byte-identical) với TCPDF”. Gói bao phủ 94 trong số khoảng 120 phương thức TCPDF được khảo sát bằng cách ủy quyền trực tiếp. Các phương thức còn lại có các khác biệt hành vi đã được ghi tài liệu, mô tả bên dưới. Mô tả chính xác là giải pháp thay thế tương thích với TCPDF với một bề mặt tương thích đã biết và đã được kiểm thử.

Một lưu ý về số lượng phương thức

Adapter được xây dựng từ 25 concern trait đơn-trách-nhiệm (src/Compat/Tcpdf/Concerns/) cung cấp tổng cộng 273 phương thức công khai, cộng thêm một số ít phương thức vòng đời và lối thoát (escape-hatch) trên chính lớp TCPDF. Các nhóm phạm vi ở trên đếm các phương thức riêng biệt trên bề mặt API của TCPDF 6.x (~120), không phải tổng số phương thức công khai của adapter. Hai con số đo những khía cạnh khác nhau: phạm vi bề mặt API và quy mô triển khai. Nếu tệp README.md của gói nêu số lượng trait hoặc phương thức nhỏ hơn, hãy coi docs/TCPDF_COVERAGE.md và trang này là nguồn chính thức. Phần tóm tắt trong README có trước trait AdaptsDriftV51.

1. Các phương thức được phản chiếu — ủy quyền tương thích

Chín mươi bốn phương thức được ánh xạ trực tiếp tới đối tượng NextPDF\Core\Document bên dưới. Các tên TCPDF kiểu PascalCase ánh xạ sang tên NextPDF kiểu camelCase ở những nơi engine dùng camelCase. Adapter chấp nhận cả hai cách viết để tương thích cả thuận lẫn nghịch.

Các nhóm tiêu biểu (bảng đầy đủ: docs/TCPDF_COVERAGE.md §1):

Vùng TCPDF	Phương thức ví dụ	Trait adapter
Vòng đời	`Output()`, `Close()`, `getPDFData()`	`AdaptsLifecycle`
Trang	`AddPage()`, `getNumPages()`, `deletePage()`	`AdaptsPageManagement`
Văn bản	`Cell()`, `MultiCell()`, `Write()`, `Text()`, `Ln()`	`AdaptsTextOutput`
Phông chữ	`SetFont()`, `SetFontSize()`, `AddFont()`	`AdaptsFonts`
Màu sắc	`SetTextColor()`, `SetDrawColor()`, `SetFillColor()`	`AdaptsColors`
Vẽ	`Line()`, `Rect()`, `Circle()`, `Polygon()`, `Arrow()`	`AdaptsDrawing`
Biến đổi	`Rotate()`, `Scale()`, `Translate()`, `Skew()`, `Mirror*()`	`AdaptsTransforms`
Điều hướng	`AddLink()`, `Annotation()`, `addTOC()`	`AdaptsNavigation`

Với các phương thức này, hành vi quan sát được tương thích với TCPDF 6.x đối với các tham số được NextPDF ghi tài liệu. Adapter không khẳng định kết quả PDF giống hệt từng byte. Engine bên dưới là một triển khai PDF 2.0 độc lập, nên byte có thể khác nhau ngay cả khi kết quả hiển thị là tương đương. Nếu các kiểm thử của bạn khẳng định chính xác byte PDF thay vì nội dung được kết xuất, hãy chuẩn bị thiết lập lại đường nền (rebaseline) cho các khẳng định đó. Xem /integrations/tcpdf-compat/migration/ để biết chiến lược thiết lập lại đường nền được khuyến nghị.

2. Các phương thức bỏ qua âm thầm — các khác biệt hành vi đã được ghi tài liệu

15 phương thức này vẫn chạy và tạo ra kết quả, nhưng ít nhất một tham số TCPDF được chấp nhận để tương thích mã nguồn rồi bị bỏ qua. Hãy đọc phần này trước khi di trú. Các lệnh gọi này không thất bại; chúng âm thầm làm ít việc hơn so với bản TCPDF gốc.

Phương thức TCPDF	Tham số bị bỏ qua	Giải pháp tương thích
`Image()`	type, link, align, resize, dpi, palign, ismask, imgmask, border, fitbox, hidden, fitonpage, alt, altimgs	NextPDF `image()` nhận file, x, y, width, height. Để tạo ảnh có thể nhấp, hãy vẽ ảnh rồi thêm `Document::link()` lên cùng hình chữ nhật đó. Mặt nạ ảnh (image masking) và ảnh thay thế không được hỗ trợ.
`writeHTML()`	ln, fill, reseth, cell, align	NextPDF `writeHtml()` chỉ xử lý nội dung. Hãy bọc HTML trong một khối được định vị bằng API hiện đại để kiểm soát bố cục.
`writeHTMLCell()`	border (dạng chuỗi), ln, fill, reseth, autopadding	Chiều rộng, chiều cao, vị trí và đường viền dạng boolean được tôn trọng; bố cục ô phức tạp hơn không có ánh xạ.
`ImageEps()`	link, useBoundingBox, align, palign, border, fitonpage, fixoutvals	Chỉ vị trí và kích thước.
`ImageSVG()`	link, align, palign, border, fitonpage	Chỉ vị trí và kích thước.
`SetProtection()`	mode (khác không), pubkeys (không rỗng)	NextPDF luôn dùng AES-256 cho handler chuẩn. Với mã hóa dựa trên chứng chỉ, hãy dùng `setPublicKeyEncryption()` hiện đại được cung cấp trên adapter (xem /integrations/tcpdf-compat/security-and-operations/).
`Bookmark()`	style, color, x, isNamedDest	Tiêu đề, cấp độ và vị trí y được tôn trọng.
`setDestination()`	page, x	Tên và vị trí y được tôn trọng.
`Link()`	spaces	Theo dõi khoảng trắng nội bộ của TCPDF; không có phương thức tương đương trong engine.
`Annotation()`	các khóa tùy chọn ngoài Subtype, spaces	Kiểu, vị trí và văn bản được tôn trọng.
`SetLineStyle()`	chi tiết mẫu nét đứt (dash-pattern) ngoài độ rộng	Các thuộc tính cốt lõi của đường nét được ánh xạ.
`setAlpha()`	ánh xạ một phần chế độ hòa trộn (blend-mode)	Một số tên chế độ hòa trộn không có phương thức tương đương trong engine.
`Polycurve()`	toàn bộ danh sách tham số	Không hoạt động (no-op) ở chế độ mặc định; không có phương thức tương đương trong engine.
`PieSectorXY()`	toàn bộ danh sách tham số	Ánh xạ một phần (các đường từ tâm tới vành khác nhau).
`RoundedRectXY()`	bán kính theo từng góc	Chỉ bán kính góc đồng nhất.

Cách adapter bộc lộ các khác biệt này phụ thuộc vào chế độ nghiêm ngặt (xem /integrations/tcpdf-compat/configuration/). Khi chế độ nghiêm ngặt tắt — mặc định để tương thích ngược — các lệnh gọi này suy giảm âm thầm. Khi chế độ nghiêm ngặt bật, mọi lệnh gọi bỏ qua một tham số sẽ ném TcpdfNotImplementedException kèm danh sách chính xác các tham số bị bỏ qua và một gợi ý di trú. Chế độ nghiêm ngặt là công cụ kiểm tra, không phải thiết lập cho môi trường sản xuất.

Thiết kế chế độ nghiêm ngặt tuân theo nguyên tắc rằng bên gọi phải quan sát được khi ý định của mình không được tôn trọng. OWASP ASVS 5.0 §16.5.3 nêu rằng các ứng dụng nên thất bại một cách nhẹ nhàng và an toàn và ngăn các tình huống thất bại theo hướng mở (fail-open). Mất tham số âm thầm là một cái bẫy về trải nghiệm lập trình viên chứ không phải một lỗ hổng, nhưng cùng nguyên tắc thất-bại-một-cách-rõ-ràng vẫn áp dụng. Bản tóm tắt điều khoản được ghim nằm trong phần front-matter citations của trang.

3. Các phương thức chưa triển khai — thân hàm rỗng

Bốn phương thức tồn tại để mã kế thừa có thể biên dịch, nhưng thân hàm không làm gì cả. Khi chế độ nghiêm ngặt bật, ba trong số đó ném TcpdfNotImplementedException. Phương thức thứ tư (Open()) là một no-op an toàn có chủ đích, không bao giờ ném ngoại lệ vì bạn luôn có thể gỡ nó khỏi mã kế thừa một cách an toàn.

Phương thức TCPDF	Hành vi	Phương án thay thế
`setSignature()`	No-op (không lưu trữ gì có thể dùng được). Ném ngoại lệ ở chế độ nghiêm ngặt.	Ký số yêu cầu một phiên bản thương mại của NextPDF. Hãy dùng API chữ ký hiện đại với một value object `CertificateInfo`; xem /integrations/tcpdf-compat/security-and-operations/.
`addEmptySignatureAppearance()`	No-op. Ném ngoại lệ ở chế độ nghiêm ngặt.	Cùng cổng phiên-bản-thương-mại như `setSignature()`.
`endPage()`	No-op. Ném ngoại lệ ở chế độ nghiêm ngặt.	NextPDF quản lý vòng đời trang một cách tự động. Hãy gỡ bỏ lệnh gọi.
`Open()`	No-op an toàn. Không bao giờ ném ngoại lệ.	NextPDF tự động mở tài liệu. Gỡ bỏ lệnh gọi luôn an toàn.

Ký số không khả dụng trong lõi engine thông qua adapter này. Adapter cung cấp một điểm vào chữ ký hiện đại, ủy quyền cho engine. Hỗ trợ chữ ký nền tảng (baseline) được giới hạn cho một phiên bản thương mại. Tài liệu này không đưa ra tuyên bố nào về các hồ sơ chữ ký xác thực-dài-hạn (long-term-validation) hoặc có dấu thời gian cho bất kỳ phiên bản nào. Xem /integrations/tcpdf-compat/security-and-operations/ để biết tuyên bố chính xác và thận trọng.

4. Các phương thức không áp dụng

Bảy phương thức TCPDF không có tác dụng lên kết quả PDF và được loại trừ có chủ đích. Bạn có thể gọi chúng an toàn.

Phương thức TCPDF	Lý do loại trừ
`setDocCreationTimestamp()` / `setDocModificationTimestamp()`	Trạng thái được giữ trên adapter nhưng không được đưa vào siêu dữ liệu XMP của tài liệu. Không hiển thị trong kết quả.
`setSRGBmode()`	Quản lý màu của NextPDF độc lập với cờ này.
`setPDFVersion()`	NextPDF chọn phiên bản PDF từ hồ sơ conformance/output của nó; không có hàm thiết lập trực tiếp. Adapter phát ra một thông báo và tiếp tục.
`setDocInfoUnicode()`	NextPDF luôn là Unicode; cờ này là một no-op theo thiết kế.
`setDefaultMonospacedFont()`	Không có phương thức tương đương trong engine; thay vào đó áp dụng định kiểu HTML/CSS.
`setFontSubsetting()`	NextPDF luôn tạo tập con (subset) các phông chữ được nhúng; cờ này thực tế luôn bật.

Phiên bản PDF do engine cố định. Kết quả được ghi dưới dạng PDF 2.0 (ISO 32000-2). ISO 32000-2 §7.5.2 quy định rằng một bộ ghi tuân thủ phải nhận diện phiên bản tài liệu — trong phần đầu tệp hoặc mục Version của catalog — là 2.0. Điều khoản này cũng quy định rằng việc lưu một tệp không làm hạ thấp phiên bản của tệp. Điều đó khớp với hành vi của adapter: các lệnh gọi như setPDFVersion('1.4') không thể hạ mục tiêu xuống một phiên bản PDF cũ hơn thông qua adapter này. Bản tóm tắt điều khoản được ghim nằm trong phần front-matter citations của trang.

5. Các phương thức bổ sung do API hiện đại khác biệt

Mười bảy phương thức từ lõi NextPDF v5.1+ được cung cấp trên adapter (trait AdaptsDriftV51) để mã trộn API TCPDF với API hiện đại vẫn biên dịch được. Những phương thức này không có phương thức TCPDF 6.x tương đương. Ví dụ: getWarnings(), hasWarnings(), embedFileFromString(), enableBiDi(), beginTag() / endTag(), enableLinearization(), useAesGcm(), useDocumentMac(), setConformanceMode(). Hãy xem chúng là API hiện đại, không phải một phần của hợp đồng tương thích TCPDF.

6. Hướng dẫn về trạng thái không dùng nữa và thay thế

Nếu mã của bạn gọi…	Trạng thái	Hãy làm điều này thay thế
`Error()`	Hành vi đã thay đổi (được làm chặt hơn)	Adapter thay thế `die()` của TCPDF bằng việc ném một `RuntimeException`. Hãy bọc các lệnh gọi rủi ro trong `try`/`catch`; đừng dựa vào việc kết thúc tiến trình.
`setPDFVersion()`	Không áp dụng	Gỡ bỏ. Kết quả luôn là PDF 2.0.
`setUserRights()`	Không dùng nữa trong PDF 2.0	Gỡ bỏ. Lệnh gọi phát ra một thông báo `E_USER_DEPRECATED` và bị bỏ qua.
`setSignature()`	Chưa triển khai trong lõi	Chuyển sang API chữ ký hiện đại trên một phiên bản thương mại.
`Image(...)` với các tham số bổ sung	Bỏ qua âm thầm	Rút gọn còn file, x, y, w, h; thêm `Document::link()` cho ảnh có thể nhấp.
`endPage()` / `Open()`	Chưa triển khai / no-op	Gỡ bỏ.

7. Các bước di trú an toàn

Cài đặt gói và chạy bộ kiểm thử hiện có của bạn với adapter mà không thay đổi mã. Xem /integrations/tcpdf-compat/install/ và /integrations/tcpdf-compat/quickstart/.
Bật chế độ nghiêm ngặt trong một lần chạy kiểm tra riêng (không phải trong môi trường sản xuất): $pdf->setStrictMode(true);. Thu thập từng TcpdfNotImplementedException. Mỗi ngoại lệ nêu rõ các tham số chính xác bị bỏ qua và một gợi ý di trú.
Với mỗi vị trí ném ngoại lệ, hãy chọn bỏ tham số bị bỏ qua hoặc chuyển lệnh gọi đó sang API hiện đại qua $pdf->getDocument().
Thiết lập lại đường nền cho bất kỳ kiểm thử nào khẳng định chính xác byte PDF; thay vào đó, hãy khẳng định trên nội dung được kết xuất hoặc các thuộc tính cấu trúc.
Tắt chế độ nghiêm ngặt và triển khai luồng mã đã được kiểm tra. Hãy duy trì một tác vụ CI chạy chế độ nghiêm ngặt định kỳ để bắt hồi quy khi bạn tái cấu trúc.

Quy trình đầy đủ kèm mã nằm tại: /integrations/tcpdf-compat/migration/.

Xem thêm

docs/TCPDF_COVERAGE.md — ma trận phạm vi chính thức, đã được kiểm thử xác minh (trong kho mã)
/integrations/tcpdf-compat/migration/ — chiến lược di trú từ đầu đến cuối từ TCPDF sang NextPDF
/integrations/tcpdf-compat/configuration/ — chế độ nghiêm ngặt và cấu hình adapter
/integrations/tcpdf-compat/security-and-operations/ — trạng thái mã hóa và chữ ký
/integrations/tcpdf-compat/integration/ — nối adapter vào ứng dụng
/integrations/tcpdf-compat/boot-and-discovery/ — đăng ký alias lớp và cung cấp facade