Hướng dẫn cho nhà phát triển về tương thích TCPDF

Tổng quan nhanh

Adapter tương thích là lớp hỗ trợ quá trình di chuyển. Nó làm rõ các hành vi cũ thay vì che giấu chúng. Hãy dùng adapter này để giữ cho ứng dụng tiếp tục chạy trong khi bạn chuyển các luồng có giá trị cao sang các API NextPDF native.

Hãy dùng hướng dẫn này khi bạn bảo trì mã cũ kiểu TCPDF, mở rộng phạm vi hỗ trợ của adapter hoặc lập kế hoạch di chuyển từng giai đoạn sang các API NextPDF native.

Ranh giới kiến trúc

Lớp	Thuộc về	Trách nhiệm	Đừng đặt ở đây
Ứng dụng cũ	Ứng dụng	Giữ cho các lệnh gọi kiểu TCPDF hiện có tiếp tục chạy trong quá trình di chuyển.	Các tính năng PDF mới nên dùng API NextPDF native.
Lớp vỏ adapter	`nextpdf/compat-legacy`	Cung cấp lớp kiểu `TCPDF` và trạng thái tương thích dùng chung.	Các nhóm phương thức lớn hoặc logic chuyển đổi dữ liệu.
Các trait theo mối quan tâm	`nextpdf/compat-legacy`	Nhóm các họ phương thức cũ: văn bản, phông chữ, hình ảnh, bảo mật, biểu mẫu, trang.	Chính sách đầu ra áp dụng cho nhiều họ phương thức.
Các lớp bridge	`nextpdf/compat-legacy`	Chuyển đổi đối số cũ, đích đến, màu sắc, đơn vị và định dạng.	Hành vi đặc thù theo nghiệp vụ.
Engine lõi	`nextpdf/nextpdf`	Tạo tài liệu native.	Các cam kết tương thích cũ.

Vòng đời khi chạy

Giai đoạn	Hành vi	Hành động của nhà phát triển
Khởi tạo (bootstrap)	Một bootstrap cũ tùy chọn cung cấp các tên tương thích.	Chỉ dùng nó ở nơi mã cũ mong đợi các ký hiệu TCPDF.
Khởi tạo đối tượng	Adapter ánh xạ các đối số constructor cũ sang cấu hình tài liệu lõi.	Giữ ổn định dữ liệu đầu vào của constructor trong quá trình di chuyển.
Lệnh gọi phương thức	Các phương thức được hỗ trợ ánh xạ sang hành vi NextPDF thông qua các mối quan tâm và bridge.	Hãy kiểm tra phạm vi hỗ trợ phương thức trước khi giả định chúng tương đương.
Tính năng không được hỗ trợ	Adapter ném ngoại lệ tương thích rõ ràng cho hành vi không được hỗ trợ.	Thay thế lệnh gọi hoặc cô lập nó phía sau mã ứng dụng.
Đầu ra	Bridge đầu ra ánh xạ hành vi đích đến cũ sang đầu ra NextPDF.	Hãy xác thực tên tệp và thư mục gốc của kho lưu trữ.

Bản kiểm kê di chuyển

Bắt đầu bằng cách thu thập mọi lệnh gọi phương thức TCPDF trong ứng dụng của bạn. Hãy phân loại từng lệnh gọi trước khi thay đổi hành vi.

Phân loại	Ý nghĩa	Hành động
Phương thức adapter được hỗ trợ	Phương thức đã được ghi nhận là được hỗ trợ và có kiểm thử.	Tạm thời giữ lại, rồi di chuyển khi bạn chỉnh sửa khu vực đó.
Phương thức adapter hỗ trợ một phần	Phương thức tồn tại, nhưng hành vi không hoàn toàn khớp với TCPDF cũ.	Thêm kiểm thử fixture và xác thực đầu ra theo cách thủ công.
Phương thức rõ ràng không được hỗ trợ	Adapter ném ra một ngoại lệ tương thích.	Thay thế nó bằng NextPDF native hoặc gỡ bỏ tính năng.
Lớp bao bọc đặc thù theo nghiệp vụ	Ứng dụng đã bao bọc sẵn các lệnh gọi TCPDF.	Hãy di chuyển phần bên trong lớp bao bọc trước.
Lệnh gọi nhạy cảm về tuân thủ	Luồng chữ ký, mã hóa, gắn thẻ, PDF/A, trợ năng hoặc hóa đơn.	Di chuyển sang các API NextPDF native kèm xác minh chuyên biệt.

Mẫu đóng góp vào adapter

Hãy thêm hỗ trợ tương thích vào họ phương thức nhỏ nhất chịu trách nhiệm cho hành vi đó.

Loại thay đổi	Nơi triển khai	Kiểm thử bắt buộc
Phương thức xuất văn bản	`Concerns\AdaptsTextOutput` hoặc mối quan tâm về phông chữ.	Fixture cũ kèm assertion cho đầu ra native.
Phương thức trang hoặc lề	Mối quan tâm về trang, định vị hoặc lề.	Kiểm thử chuyển đổi tọa độ và trạng thái trang.
Phương thức hình ảnh hoặc vẽ	Mối quan tâm về hình ảnh, vẽ, màu sắc hoặc gradient.	Kiểm thử xác thực đầu vào và đầu ra visual/structural.
Đích đầu ra	`OutputBridge`.	Kiểm thử ánh xạ đích đến và đường dẫn không an toàn.
Tính năng không được hỗ trợ	Factory ngoại lệ hoặc bảng phạm vi hỗ trợ phương thức.	Kiểm thử loại ngoại lệ và thông điệp.

