Khởi động và phát hiện compat-legacy trong NextPDF

Tổng quan nhanh

nextpdf/compat-legacy cung cấp NextPDF\Compat\Tcpdf\TCPDF, một facade tương thích TCPDF ủy quyền cho engine NextPDF. Đây là một lớp tương thích, không phải bản sao thay thế trực tiếp. Nó ủy quyền trực tiếp 94 trong số khoảng 120 phương thức TCPDF 6.x được khảo sát. Các phương thức còn lại có những khác biệt về hành vi đã được ghi nhận; xem /integrations/tcpdf-compat/method-coverage/.

Tuyệt đối không có thiết lập toàn cục tại thời điểm autoload. Việc require gói này không tạo ra lớp \TCPDF toàn cục theo mặc định. Bạn chủ động chọn dùng bí danh toàn cục một cách rõ ràng, hoặc tốt hơn trong quá trình di chuyển là import lớp adapter theo từng tệp.

Cách facade TCPDF được cung cấp

Facade là một lớp được autoload theo chuẩn PHP Standard Recommendation 4 (PSR-4):

Mục	Giá trị
Lớp facade	`NextPDF\Compat\Tcpdf\TCPDF`
Tiền tố PSR-4	`NextPDF\Compat\Tcpdf\` ánh xạ tới `src/Compat/Tcpdf/`
Hợp đồng dùng chung	`NextPDF\Compat\Contracts\CompatAdapterInterface`
Điểm thoát	`TCPDF::getDocument()` trả về đối tượng được bọc bên trong `NextPDF\Core\Document`

Lớp này được cố ý để không phải final. Người dùng TCPDF cũ thường kế thừa TCPDF để ghi đè Header() và Footer(), nên adapter giữ lại điểm mở rộng đó. Bên trong, lớp này hoạt động như một facade. Nó kết hợp 25 trait chức năng đơn trách nhiệm và ủy quyền mọi thao tác Portable Document Format (PDF) cho một thực thể Document được tạo khi facade được dựng.

Trình tự khởi động

Diagram

Việc khởi tạo là bước “khởi động” duy nhất. Bản thân gói này không đăng ký service container nào và không thực hiện bất kỳ bootstrapping framework nào. Bạn thêm phần tích hợp framework dưới dạng một lớp mỏng; xem /integrations/tcpdf-compat/integration/.

LegacyDefaults::register() mang tính idempotent: nó chỉ định nghĩa một hằng số khi hằng số đó chưa được định nghĩa. Các hằng số do ứng dụng định nghĩa luôn thắng nếu bạn định nghĩa chúng trước lần khởi tạo đầu tiên; xem /integrations/tcpdf-compat/configuration/ § Thứ tự phân giải cấu hình.

Bí danh lớp toàn cục tùy chọn

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 điểm gọi đó, hãy đăng ký bí danh toàn cục một lần trong lúc khởi động ứng dụng:

<?php

declare(strict_types=1);

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

use NextPDF\Compat\Tcpdf\LegacyBootstrap;

LegacyBootstrap::enableAliases();

// Global names now resolve to the adapter:
$pdf = new \TCPDF('P', 'mm', 'A4');

enableAliases() đăng ký \TCPDF, \TCPDF_STATIC, \TCPDF_FONTS, \TCPDF_COLORS, và \TCPDF_IMAGES. tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php kiểm chứng các hành vi này:

Nó có tính idempotent: gọi hai lần không gây lỗi và chỉ đăng ký một lần.
LegacyBootstrap::isRegistered() cho biết nó đã chạy hay chưa.
Sau khi đăng ký, new \TCPDF() tạo ra một thực thể của adapter.

Tránh xung đột với bản cài đặt TCPDF thật

Đây là quy tắc quan trọng nhất trên trang này.

enableAliases() đăng ký một bí danh chỉ khi chưa có lớp nào mang tên đó (class_exists($alias, autoload: false)). Do đó:

Nếu tecnickcom/tcpdf được cài đặt và \TCPDF của nó được nạp trước, bí danh sẽ bị bỏ qua một cách âm thầm, và mã của bạn vẫn tiếp tục dùng TCPDF cũ, không phải adapter.
Việc chạy cả hai thư viện với bí danh toàn cục được bật trong cùng một tiến trình không được hỗ trợ và tạo ra hành vi mơ hồ.

Trong quá trình di chuyển, hãy ưu tiên import rõ ràng theo từng tệp (use NextPDF\Compat\Tcpdf\TCPDF;). Cách này dễ tìm kiếm và không gây mơ hồ. Gỡ bỏ tecnickcom/tcpdf sau khi kiểm tra ở chế độ nghiêm ngặt đạt yêu cầu; xem /integrations/tcpdf-compat/migration/ Giai đoạn 5. Khi \TCPDF phân giải sai lớp, /integrations/tcpdf-compat/troubleshooting/ có hướng dẫn chẩn đoán.

Liên kết container

Gói này không đi kèm liên kết container cho framework. Nếu bạn liên kết facade trong một container, hãy liên kết một factory trả về một NextPDF\Compat\Tcpdf\TCPDF mới cho mỗi tài liệu. Trạng thái tài liệu thuộc riêng từng thực thể và không được chia sẻ giữa các tài liệu không liên quan; xem /integrations/tcpdf-compat/production-usage/ § Đồng thời. /integrations/tcpdf-compat/integration/ trình bày một liên kết điển hình.

Thứ tự phân giải cấu hình

Khi khởi tạo, adapter phân giải cấu hình theo thứ tự này: trước hết là các đối số của constructor, sau đó là bất kỳ hằng số cũ nào do ứng dụng định nghĩa đang tồn tại, rồi đến các giá trị mặc định LegacyDefaults của TCPDF 6.2.13 cho mọi hằng số chưa được định nghĩa. Để biết đầy đủ chi tiết và đối tượng AdaptationConfig hiện đại, xem /integrations/tcpdf-compat/configuration/.

Chẩn đoán

Để xác nhận facade đã được thiết lập và liên kết tới đúng engine phân giải, hãy khởi tạo một adapter, tạo một PDF một trang, rồi kiểm tra tiền tố %PDF. Các bài kiểm tra đầu ra của gói cũng kiểm chứng cùng bề mặt đó. Bài kiểm tra có thể chạy được nằm trong /integrations/tcpdf-compat/install/ § Xác minh quá trình cài đặt.

Để phát hiện xung đột với TCPDF thật trước khi bật bí danh, hãy kiểm tra xem một \TCPDF toàn cục đã tồn tại hay chưa ở nơi bạn sẽ gọi enableAliases(). Nếu có, bí danh sẽ bị bỏ qua. Hãy giải quyết xung đột bằng cách import rõ ràng, hoặc gỡ bỏ TCPDF thật trước khi bạn dựa vào adapter.

Phạm vi bao phủ API TCPDF

Ma trận phạm vi bao phủ chính thức, đã được kiểm chứng bằng kiểm thử, là tệp docs/TCPDF_COVERAGE.md trong repo. Bản tóm tắt dành cho người đọc, bao gồm danh sách các phương thức bị bỏ qua âm thầm và chưa được triển khai, nằm ở /integrations/tcpdf-compat/method-coverage/. Gói này không tuyên bố là một “bản thay thế trực tiếp” hay “tương thích TCPDF 100%”; đây là một giải pháp thay thế tương thích TCPDF với bề mặt tương thích đã biết, đã được kiểm thử và những khác biệt về hành vi đã được ghi nhận.

Xem thêm

docs/TCPDF_COVERAGE.md — nguồn phạm vi bao phủ chính thức (trong repo)
/integrations/tcpdf-compat/integration/ — thiết lập facade trong một application/framework
/integrations/tcpdf-compat/method-coverage/ — hành vi và khoảng trống theo từng phương thức
/integrations/tcpdf-compat/migration/ — chiến lược di chuyển theo từng giai đoạn
/integrations/tcpdf-compat/troubleshooting/ — chẩn đoán xung đột alias/real-TCPDF
tests/Unit/Compat/Tcpdf/LegacyBootstrapTest.php — oracle về hành vi bí danh