Khắc phục sự cố với compat-legacy

Tổng quan nhanh

Hầu hết vấn đề khi di chuyển đều thuộc một vài mẫu sự cố quen thuộc. Mỗi mục bên dưới liệt kê triệu chứng, nguyên nhân và cách khắc phục. Khi chưa chắc chắn về một phương thức cụ thể, hãy xem /integrations/tcpdf-compat/method-coverage/ và ma trận chính thức trong kho lưu trữ docs/TCPDF_COVERAGE.md.

Trước đây quy trình dừng khi gặp lỗi PDF; giờ một ngoại lệ thoát ra ngoài

Triệu chứng. Đoạn mã trước đây từng dừng lại khi kết xuất lỗi, nhưng nay ném ra một RuntimeException không được bắt, khiến yêu cầu hoặc tác vụ báo lỗi.

Nguyên nhân. Các lệnh gọi Error() của TCPDF cũ sẽ gọi die(). Theo thiết kế, bộ chuyển đổi thay vào đó ném ra RuntimeException để lỗi có thể quan sát được.

Cách khắc phục. Hãy bọc các điểm vào của quá trình kết xuất bằng try/catch, rồi ánh xạ ngoại lệ vào hợp đồng lỗi của bạn. Đừng khôi phục hành vi die(). Xem /integrations/tcpdf-compat/production-usage/ § Xử lý lỗi.

`new \TCPDF()` vẫn phân giải về thư viện TCPDF thật

Triệu chứng. Bạn đã bật LegacyBootstrap::enableAliases() nhưng kết quả vẫn giống TCPDF cũ, hoặc hành vi không thay đổi.

Nguyên nhân. enableAliases() chỉ đăng ký bí danh khi chưa tồn tại lớp nào trùng tên. Nếu tecnickcom/tcpdf vẫn có thể được tự động nạp và lớp \TCPDF của nó được nạp trước, bí danh sẽ bị bỏ qua và mã của bạn vẫn tiếp tục dùng TCPDF cũ.

Cách khắc phục. Trong quá trình di chuyển, hãy dùng lệnh import tường minh theo từng tệp (use NextPDF\Compat\Tcpdf\TCPDF;) để mỗi điểm gọi đều rõ ràng. Hãy gỡ bỏ tecnickcom/tcpdf sau khi kiểm thử thông qua (xem /integrations/tcpdf-compat/migration/ Giai đoạn 5). Đừng chạy cả hai thư viện trong cùng một tiến trình khi bí danh toàn cục đang bật.

Một phương thức “hoạt động” nhưng tham số tôi truyền vào bị bỏ qua

Triệu chứng. Một lệnh gọi thành công và tạo ra tệp Portable Document Format (PDF), nhưng một tùy chọn bạn truyền vào (liên kết hình ảnh, căn lề, dots per inch (DPI), màu dấu trang, …) không có tác dụng.

Nguyên nhân. Phương thức này thuộc nhóm âm thầm bỏ qua. Nó chấp nhận tham số để tương thích mã nguồn, rồi bỏ qua tham số đó. Đây là hành vi đã được ghi nhận, không phải lỗi; xem /integrations/tcpdf-compat/method-coverage/ §2.

Cách khắc phục. Hãy chạy kiểm tra ở chế độ nghiêm ngặt để tìm mọi lệnh gọi như vậy:

<?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('logo.png', 10, 10, 50, 0, '', 'https://example.com');
} catch (TcpdfNotImplementedException $e) {
    // Message lists every ignored parameter and a migration hint.
    echo $e->getMessage(), "\n";
}

Sau đó, hãy bỏ tham số đó hoặc diễn đạt lại qua API hiện đại ($pdf->getDocument()), như được trình bày trong /integrations/tcpdf-compat/migration/ Giai đoạn 4.

`MultiCell()` luôn trả về giá trị là 1

Triệu chứng. Đoạn mã rẽ nhánh theo giá trị trả về của MultiCell() (ví dụ, để tính chiều cao đã dùng hoặc số dòng) chạy không đúng.

Nguyên nhân. Phương thức MultiCell() của bộ chuyển đổi trả về giá trị giữ chỗ để tương thích là 1, chứ không phải số ô hay số dòng đã kết xuất. Tương tự, Write() cũng trả về 0.

Cách khắc phục. Đừng rẽ nhánh dựa trên các giá trị trả về này. Nếu bạn cần chiều cao đã kết xuất, hãy tính nó từ getStringHeight() / getNumLines(), hoặc chuyển logic đó sang API hiện đại.

`setPDFVersion('1.4')` không tạo ra tệp PDF 1.4

Triệu chứng. Bạn yêu cầu một phiên bản PDF cũ hơn, nhưng kết quả vẫn là PDF 2.0.

Nguyên nhân. Bộ chuyển đổi luôn xuất ra PDF 2.0 (ISO 32000-2). setPDFVersion() nằm trong nhóm không áp dụng được; bộ chuyển đổi phát ra một thông báo và tiếp tục.

Cách khắc phục. Hãy gỡ bỏ lệnh gọi này. Nếu một bên tiêu thụ phía sau yêu cầu phiên bản PDF cũ hơn, hãy xử lý yêu cầu đó riêng; bộ chuyển đổi không thể hạ cấp phiên bản đích.

`setSignature()` không làm gì cả — tệp PDF không được ký

Triệu chứng. Bạn đã gọi setSignature() với một chứng chỉ, nhưng tệp PDF đầu ra lại không có chữ ký.

Nguyên nhân. Engine lõi không triển khai setSignature() thông qua bộ chuyển đổi này. Ở chế độ mặc định, đây là một thao tác rỗng; ở chế độ nghiêm ngặt, nó ném ra ngoại lệ.

