Tham khảo API tương thích TCPDF
Tổng quan
Phần tiêu đề “Tổng quan”Gói nextpdf/compat-legacy cung cấp một lớp chính, NextPDF\Compat\Tcpdf\TCPDF. Lớp này phản chiếu giao diện lập trình ứng dụng (API) công khai của TCPDF 6.x, nhưng kết xuất bằng engine NextPDF hiện đại. Gói này cũng bao gồm một bề mặt hỗ trợ nhỏ: LegacyBootstrap cho bí danh lớp toàn cục, bề mặt cấu hình AdaptationConfig/LegacyDefaults, các lớp bridge nội bộ cho output, khởi tạo, màu sắc, đơn vị và định dạng trang, cùng các exception tương thích. Hãy dùng gói này như một công cụ hỗ trợ di chuyển, không phải một phụ thuộc lâu dài. Bảng độ phủ phương thức là nguồn tham chiếu đầy đủ về trạng thái của các phương thức cũ. Trang này chỉ ghi lại những bề mặt mà mã ứng dụng nên phụ thuộc một cách có chủ đích.
Bắt đầu tại đây: Nếu bạn mới dùng gói này, hãy khởi tạo NextPDF\Compat\Tcpdf\TCPDF, thực hiện các lệnh gọi TCPDF quen thuộc (AddPage(), SetFont(), Cell()), rồi kết thúc bằng Output($name, $dest). Lớp này là điểm vào cho hầu hết nội dung bên dưới. Để có các điểm khởi đầu có thể chạy ngay, hãy xem Tác vụ thường gặp.
Tác vụ thường gặp
Phần tiêu đề “Tác vụ thường gặp”Đây là những tác vụ trong gói mà bạn sẽ dùng thường xuyên nhất. Mỗi khối đã được kiểm chứng đối chiếu với mã nguồn adapter và có thể chạy nguyên trạng.
Tạo một tệp Portable Document Format (PDF) bằng các lệnh gọi TCPDF quen thuộc, rồi thu tệp đó dưới dạng chuỗi để đưa vào hàng đợi, trả về trong phản hồi HTTP, hoặc lưu trữ:
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
use NextPDF\Compat\Tcpdf\TCPDF;
$pdf = new TCPDF('P', 'mm', 'A4');$pdf->SetTitle('Invoice 1234');$pdf->SetFont('helvetica', '', 12);$pdf->AddPage();$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');
$bytes = $pdf->Output('invoice.pdf', 'S');Nó làm gì: Dựng một tài liệu PDF 2.0 thông qua adapter mang hình dạng TCPDF. Lệnh gọi trả về các byte thô (%PDF...) vì đích 'S' định tuyến qua OutputBridge đến Document::getPdfData() thay vì in ra, nên có thể dùng an toàn bên trong worker hoặc controller.
Đăng ký các bí danh toàn cục một lần khi khởi động để chạy mã new \TCPDF(...) hiện có mà không cần sửa mã nguồn:
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
use NextPDF\Compat\Tcpdf\LegacyBootstrap;
LegacyBootstrap::enableAliases();
$pdf = new \TCPDF('P', 'mm', 'A4'); // resolves to the adapter$pdf->AddPage();$pdf->Cell(0, 10, 'Legacy call site, modern engine');$pdf->Output(__DIR__ . '/legacy.pdf', 'F');Nó làm gì: enableAliases() đăng ký \TCPDF theo cách bất biến (idempotent) (cùng các helper \TCPDF_STATIC/\TCPDF_FONTS/\TCPDF_COLORS/\TCPDF_IMAGES) chỉ khi những tên đó chưa được định nghĩa. Sau đó, mã cũ không cần thay đổi vẫn chạy trên adapter.
Kiểm tra một lượt di chuyển bằng cách phơi bày mọi tham số TCPDF mà adapter sẽ âm thầm bỏ qua:
<?php
declare(strict_types=1);
require __DIR__ . '/vendor/autoload.php';
use NextPDF\Compat\Tcpdf\Exception\TcpdfNotImplementedException;use NextPDF\Compat\Tcpdf\TCPDF;
$pdf = new TCPDF();$pdf->setStrictMode(true);$pdf->AddPage();$pdf->SetFont('helvetica', '', 12);
try { $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);} catch (TcpdfNotImplementedException $e) { fwrite(STDERR, $e->getMessage() . "\n"); // names every ignored parameter}Nó làm gì: Với setStrictMode(true), một lệnh gọi không thể tái tạo hành vi TCPDF sẽ ném TcpdfNotImplementedException và nêu tên mọi tham số bị bỏ qua. Điều này biến sự xuống cấp âm thầm thành danh sách việc cần xử lý khi di chuyển. Chỉ chạy chế độ này trong một lượt kiểm tra, không bao giờ trong môi trường production.
Adapter chính
Phần tiêu đề “Adapter chính”Bảng này là bề mặt adapter chuẩn. Hãy dùng bảng này để tìm lớp bạn khởi tạo (TCPDF), các phương thức chế độ nghiêm ngặt và lối thoát của lớp đó, cùng hợp đồng (contract) mà nó triển khai.
| Ký hiệu | Tham số | Hành vi mặc định | Trả về | Ném hoặc thất bại với | Ghi chú |
|---|---|---|---|---|---|
NextPDF\Compat\Tcpdf\TCPDF | Các tham số của constructor theo hình dạng TCPDF cũ thông qua ConstructorBridge. | Tạo một adapter được hỗ trợ bởi tài liệu NextPDF. | TCPDF | Các exception về xác thực constructor hoặc tính năng không được hỗ trợ. | Dùng trong quá trình di chuyển, không dùng cho mã NextPDF gốc mới. |
TCPDF::getDocument() | không có. | Trả về tài liệu NextPDF bên dưới. | NextPDF\Core\Document | dự kiến không có. | Dùng như một lối thoát cho mã di chuyển cần pha trộn các lệnh gọi cũ và gốc. |
TCPDF::getUnitConverter() | không có. | Trả về bộ chuyển đổi được tạo từ đơn vị cũ. | UnitConverter | dự kiến không có. | Dùng để chẩn đoán di chuyển, không dùng cho mã ứng dụng thông thường. |
TCPDF::setStrictMode(bool $enabled) | Cờ chế độ nghiêm ngặt. | Bật hoặc tắt việc thất bại tường minh đối với hành vi tương thích không được hỗ trợ. | static | dự kiến không có. | Hãy bật trong các lượt kiểm tra di chuyển. |
TCPDF::isStrictMode() | không có. | Trả về cờ chế độ nghiêm ngặt hiện tại. | bool | dự kiến không có. | Hữu ích trong các phép khẳng định kiểm thử. |
TCPDF các phương thức cũ | Khác nhau tùy phương thức. | Các phương thức được hỗ trợ ánh xạ tới các lệnh gọi tài liệu lõi; các phương thức không được hỗ trợ sẽ thất bại tường minh. | Khác nhau tùy phương thức. | TcpdfNotImplementedException hoặc UnsupportedFeatureException. | Hãy kiểm tra độ phủ phương thức trước khi dựa vào một phương thức. |
CompatAdapterInterface::getDocument() | không có. | Phương thức hợp đồng do TCPDF triển khai. | Document | dự kiến không có. | Cho phép công cụ truy cập tài liệu gốc. |
CompatAdapterInterface::Output(string $name = '', string $dest = '') | Tên tệp và đích cũ. | Ủy thác cho output bridge. | string | Lỗi ghi của lõi hoặc lỗi đích không được hỗ trợ. | Phản chiếu output của TCPDF cũ; lớp TCPDF::Output cụ thể cung cấp các giá trị mặc định 'doc.pdf'/'I'. |
Các nhóm phương thức cũ
Phần tiêu đề “Các nhóm phương thức cũ”Bảng này ánh xạ các họ phương thức TCPDF mà adapter bao phủ. Hãy xem nhanh bảng này để định vị một lệnh gọi cũ trước khi kiểm tra trạng thái chính xác của nó trong độ phủ phương thức.
| Nhóm | Ký hiệu tiêu biểu | Hành vi mặc định | Ghi chú |
|---|---|---|---|
| Vòng đời và output | Open(), Close(), Output(), getPDFData() | Duy trì vòng đời tài liệu mang hình dạng TCPDF trên một tài liệu gốc. | Hãy ưu tiên các API output gốc sau khi di chuyển. |
| Siêu dữ liệu | SetTitle(), SetAuthor(), SetSubject(), SetKeywords(), SetCreator() | Ánh xạ các bộ thiết lập siêu dữ liệu tới tài liệu bên dưới. | Hãy giữ việc chuẩn hóa siêu dữ liệu trong mã ứng dụng. |
| Trang và định vị | AddPage(), setPage(), lastPage(), GetX(), SetXY() | Chuyển đổi các đơn vị và tọa độ cũ thành các thao tác trang gốc. | Hãy kiểm tra trực quan việc định vị tuyệt đối sau khi di chuyển. |
| Lề và bố cục | SetMargins(), SetAutoPageBreak(), setCellPaddings(), getMargins() | Lưu trạng thái tương thích và ánh xạ các giá trị được hỗ trợ. | Hành vi ngắt trang phức tạp của TCPDF có thể cần xem xét thủ công. |
| Phông chữ và văn bản | SetFont(), AddFont(), Cell(), MultiCell(), Write(), Text() | Định tuyến các thao tác văn bản thông thường tới các API phông chữ và văn bản gốc. | Hãy kiểm tra hành vi CJK và mã hóa ký tự với các phông chữ production. |
| HTML | writeHTML(), writeHTMLCell(), fixHTMLCode() | Truyền HTML được hỗ trợ tới pipeline HTML gốc. | Bộ kết xuất gốc không phải là một bản sao TCPDF HTML đầy đủ. |
| Hình ảnh và vẽ | Image(), Line(), Rect(), Circle(), SetDrawColor() | Ánh xạ các thao tác đồ họa được hỗ trợ qua các thành phần của adapter. | Các định dạng vector hoặc định dạng đặc biệt không được hỗ trợ sẽ thất bại tường minh. |
| Điều hướng và chú thích | Bookmark(), AddLink(), SetLink(), Annotation() | Bảo toàn các lệnh gọi điều hướng thông thường ở những nơi đã được ánh xạ. | Hãy xác thực các đề cương (outline) và liên kết được tạo ra. |
| Bảo mật và chữ ký | SetProtection(), setSignature(), setTimeStamp(), setUserRights() | Bắc cầu các lệnh gọi bảo mật cũ được hỗ trợ tới các tính năng gốc. | Hãy coi output mật mã là một cổng xác minh riêng. |
| Biểu mẫu, mẫu, phép biến đổi | TextField(), startTemplate(), StartTransform(), Rotate(), Scale() | Triển khai các tập con được hỗ trợ và thất bại rõ ràng đối với hành vi không được hỗ trợ. | Hãy kiểm tra từng lệnh gọi với độ phủ phương thức trước khi triển khai. |
Bootstrap và cấu hình
Phần tiêu đề “Bootstrap và cấu hình”Hãy dùng bảng này khi bạn nối adapter vào luồng khởi động của ứng dụng, đăng ký các bí danh toàn cục, hoặc chọn giữa các hằng số cũ và AdaptationConfig hiện đại.
| Ký hiệu | Tham số | Hành vi mặc định | Trả về | Ném hoặc thất bại với | Ghi chú |
|---|---|---|---|---|---|
LegacyBootstrap::enableAliases() | không có. | Đăng ký các bí danh tương thích một lần. | void | Lỗi autoload hoặc môi trường. | Chỉ dùng khi mã cũ kỳ vọng các tên TCPDF tồn tại ở phạm vi toàn cục. |
LegacyBootstrap::isRegistered() | không có. | Báo cáo liệu các bí danh đã được đăng ký hay chưa. | bool | dự kiến không có. | Hữu ích trong các kiểm thử bootstrap. |
LegacyBootstrap::resetForTesting() | không có. | Xóa trạng thái đăng ký cho kiểm thử. | void | dự kiến không có. | Helper chỉ dùng cho kiểm thử. |
AdaptationConfig | Các cờ adapter và bộ điều khiển di chuyển. | Dùng các giá trị mặc định của gói khi bỏ qua. | AdaptationConfig | Các giá trị tùy chọn không hợp lệ. | Hãy giữ cấu hình tường minh trong các lượt kiểm tra di chuyển. |
AdaptationConfig::fromLegacyConstants() | không có. | Đọc các hằng số cũ đã biết và dựng một đối tượng cấu hình. | AdaptationConfig | Các giá trị hằng số cũ không hợp lệ. | Helper chuyển tiếp cho các ứng dụng cũ lớn. |
LegacyDefaults | không có. | Cung cấp các giá trị cũ mặc định. | Các giá trị mặc định. | dự kiến không có. | Nơi tập trung các giá trị mặc định tương thích. |
Bridge và helper
Phần tiêu đề “Bridge và helper”Các lớp chuyển đổi nội bộ này vận hành adapter. Hãy dùng bảng này khi bạn đóng góp độ phủ adapter hoặc chẩn đoán cách chuyển đổi một đối số cũ. Với mã ứng dụng hằng ngày, hãy ưu tiên bề mặt adapter công khai.
| Ký hiệu | Tham số | Hành vi mặc định | Trả về | Ném hoặc thất bại với | Ghi chú |
|---|---|---|---|---|---|
ConstructorBridge | Danh sách đối số của constructor cũ. | Chuẩn hóa các tùy chọn cũ thành cấu hình NextPDF. | Dữ liệu constructor. | Các giá trị đối số cũ không hợp lệ. | Được adapter dùng nội bộ. |
CellParameterAdapter | Các tham số cell của TCPDF. | Ánh xạ các đối số vị trí cũ tới các tùy chọn bố cục văn bản của lõi. | Các tham số đã được điều chỉnh. | Kích thước hoặc căn chỉnh không hợp lệ. | Hãy ưu tiên các phương thức lõi gốc trong mã mới. |
OutputBridge::dispatch(Document $document, string $filename, string $dest) | Tài liệu gốc, tên tệp và đích cũ. | Ánh xạ hành vi inline/download/save tới các API output của NextPDF. | string | Lỗi ghi của lõi; đích không được hỗ trợ. | Hãy xác thực tên tệp và thư mục gốc lưu trữ trước khi xuất. |
OutputBridge::resolveDestination(string $dest) | Mã đích cũ. | Chuyển đổi đích thành một đích output gốc. | OutputDestination | Lỗi đích không được hỗ trợ. | Giữ việc ánh xạ đích tập trung một chỗ. |
ColorTranslator | Các đối số màu của TCPDF. | Chuẩn hóa các dạng màu cũ. | Giá trị màu của lõi. | Các giá trị màu không hợp lệ. | Được các thành phần màu sắc và vẽ sử dụng. |
PageFormatResolver | Đầu vào định dạng trang cũ. | Ánh xạ các tên đã biết tới các kích thước trang của lõi. | Giá trị định dạng trang. | Định dạng không xác định. | Hãy dùng các kích thước trang gốc tường minh sau khi di chuyển. |
UnitConverter | Các giá trị và đơn vị đo lường cũ. | Chuyển đổi sang các đơn vị của lõi. | Giá trị số. | Đơn vị không hợp lệ. | Giúp bảo toàn hành vi bố cục cũ. |
Exception
Phần tiêu đề “Exception”Hãy dùng bảng này khi một lệnh gọi trong quá trình di chuyển thất bại rõ ràng. Bảng này tách các lỗi “không được triển khai” khỏi các lỗi “đã biết nhưng không được hỗ trợ” và nêu lộ trình khôi phục.
| Ký hiệu | Ý nghĩa | Khôi phục |
|---|---|---|
TcpdfNotImplementedException | Adapter chủ đích không triển khai phương thức cũ được yêu cầu. | Hãy thay lệnh gọi bằng API NextPDF gốc hoặc gỡ bỏ phần phụ thuộc. |
TcpdfNotImplementedException::forSilentIgnore() | Một lệnh gọi cũ trước đây sẽ bị bỏ qua nhưng được phơi bày để làm rõ việc di chuyển. | Hãy quyết định liệu hành vi no-op tường minh có chấp nhận được hay không. |
TcpdfNotImplementedException::forUnimplemented() | Một lệnh gọi cũ không có đường triển khai nào trong adapter. | Hãy thay lệnh gọi hoặc cô lập nó phía sau mã di chuyển. |
UnsupportedFeatureException | Tính năng cũ đã biết nhưng không được hỗ trợ trong ranh giới của adapter. | Hãy kiểm tra hướng dẫn di chuyển và cô lập tính năng phía sau một adapter của ứng dụng. |
UnsupportedFeatureException::forMethod() | Tạo một lỗi tính năng-không-được-hỗ-trợ riêng cho từng phương thức. | Dùng trong các đóng góp tương thích để duy trì thông điệp lỗi nhất quán. |
Ghi chú phát triển
Phần tiêu đề “Ghi chú phát triển”- Hãy coi adapter là một công cụ di chuyển. Mã mới nên nhắm trực tiếp tới các API NextPDF lõi.
- Hành vi không được hỗ trợ nên thất bại rõ ràng. Đừng bắt các exception tương thích rồi tiếp tục với một tài liệu không hoàn chỉnh, trừ khi ứng dụng chấp nhận rõ ràng rủi ro đó.
- Hãy giữ các thay đổi di chuyển nhỏ gọn và xác minh từng phương thức cũ với bảng độ phủ.