Đừng đặt một phương thức lớn trực tiếp trong lớp vỏ adapter khi đã có trait theo mối quan tâm sở hữu họ đó.

Mẫu di chuyển sang native

Dùng adapter để ổn định mã cũ, sau đó chuyển các quy trình đã ổn định sang API native.

<?php

// Temporary compatibility code.
$pdf = new \NextPDF\Compat\Tcpdf\TCPDF();
$pdf->AddPage();
$pdf->SetFont('dejavusans', '', 12);
$pdf->Cell(0, 10, 'Invoice 1234');

// Target native shape.
$document = \NextPDF\Core\Document::createStandalone();
$document->addPage()
    ->setFont('dejavusans', '', 12)
    ->cell(0, 10, 'Invoice 1234');

Hãy xem quá trình di chuyển như một chuỗi thay đổi hành vi nhỏ. Một trang vẫn có thể dùng adapter trong khi một phần có rủi ro cao được chuyển sang các API native.

Các điểm mở rộng

Điểm mở rộng	Dùng cho	Ràng buộc
`AdaptationConfig`	Kiểm soát hành vi của adapter trong quá trình di chuyển.	Giữ các giá trị mặc định rõ ràng và đã được rà soát.
Các trait theo mối quan tâm	Gom nhóm các họ phương thức như văn bản, biểu mẫu, hình ảnh hoặc bảo mật.	Hãy thêm phương thức vào mối quan tâm phù hợp, không phải vào lớp vỏ adapter.
Các lớp bridge	Chuyển đổi các dạng đối số cũ thành giá trị lõi.	Bao phủ hành vi của bridge bằng kiểm thử di chuyển.
`CompatAdapterInterface`	Lớp trừu tượng cấp adapter dành cho công cụ.	Đừng dùng nó thay cho contract lõi native trong mã mới.
Bảng phạm vi hỗ trợ phương thức	Bản ghi tình trạng hỗ trợ dành cho nhà phát triển.	Hãy cập nhật khi trạng thái hỗ trợ thay đổi.

Quy trình di chuyển

Cài đặt adapter và chạy bộ kiểm thử cũ mà không sửa đổi.
Hãy mở phạm vi hỗ trợ phương thức và phân loại mọi phương thức được gọi.
Thay thế các phương thức không được hỗ trợ trước.
Chuyển các luồng có lưu lượng cao hoặc nhạy cảm về tuân thủ sang các API lõi native.
Thêm phạm vi fixture cho mọi họ phương thức đã di chuyển.
Gỡ bỏ các bí danh bootstrap khi không còn entrypoint ứng dụng nào phụ thuộc vào chúng.

Xử lý sự cố

Sự cố	Nơi nên xử lý	Phản hồi được khuyến nghị
Phương thức không được hỗ trợ	Ngoại lệ của adapter.	Thay thế lệnh gọi hoặc cô lập nó phía sau adapter ứng dụng.
Bố cục tương đương một phần	Kiểm thử di chuyển và rà soát trực quan.	Ghi lại điểm khác biệt được chấp nhận trước khi triển khai.
Đích đầu ra không an toàn	`OutputBridge` và chính sách lưu trữ của ứng dụng.	Từ chối các đường dẫn không an toàn và ưu tiên các API đầu ra native.
Tính năng bảo mật không khớp	Kế hoạch di chuyển sang native.	Đừng phát hành hành vi chỉ có trong chế độ tương thích cho các đầu ra thuộc phạm vi quản lý.
Xung đột bí danh bootstrap	Bootstrap của ứng dụng.	Gỡ bỏ các bí danh toàn cục hoặc giới hạn chúng vào các entrypoint cũ.

Mặc định an toàn

Mối quan tâm	Mặc định	Khi nào nên ghi đè
Các phương thức không được hỗ trợ	Ném ra ngoại lệ rõ ràng.	Đừng nới lỏng điều này trong môi trường production.
Các giá trị mặc định cũ	Tập trung tại `LegacyDefaults`.	Chỉ ghi đè cho hành vi di chuyển đã biết.
Ánh xạ đầu ra	Thông qua `OutputBridge`.	Dùng các API đầu ra native sau khi di chuyển.
Nguồn phạm vi hỗ trợ	Trang phạm vi hỗ trợ phương thức và các kiểm thử.	Chạy lại các kiểm tra phạm vi hỗ trợ sau mỗi lần nâng cấp adapter.
Chế độ nghiêm ngặt	Giữ ở trạng thái bật trong các đợt kiểm tra di chuyển.	Chỉ tắt trong một khoảng thời gian tương thích cũ đã được ghi nhận.

Danh sách kiểm tra cho kiểm thử

Giữ một fixture cũ cho mỗi họ phương thức đã di chuyển.
Thêm một kiểm thử NextPDF native trước khi bạn thay thế một phương thức cũ.
Khẳng định rằng các phương thức không được hỗ trợ ném ra ngoại lệ đã được ghi nhận.
So sánh cấu trúc đầu ra khi việc khớp byte chính xác không phải là mục tiêu di chuyển thực tế.
Chạy các kiểm tra phạm vi hỗ trợ phương thức sau khi bạn thêm hoặc thay đổi các phương thức của adapter.
Thêm các kiểm thử đường dẫn lưu trữ cho mọi đích đầu ra mà mã cũ sử dụng.