Bắt đầu nhanh với compat-legacy

Tổng quan nhanh

Trang này hướng dẫn bạn đi từ gói đã cài đặt đến một tệp PDF hoàn chỉnh, rồi đến bước kiểm tra chế độ nghiêm ngặt cần chạy trước khi di chuyển. Mọi khối mã đều khớp với hành vi được bộ kiểm thử của gói xác nhận, nên kết quả hiển thị ở đây chính là kết quả dùng để đối chiếu trong các bài kiểm thử.

Trước khi bắt đầu

Trước tiên, hãy cài đặt gói và xác nhận liên kết với engine theo /integrations/tcpdf-compat/install/. Bạn cần PHP 8.4 và nextpdf/core ^3.0 phải phân giải được.

1. Tạo tài liệu đầu tiên của bạn

Hãy đổi câu lệnh import và giữ nguyên các lệnh gọi theo kiểu TCPDF hiện có. Đây chính là bề mặt được tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php xác nhận.

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->SetCreator('Quickstart');
$pdf->SetTitle('First Document');
$pdf->SetFont('helvetica', '', 12);
$pdf->AddPage();
$pdf->Cell(0, 10, 'Hello from the NextPDF engine', 1, 1, 'C');

$pdf->Output(__DIR__ . '/quickstart.pdf', 'F');

echo "Wrote quickstart.pdf\n";

Chạy tệp này:

php examples/quickstart-first.php

Tệp quickstart.pdf là một PDF 2.0 hợp lệ. Bộ kiểm thử xác nhận rằng chuỗi kết quả tương ứng bắt đầu bằng %PDF cho các đích S, F và E, cũng như với getPDFData().

Các đích xuất

Output($name, $dest) ánh xạ các mã đích của TCPDF thông qua cầu nối xuất an toàn. Bộ kiểm thử xác nhận hành vi này:

`$dest`	Hành vi	Giá trị trả về
`'S'`	Trả về PDF dưới dạng chuỗi	Byte PDF (`%PDF…`)
`'F'`	Ghi PDF vào đường dẫn đã cho	chuỗi rỗng
`'E'`	Trả về phần thân MIME mã hóa base64	một khối có dòng `Content-Type: application/pdf` ở đầu
`'I'`	Hiển thị inline (mặc định)	theo cầu nối xuất
`'D'`	Tải xuống	theo cầu nối xuất

Khác với TCPDF cũ, Output() không in trực tiếp vào output buffer đang hoạt động. Bạn có thể gọi phương thức này an toàn trong queue worker hoặc HTTP handler tự quản lý phản hồi của chính nó. Xem /integrations/tcpdf-compat/production-usage/.

2. Chạy mã TCPDF hiện có mà không thay đổi

Trong một lần di chuyển thực tế, hãy bắt đầu bằng cách chạy mã hiện có và chỉ đổi câu lệnh import hoặc alias. Nếu codebase của bạn gọi new \TCPDF(...) trong global namespace, hãy bật các alias tùy chọn một lần khi khởi động (được trình bày trong /integrations/tcpdf-compat/boot-and-discovery/):

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

// Legacy code now resolves \TCPDF to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Legacy call site, modern engine');
$pdf->Output(__DIR__ . '/aliased.pdf', 'F');

LegacyBootstrap::enableAliases() có tính lũy đẳng. Nó chỉ đăng ký \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS và \TCPDF_IMAGES khi các lớp đó chưa tồn tại. Bài kiểm thử của gói tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php xác nhận rằng các alias được đăng ký, lệnh gọi có tính lũy đẳng, và new \TCPDF() là một thực thể adapter. Đừng bật các alias nếu thư viện TCPDF gốc được nạp trong cùng một process; xem /integrations/tcpdf-compat/troubleshooting/.

3. Kiểm tra với chế độ nghiêm ngặt

Bước này giúp quá trình di chuyển an toàn hơn. Khi chế độ nghiêm ngặt tắt (mặc định), các phương thức không thể tái tạo hành vi của TCPDF sẽ âm thầm suy giảm. Khi chế độ nghiêm ngặt bật, chúng ném ra TcpdfNotImplementedException kèm chính xác các tham số bị bỏ qua. Hãy chạy bước này trong một lượt kiểm tra riêng, tuyệt đối không chạy trong môi trường production.

<?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 {
    // 14 of these parameters are silently ignored by the adapter.
    $pdf->Image('photo.jpg', 10, 10, 50, 0, '', '', '', true, 300);
} catch (TcpdfNotImplementedException $e) {
    // The message names every ignored parameter and a migration hint.
    fwrite(STDERR, $e->getMessage() . "\n");
}

Bài kiểm thử của gói tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php xác nhận rằng đúng lệnh gọi này sẽ ném lỗi ở chế độ nghiêm ngặt, giữ im lặng ở chế độ mặc định, và thông báo chứa tên phương thức cùng các tham số bị bỏ qua. Hãy dùng các ngoại lệ thu thập được làm danh sách công việc di chuyển của bạn — xem /integrations/tcpdf-compat/migration/.

4. Tiếp cận API hiện đại khi bạn cần

Mỗi thực thể adapter đều cho phép truy cập tài liệu của engine bên dưới. Hãy dùng nó để gọi các phương thức NextPDF hiện đại không có tương đương trong TCPDF:

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF();
$pdf->AddPage();
$pdf->Cell(0, 10, 'Legacy call');

// Drop to the modern engine API:
$document = $pdf->getDocument();
$document->setFont('Helvetica', 'B', 16)
    ->cell(0, 10, 'Modern fluent API', newLine: true);

getDocument() trả về NextPDF\Core\Document mà adapter đang bao bọc. Đây là lối thoát được khuyến nghị: chuyển từng điểm gọi sang API hiện đại, cho đến khi bạn có thể gỡ bỏ adapter.

Những khác biệt về hành vi cần lường trước ngay

MultiCell() trả về 1, không phải số ô đã kết xuất. Mã rẽ nhánh dựa trên giá trị trả về của MultiCell() cần được điều chỉnh.
Error() ném ra RuntimeException thay vì gọi die(). Mã trước đây dựa vào việc kết thúc process phải bắt ngoại lệ này.
Các byte PDF chính xác sẽ khác với kết quả của TCPDF. Hãy thiết lập lại baseline cho các khẳng định kiểm thử ở mức byte để thay vào đó chúng kiểm tra nội dung đã kết xuất.

Danh sách đầy đủ theo từng phương thức có tại /integrations/tcpdf-compat/method-coverage/.

Các bước tiếp theo

/integrations/tcpdf-compat/migration/ — chiến lược di chuyển đầy đủ theo từng tệp.
/integrations/tcpdf-compat/configuration/ — chế độ nghiêm ngặt, giá trị mặc định và đối tượng cấu hình hiện đại.
/integrations/tcpdf-compat/production-usage/ — worker, output buffer và hiệu năng.
/integrations/tcpdf-compat/security-and-operations/ — định hướng về mã hóa và ký.

Xem thêm

tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — oracle cho hành vi xuất
tests/Unit/Compat/Tcpdf/TcpdfStrictModeTest.php — oracle cho chế độ nghiêm ngặt
docs/TCPDF_COVERAGE.md — ma trận độ phủ chính thức