Hướng dẫn chuyển đổi

Các công thức và hướng dẫn sẽ xuất hiện tại đây khi các kho upstream phát hành. Trang này dẫn bạn đến nội dung được biên soạn trong các kho nguồn (nextpdf, nextpdf-Laravel, nextpdf-Symfony, và các gói khác trong hệ sinh thái). Để xem tài liệu có sẵn hiện nay, hãy xem Insider_ (35 bài viết, cả 17 ngôn ngữ) hoặc Chọn một bản tích hợp.

Hướng dẫn chuyển đổi

NextPDF là một engine Portable Document Format (PDF) 2.0 cho PHP. Nếu bạn đã tạo PDF bằng thư viện khác, hướng dẫn chuyển đổi sẽ ánh xạ giao diện lập trình ứng dụng (API) của thư viện đó sang NextPDF và ghi lại các khác biệt hành vi mà bạn sẽ gặp. Chỉ mục liên kho này cho biết hướng dẫn nào hỗ trợ chuyển đổi từ thư viện nào, kho nào sở hữu từng hướng dẫn, và mô hình chung mà mọi hướng dẫn đều sử dụng.

Vì trang này là một chỉ mục, nó không đưa ra bất kỳ khẳng định nào về hành vi của bất kỳ hướng dẫn nào. Mỗi hướng dẫn thuộc về kho riêng của mình. Bộ tổng hợp đưa hướng dẫn vào trang này; cho đến khi hướng dẫn xuất hiện, liên kết của hướng dẫn đó sẽ trỏ đến một placeholder. Mọi khẳng định về hành vi đều nằm trong chính hướng dẫn đó, được hỗ trợ bởi một bài kiểm thử trong kho hoặc một điều khoản ISO 32000-2 / Cascading Style Sheets Working Group (CSS WG) đã được ghim, chứ không nằm ở đây.

Mô hình chuyển đổi duy nhất

Mọi hướng dẫn chuyển đổi NextPDF đều dùng chung một mô hình trung thực. Khi đọc từng hướng dẫn, hãy giữ mô hình đó trong đầu:

• Tương thích, nhưng không giống hệt từng byte. NextPDF và thư viện bạn đang rời bỏ là các bản triển khai độc lập. Tài liệu sau khi chuyển đổi giữ nguyên ý đồ chức năng, chứ không phải sự giống hệt ở cấp pixel hay byte. Không hướng dẫn nào khẳng định đó là một bản thay thế lắp-vào-dùng-ngay hay tương thích (không phải byte-identical).
• Mức độ bao phủ là một con số được đo lường, chứ không phải một lời khẳng định. Khi một hướng dẫn nêu con số bao phủ, chẳng hạn như con số của adapter TCPDF, con số đó là chỉ số về độ hoàn chỉnh chức năng được rút ra từ một ma trận trong kho, theo nghĩa của điều khoản 43 trong ISO/IEC 25023. Đó là số đo về số phương thức được bao phủ, chứ không phải một bảo đảm chung chung.
• Mỗi hướng dẫn nêu rõ các khác biệt về hành vi của mình một cách công khai. Mọi hướng dẫn đều có một bảng khác biệt rõ ràng và một mục “không hỗ trợ / không có tương đương trực tiếp”. Một khác biệt là thuộc tính đã được ghi nhận của engine, chứ không phải lỗi.
• Thay đổi bộ kết xuất đòi hỏi phải rà soát lại. Việc chuyển đổi làm thay đổi mã và đòi hỏi một đường cơ sở đầu ra mới. Mỗi hướng dẫn mô tả cách kiểm thử quá trình chuyển đổi; việc nghiệm thu trực quan được thực hiện theo từng tài liệu và vẫn thuộc trách nhiệm của người tích hợp.

Các dạng chuyển đổi

Các hướng dẫn được chia thành hai dạng. Mỗi dạng cho biết mức độ thay đổi của mã.

• Chuyển đổi kiểu viết lại API không có lớp tương thích đệm: mọi điểm gọi đều được viết lại bằng bản ánh xạ động từ và bản ánh xạ tùy chọn của hướng dẫn. Các bản chuyển đổi từ thư viện Hypertext Markup Language (HTML) sang PDF (dompdf, mpdf) dùng dạng này; chúng nhắm trực tiếp đến pipeline Html của NextPDF.
• Chuyển đổi kiểu lắp-vào-rồi-chuyển-dần cung cấp một adapter gần như tương thích ở cấp mã nguồn, nên bước đầu chỉ là một lần thay phụ thuộc tối thiểu. Từ đó, bạn dần chuyển các điểm gọi sang API hiện đại, rồi ngừng dùng adapter. Bản chuyển đổi TCPDF dùng dạng này, thông qua adapter nextpdf/compat-legacy.

Tham chiếu hướng dẫn và kho sở hữu