Cách khắc phục. Việc ký yêu cầu phiên bản NextPDF thương mại và API chữ ký hiện đại. Xem /integrations/tcpdf-compat/security-and-operations/ § Chữ ký số. Đừng kỳ vọng lệnh gọi setSignature() cũ sẽ ký bất cứ thứ gì.

`Output()` làm hỏng phản hồi HTTP hoặc đầu ra của worker của tôi

Triệu chứng. Các byte PDF xuất hiện trong phản hồi Hypertext Transfer Protocol (HTTP), hoặc nhật ký của worker bị lẫn byte PDF.

Nguyên nhân. Bạn đã dùng một đích đầu ra ghi ra luồng đầu ra (I/D) trong khi chính bạn đang kiểm soát phản hồi. Bộ chuyển đổi không in vào bộ đệm của bạn theo cách TCPDF cũ từng làm, nhưng I/D vẫn điều khiển đầu ra của engine.

Cách khắc phục. Trong các worker và trình xử lý mà bạn kiểm soát, hãy dùng Output($path, 'F') để ghi ra một tệp, hoặc Output($name, 'S') để lấy các byte và tự phát chúng. tests/Unit/Compat/Tcpdf/Bridge/OutputBridgeTest.php xác nhận rằng việc ánh xạ đích không phân biệt chữ hoa chữ thường và đã được cắt bỏ khoảng trắng:

Mã	Trả về	Hiệu ứng phụ
`S`	Các byte PDF (`%PDF…`)	không có
`F`	chuỗi rỗng	ghi ra tệp
`E`	phần thân MIME base64	không có
`FI` / `FD`	chuỗi rỗng	ghi ra tệp, rồi chuyển đến đầu ra của engine
`I` / `D` / không xác định	chuỗi rỗng	đầu ra của engine (nội tuyến/tải xuống)

Các khẳng định PDF chính xác theo byte bị thất bại sau khi chuyển đổi

Triệu chứng. Các bài kiểm tra ảnh chụp so sánh byte PDF thô bị thất bại hàng loạt.

Nguyên nhân. Engine sử dụng một bản triển khai PDF 2.0 độc lập. Các phương thức được ủy quyền tạo ra đầu ra hiển thị tương thích, nhưng byte sẽ khác nhau. Điều này là bình thường.

Cách khắc phục. Hãy thiết lập lại đường cơ sở kiểm thử để khẳng định trên nội dung đã kết xuất (văn bản đã trích xuất), cấu trúc (số trang, kích thước trang), hoặc một phép kiểm tra nhanh (str_starts_with($bytes, '%PDF')). Xem /integrations/tcpdf-compat/migration/ Giai đoạn 4.

Một hằng số `K_` / `PDF_` cũ có giá trị sai

Triệu chứng. Một đường dẫn hoặc giá trị mặc định tùy chỉnh mà bạn đặt qua hằng số không có tác dụng.

Nguyên nhân. Bộ chuyển đổi chỉ tự động định nghĩa một hằng số nếu hằng số đó chưa được định nghĩa, và việc này diễn ra trong lần khởi tạo đầu tiên. Nếu lệnh define() của bạn chạy sau khi bộ chuyển đổi đầu tiên được khởi tạo, giá trị mặc định của bộ chuyển đổi đã có hiệu lực.

Cách khắc phục. Hãy định nghĩa mọi hằng số K_* / PDF_* tùy chỉnh trong phần khởi động của bạn, trước khi bất kỳ thực thể bộ chuyển đổi nào được tạo. Xem /integrations/tcpdf-compat/configuration/ § Thứ tự phân giải cấu hình.

Phiên bản engine không khớp khi khởi tạo

Triệu chứng. Quá trình khởi tạo thất bại hoặc hành vi thay đổi bất ngờ sau khi cập nhật một phụ thuộc.

Nguyên nhân. Bộ chuyển đổi yêu cầu nextpdf/core ^3.0. Phiên bản core được phân giải nằm ngoài phạm vi đó sẽ không được hỗ trợ.

Cách khắc phục. Hãy chạy composer show nextpdf/core, và ghim engine ở ^3.0. Xem /integrations/tcpdf-compat/install/ § Xác minh phiên bản engine.

Tham chiếu chẩn đoán nhanh

Câu hỏi	Nơi cần tìm
Phương thức X thực sự làm gì ở đây?	/integrations/tcpdf-compat/method-coverage/, `docs/TCPDF_COVERAGE.md`
Những lệnh gọi nào của tôi bị bỏ qua tham số?	Kiểm tra ở chế độ nghiêm ngặt (trang này; /integrations/tcpdf-compat/migration/)
Tại sao quy trình không dừng lại khi gặp lỗi?	/integrations/tcpdf-compat/security-and-operations/ § Các hành vi đã được tăng cường
Tại sao đầu ra không được ký / không phải PDF/A?	/integrations/tcpdf-compat/security-and-operations/
Xung đột giữa bí danh và import tường minh	Trang này; /integrations/tcpdf-compat/boot-and-discovery/

Xem thêm

/integrations/tcpdf-compat/migration/ — quy trình di chuyển theo giai đoạn giúp ngăn ngừa hầu hết các sự cố trên
/integrations/tcpdf-compat/method-coverage/ — tài liệu tham chiếu hành vi theo từng phương thức
/integrations/tcpdf-compat/boot-and-discovery/ — đăng ký bí danh và tránh xung đột
docs/TCPDF_COVERAGE.md — ma trận phạm vi hỗ trợ chính thức