Cài đặt NextPDF compat-legacy

Tổng quan nhanh

nextpdf/compat-legacy là một thư viện Composer. Thư viện này yêu cầu PHP 8.4 trở lên và nextpdf/core ^3.0. Hãy cài đặt gói này để bổ sung một lớp tương thích mà bạn có thể chuyển sang sử dụng; các lệnh gọi TCPDF hiện có của bạn vẫn giữ nguyên.

Yêu cầu

Phụ thuộc	Phiên bản	Nguồn xác minh
PHP	`>=8.4 <9.0`	gói `composer.jsonrequire.php`
`nextpdf/core`	`^3.0`	gói `composer.jsonrequire`
Composer	2.7 trở lên	đường cơ sở của toolchain

Gói này đi kèm bộ kiểm thử riêng và khai báo PHPStan Level 10 không dùng baseline. Gói yêu cầu PHP 8.4 tại thời điểm chạy. Nhìn chung, engine NextPDF hỗ trợ PHP 8.1 đến 8.4 trên nhánh backport, nhưng adapter này đặt PHP 8.4 làm mức tối thiểu.

Cài đặt

Dùng Composer để thêm gói:

composer require nextpdf/compat-legacy:^3.0

Composer phân giải nextpdf/core ^3.0 như một phụ thuộc bắc cầu. Bộ tính năng cốt lõi không yêu cầu thêm extension runtime nào khác.

Metadata của gói cũng chấp nhận tên cũ nextpdf/compat-tcpdf thông qua một mục replace của Composer. Các bản cài đặt mới nên yêu cầu nextpdf/compat-legacy, tên gói chuẩn tắc.

Kiểm tra bản cài đặt

Sau khi cài đặt, hãy xác nhận rằng lớp adapter đã được nạp và liên kết tới engine phân giải được. Bước kiểm tra sau tạo một tài liệu Portable Document Format (PDF) một trang hoàn toàn trong bộ nhớ và xác nhận phần header của PDF. Bước này dùng chính bề mặt mà bài kiểm thử của gói tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php kiểm chứng.

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\TCPDF;

$pdf = new TCPDF('P', 'mm', 'A4');
$pdf->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'compat-legacy install verified');

$bytes = $pdf->Output('verify.pdf', 'S');

if (! str_starts_with($bytes, '%PDF')) {
    fwrite(STDERR, "Install check failed: output is not a PDF.\n");
    exit(1);
}

echo "OK: adapter loaded, engine linked, PDF produced (" . strlen($bytes) . " bytes).\n";

Chạy nó:

php examples/install-verify.php

Kết quả mong đợi là một dòng OK: duy nhất. Tiền tố %PDF trong chuỗi trả về xác nhận rằng adapter đã dựng một NextPDF\Core\Document, ủy quyền các lệnh gọi trang và văn bản, rồi tuần tự hóa thành kết quả PDF 2.0 hợp lệ.

Kiểm tra phiên bản engine

Adapter yêu cầu nextpdf/core ^3.0. Hãy xác nhận phiên bản mà Composer đã phân giải:

composer show nextpdf/core --format=json

Nếu Composer phân giải ra một phiên bản core nằm ngoài ^3.0, adapter sẽ báo lỗi ngay tại thời điểm khởi tạo thay vì tạo ra kết quả sai. Hãy ghim engine một cách tường minh trong composer.json nếu dự án của bạn cũng phụ thuộc trực tiếp vào nó.

Tùy chọn: bí danh lớp toàn cục

Nếu codebase của bạn gọi new \TCPDF(...) trong namespace toàn cục và bạn chưa thể thay đổi các dòng use/require đó, gói có thể đăng ký bí danh toàn cục. Hành vi này là tùy chọn bật và được mô tả trong /integrations/tcpdf-compat/boot-and-discovery/. Đừng bật tùy chọn này nếu thư viện TCPDF thật cũng được cài đặt trong cùng tiến trình; xem /integrations/tcpdf-compat/troubleshooting/ để biết quy tắc tránh xung đột.

Những việc cài đặt không làm

Gói này không sửa đổi hoặc gỡ bỏ một phụ thuộc TCPDF sẵn có. Chỉ gỡ bỏ tecnickcom/tcpdf như một bước có chủ đích về sau trong /integrations/tcpdf-compat/migration/.
Gói này không bật chữ ký số hoặc PDF/A. Những tính năng đó yêu cầu một phiên bản NextPDF thương mại (xem /integrations/tcpdf-compat/security-and-operations/).
Gói này không thay đổi đích đầu ra của PDF. Đầu ra luôn là PDF 2.0.

Bước tiếp theo

/integrations/tcpdf-compat/quickstart/ — tạo tài liệu thực đầu tiên của bạn.
/integrations/tcpdf-compat/configuration/ — cấu hình chế độ nghiêm ngặt và adapter.
/integrations/tcpdf-compat/migration/ — áp dụng chiến lược di chuyển theo từng tệp.
/integrations/tcpdf-compat/method-coverage/ — xem chính xác từng phương thức TCPDF hoạt động như thế nào ở đây.

Xem thêm

Gói composer.json — các ràng buộc phụ thuộc có thẩm quyền
docs/TCPDF_COVERAGE.md — ma trận phạm vi hỗ trợ có thẩm quyền (trong repo)