Mỗi hướng dẫn dưới đây đều nằm trong docs/public/ của kho sở hữu, và bộ tổng hợp đưa hướng dẫn đó vào trang này. Kho sở hữu là nguồn có thẩm quyền đối với các khẳng định về hành vi của hướng dẫn đó; chỉ mục này chỉ ghi lại định tuyến.

Từ	Hướng dẫn	Dạng	Kho sở hữu	Trang
Dompdf	Dompdf → pipeline Html của NextPDF	Viết lại API	nextpdf (core)	Hướng dẫn Dompdf dompdf (dự kiến ở upstream)
mPDF	mPDF → NextPDF core	Viết lại API	nextpdf (core)	Hướng dẫn mPDF mpdf (dự kiến ở upstream)
TCPDF 6.x	TCPDF → NextPDF qua adapter compat-legacy	Lắp-vào-rồi-chuyển-dần	nextpdf-compat-tcpdf kho, gói nextpdf/compat-legacy	Hướng dẫn TCPDF tcpdf-compat (dự kiến ở upstream)

Các hướng dẫn dompdf và mpdf nằm trong kho core vì chúng nhắm đến các API của engine core, và examples/ trong core hỗ trợ chúng. Hướng dẫn tcpdf-compat nằm trong kho compat-tcpdf vì gói nextpdf/compat-legacy sở hữu bề mặt hành vi của TCPDF và các bài kiểm thử adapter hỗ trợ hướng dẫn này. Chỉ mục này thuộc về kho docs vì nó trải rộng qua nhiều kho, và không đưa ra bất kỳ khẳng định nào về hành vi của bất kỳ hướng dẫn riêng lẻ nào.

Mỗi hướng dẫn dùng để làm gì

• Dompdf → NextPDF (dompdf (dự kiến ở upstream)) — dành cho các mã nguồn dùng dompdf/dompdf ở phía máy chủ. Hướng dẫn này ánh xạ loadHtml/render/output và các khóa Options sang pipeline Html của NextPDF, đồng thời chuyển các kỳ vọng về tính năng CSS sang ma trận hỗ trợ CSS chỉ-gồm-mục-Đã-xác-minh. Không có lớp đệm cho class Dompdf; bạn viết lại mọi điểm gọi.
• mPDF → NextPDF (mpdf (dự kiến ở upstream)) — dành cho các mã nguồn dùng mpdf/mpdf. Hướng dẫn này ánh xạ WriteHTML/Output/AddPage và mảng cấu hình của hàm khởi tạo sang API core, với một khác biệt trong cách xử lý phông chữ: NextPDF phân giải phông chữ qua một thư mục phông chữ duy nhất, kết hợp với so khớp CSS, và luôn tạo tập con (subset). Không có lớp đệm cho class Mpdf.
• TCPDF → NextPDF (compat-legacy) (tcpdf-compat (dự kiến ở upstream)) — dành cho các mã nguồn TCPDF 6.x muốn thay đổi ban đầu ở mức nhỏ nhất. Cài đặt adapter, rà soát bề mặt thực tế của bạn ở chế độ nghiêm ngặt dựa trên ma trận bao phủ trong kho, chuyển các điểm gọi ra khỏi adapter, rồi bổ sung cấu trúc gắn thẻ PDF/Universal Accessibility (PDF/UA-2) lên trên, một khả năng mà TCPDF chưa từng có. Adapter là một khung tạm, không phải đích đến, và không phải là một bảo đảm lắp-vào-dùng-ngay.

Cách các liên kết hướng dẫn phân giải

Mỗi placeholder [[…]] ở trên trỏ tới một trang nằm trong kho sở hữu dưới docs/public/migration/, và bộ tổng hợp kéo trang đó vào trang này. Các slug đích tuân theo một quy ước:

/migration/<source>/

Token <source> là tên ngắn của thư viện mà bạn đang chuyển đổi từ đó: một trong các giá trị dompdf, mpdf, hoặc tcpdf-compat, như được liệt kê trong bảng tham chiếu hướng dẫn ở trên. Cho đến khi một trang đích được tổng hợp, liên kết của trang đó vẫn là một placeholder và không phân giải. Chỉ mục này không đưa ra bất kỳ khẳng định nào về hành vi của bất kỳ hướng dẫn đích nào; nó chỉ ghi lại định tuyến và mô hình chuyển đổi chung.

Xem thêm

• Ma trận hỗ trợ CSS — nguồn có thẩm quyền chỉ-gồm-mục-Đã-xác-minh cho các kỳ vọng về tính năng CSS trong hướng dẫn dompdf và mpdf.
• Cẩm nang tích hợp — chỉ mục liên kho cho các gói tích hợp trong hệ sinh thái. Nó đề cập đến một mối quan tâm khác: kết nối với engine, chứ không phải chuyển đổi sang engine.