Tích hợp NextPDF compat-legacy

Tổng quan nhanh

Sử dụng nextpdf/compat-legacy để kết nối ứng dụng, giúp mã TCPDF 6.x hiện có chạy trên engine NextPDF. Gói này là công cụ hỗ trợ chuyển đổi, không phải lớp đệm vĩnh viễn — hãy gỡ bỏ sau khi bạn đã chuyển sang API hiện đại (xem /integrations/tcpdf-compat/migration/). Đây là một lựa chọn thay thế tương thích TCPDF, không phải bản sao theo kiểu thay-thế-tương-thích-rồi-di-trú: 94 trong số khoảng 120 phương thức TCPDF được khảo sát sẽ ủy thác trực tiếp. Các phương thức còn lại có khác biệt về hành vi đã được ghi lại (xem /integrations/tcpdf-compat/method-coverage/).

Cài đặt

composer require nextpdf/compat-legacy:^3.0

Lệnh này phân giải nextpdf/core ^3.0 dưới dạng phụ thuộc bắc cầu. Để xem đầy đủ yêu cầu và các bước xác minh, hãy xem /integrations/tcpdf-compat/install/.

Khởi động và tự động khám phá

Gói này không gắn biến toàn cục vào quá trình autoload. Việc require gói này không tạo ra \TCPDF toàn cục. Bạn tự chọn cách các điểm gọi phân giải lớp này:

Cách ưu tiên (import tường minh). Cập nhật các dòng use/require thành use NextPDF\Compat\Tcpdf\TCPDF; trong từng tệp. Cách này rõ ràng và dễ tra cứu.
Bí danh toàn cục cần bật tường minh. Gọi LegacyBootstrap::enableAliases() một lần khi khởi động để đăng ký \TCPDF và bốn lớp trợ giúp — chỉ khi những tên đó chưa bị chiếm dụng. Cơ chế, tính bất biến khi gọi nhiều lần và quy tắc xung đột với TCPDF thật: /integrations/tcpdf-compat/boot-and-discovery/.

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

// One call at application bootstrap, before any \TCPDF use.
LegacyBootstrap::enableAliases();

Liên kết container

Gói này không đi kèm service provider hay bundle của framework. Bạn tự quản lý lớp tích hợp mỏng này. Hãy liên kết một factory trả về một adapter mới cho mỗi tài liệu — đừng bao giờ dùng singleton dùng chung, vì mỗi instance sở hữu trạng thái tài liệu riêng (xem /integrations/tcpdf-compat/production-usage/ § Concurrency).

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use Psr\Container\ContainerInterface;

// Pseudocode for a PSR-11-style container: bind a factory, not a shared instance.
$container->set(TCPDF::class, static function (ContainerInterface $c): TCPDF {
    return new TCPDF('P', 'mm', 'A4');
});

// Each resolution is an independent document context.
$pdf = $container->get(TCPDF::class);

Trong Symfony, hãy đăng ký factory đó dưới dạng service không dùng chung. Trong Laravel, hãy dùng bind (không phải singleton) để mỗi lần phân giải đều tạo một instance mới. Bản thân gói này vẫn độc lập với framework.

Xuất bản cấu hình

Không có tệp cấu hình framework nào để xuất bản. Hãy cấu hình adapter thông qua các hằng số kế thừa K_* / PDF_* (định nghĩa chúng trong phần bootstrap của bạn trước lần khởi tạo đầu tiên) hoặc thông qua đối tượng bất biến hiện đại NextPDF\Compat\Tcpdf\Config\AdaptationConfig. Xem /integrations/tcpdf-compat/configuration/.

Kiểm tra nhanh service provider / bundle

Sau khi kết nối xong, hãy xác minh rằng phần tích hợp tạo ra một tệp Portable Document Format (PDF) hợp lệ. Bài kiểm tra này phản ánh bề mặt hành vi đã đượ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->AddPage();
$pdf->SetFont('helvetica', '', 12);
$pdf->Cell(0, 10, 'Integration smoke test');

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

assert(str_starts_with($bytes, '%PDF'), 'Integration smoke test failed');
echo "Integration OK\n";

Trong ngữ cảnh Hypertext Transfer Protocol (HTTP) hoặc worker, hãy dùng Output(..., 'F') hoặc 'S'. Đừng dựa vào đường dẫn inline. Để xem hướng dẫn vận hành đầy đủ, hãy xem /integrations/tcpdf-compat/production-usage/.

Các điểm vào API công khai

Điểm vào	Mục đích
`NextPDF\Compat\Tcpdf\TCPDF`	Facade tương thích TCPDF. Khởi tạo một đối tượng cho mỗi tài liệu.
`TCPDF::getDocument()`	Trả về `NextPDF\Core\Document` được bọc bên trong — đường thoát sang API hiện đại.
`TCPDF::setStrictMode(bool)`	Công tắc kiểm toán quá trình chuyển đổi (xem /integrations/tcpdf-compat/configuration/).
`NextPDF\Compat\Tcpdf\LegacyBootstrap::enableAliases()`	Bí danh lớp toàn cục cần bật tường minh.
`NextPDF\Compat\Tcpdf\Config\AdaptationConfig`	Đối tượng cấu hình bất biến hiện đại.
`NextPDF\Compat\Contracts\CompatAdapterInterface`	Hợp đồng tương thích dùng chung.

Phạm vi bao phủ API của TCPDF

Ma trận bao phủ chính thức, đã được kiểm chứng bằng test, nằm trong tệp docs/TCPDF_COVERAGE.md trong repo. Bản tóm tắt dành cho người đọc — gồm các phương thức được phản chiếu, bị bỏ qua âm thầm, chưa triển khai và không áp dụng — nằm tại /integrations/tcpdf-compat/method-coverage/. Đừng gọi đây là một bản triển khai “Kiểu thay-thế-tương-thích-rồi-di-trú” hay “tương thích (không phải byte-identical)”. Hãy mô tả nó là một lựa chọn thay thế tương thích TCPDF với bề mặt đã biết, đã được kiểm thử và những khác biệt về hành vi đã được ghi lại.

Xem thêm

docs/TCPDF_COVERAGE.md — nguồn bao phủ chính thức trong repo
/integrations/tcpdf-compat/boot-and-discovery/ — cách hiển thị facade và hành vi bí danh
/integrations/tcpdf-compat/method-coverage/ — hành vi và khoảng trống của từng phương thức
/integrations/tcpdf-compat/migration/ — chiến lược chuyển đổi theo từng giai đoạn
/integrations/tcpdf-compat/production-usage/ — cách chạy adapter dưới tải
tests/Unit/Compat/Tcpdf/TcpdfOutputTest.php — oracle cho hành vi đầu ra