Di chuyển từ mPDF sang NextPDF

Tổng quan nhanh

Hướng dẫn này giúp bạn chuyển mã nguồn dựa trên mPDF sang NextPDF core. Trong mPDF, lệnh gọi chính để ghi nội dung là WriteHTML(), ánh xạ trực tiếp sang Document::writeHtml(). Phần lớn công việc là ánh xạ mảng cấu hình hàm khởi tạo (mPDF cấu hình mọi thứ thông qua một mảng kết hợp duy nhất truyền vào new Mpdf([...])) và xử lý các khác biệt về phông chữ. NextPDF và mPDF là hai engine độc lập, vì vậy tài liệu sau khi di chuyển tương thích với đầu ra của mPDF, chứ không giống hệt từng byte. Hướng dẫn này bao quát ánh xạ các động từ, ánh xạ mảng cấu hình, khác biệt về phông chữ, khác biệt về hỗ trợ Cascading Style Sheets (CSS), các khác biệt về hành vi và một trình tự an toàn.

Trang Bảng hỗ trợ Cascading Style Sheets (CSS) xác định những tính năng Hypertext Markup Language (HTML) và CSS nào đã được xác minh. Hướng dẫn này mô tả hành vi; nó không khẳng định sự tương đương về mặt hình ảnh với mPDF.

Cài đặt

composer require nextpdf/core:^3

Giữ mpdf/mpdf được cài đặt trong khi bạn di chuyển. Gỡ bỏ nó sau lần chuyển đổi cuối cùng (xem trình tự di chuyển an toàn).

Tổng quan khái niệm

Đối tượng Mpdf của mPDF kết hợp cấu hình và kết xuất phía sau một giao diện duy nhất. Một mảng truyền vào hàm khởi tạo cấu hình đối tượng này, còn WriteHTML() cùng các động từ phân trang (AddPage, SetHTMLHeader, SetHTMLFooter) điều khiển nó. NextPDF tách cấu hình thành đối tượng giá trị bất biến NextPDF\Core\Config và ghi nội dung bằng Document::writeHtml(). Hàm khởi tạo không có chuỗi “mode”. NextPDF phân tích cú pháp HTML bạn truyền vào, rồi xuất tài liệu bằng save(), output() hoặc getPdfData().

Về phông chữ: mPDF đi kèm một thư mục phông chữ, một bản đồ fontdata và một tập “core fonts” dự phòng. NextPDF phân giải phông chữ từ một thư mục phông chữ cùng cơ chế đối sánh CSS font-family, và luôn tạo tập con cho các phông chữ nhúng (International Organization for Standardization (ISO) 32000-2 §9, iso32000_2_sec9#x1.x45.p7). Việc đối sánh và dự phòng phông chữ là đặc thù của từng engine (CSS Fonts 4 §5.5, css_fonts_4#x1.x5.x5.x1.p13), nên việc thay thế glyph có thể khác nhau. Đây là khác biệt chính có thể quan sát được, được trình bày trong khác biệt về xử lý phông chữ.

Bề mặt API

API HTML của NextPDF được ghi lại trong tài liệu tham khảo module Html. Các điểm vào cốt lõi gồm Document::createStandalone(), Document::writeHtml(string $html): static, Document::writeHtmlCell(...), Document::addPage(), Document::output(?string, OutputDestination), Document::save(string $path): void, Document::getPdfData(): string, và đối tượng giá trị NextPDF\Core\Config.

Ánh xạ động từ API

Các tên phương thức công khai của mPDF dưới đây được xác nhận đối chiếu với kho lưu trữ công khai gốc (mpdf/mpdf, development); xem tệp sidecar nguồn gốc _source-sidecar-upstream-api.md trong kho. Không có văn bản tài liệu gốc nào được tái hiện.

mPDF	NextPDF	Ghi chú
`new Mpdf([...])`	`Document::createStandalone($config)`	Mảng cấu hình mPDF ánh xạ sang `NextPDF\Core\Config`; xem ánh xạ cấu hình. Dùng `DocumentFactory` cho các worker chạy dài hạn.
`$mpdf->WriteHTML($html)`	`$doc->writeHtml($html)`	Ánh xạ trực tiếp. Tham số `$mode` thứ hai của mPDF (toàn bộ tài liệu so với chỉ CSS so với phần tử) không có đối ứng trong NextPDF; hãy truyền HTML hoàn chỉnh.
`$mpdf->WriteFixedPosHTML(...)`	`$doc->writeHtmlCell(...)`	Vùng HTML được định vị và định kích thước; ánh xạ các tham số x/y/width/height.
`$mpdf->AddPage(...)`	`$doc->addPage()`	NextPDF không nhận các ghi đè orientation/format/lề theo từng lệnh gọi của mPDF làm tham số; thay vào đó, hãy thay đổi mô hình tài liệu giữa các lệnh gọi.
`$mpdf->SetHTMLHeader($html)` / `SetHTMLFooter($html)`	header/footer thông qua Layout API	Các đầu trang HTML chạy liên tục của mPDF ánh xạ sang cơ chế NextPDF header/footer, chứ không phải HTML nội tuyến ở đầu phần thân.
`$mpdf->Output($name, $dest)`	`$doc->output($name, OutputDestination::…)`	Các ký tự đích đến của mPDF (`I`/`D`/`F`/`S`) ánh xạ sang enum `OutputDestination` (`Inline`/`Download`/file qua `save()`/string qua `getPdfData()`).
`$mpdf->Output('','S')`	`$doc->getPdfData()`	Trả về byte.
`$mpdf->Output($path,'F')`	`$doc->save($path)`	Ghi vào một đường dẫn tệp.
`$mpdf->SetTitle($t)`	`$doc->setTitle($t)`	Nằm trong từ điển thông tin ISO 32000-2 §14 / Extensible Metadata Platform (XMP) (`iso32000_2_sec14#x1.x5.p5`).
`$mpdf->SetProtection($perms,...)`	`$doc->setEncryption(...)` (Security API)	Quyền hạn phụ thuộc vào sự hợp tác của trình đọc, không phải kiểm soát truy cập — xem ghi chú bảo mật.

Mẫu mã — bắt đầu nhanh

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

// mPDF:
//   $mpdf = new \Mpdf\Mpdf();
//   $mpdf->WriteHTML('<h1>Invoice</h1>');
//   $mpdf->Output('out.pdf', \Mpdf\Output\Destination::FILE);

// NextPDF — default page is A4 portrait:
$doc = Document::createStandalone();
$doc->setTitle('Invoice');
$doc->addPage();
$doc->writeHtml('<h1>Invoice</h1>');
$doc->save(__DIR__ . '/out.pdf');

echo "Wrote out.pdf\n";

Mẫu mã — sản xuất

Ví dụ này tương ứng với examples/04-text-and-fonts.php, mã chạy được dùng làm nền tảng cho các khái niệm xử lý phông chữ trong hướng dẫn này. Ví dụ dùng kích thước trang rõ ràng, lề và phần thân nội dung để thực hiện việc chọn phông chữ.

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;

// Equivalent of: new Mpdf(['format'=>'A4','margin_left'=>20, ...]).
// Margin constructor order is (top, right, bottom, left) — NOT L,R,T,B.
$config = new Config(
    pageSize: new PageSize(595.276, 841.890, 'A4'),
    margins: new Margin(16.0, 20.0, 16.0, 20.0), // top,right,bottom,left in points
    fontsDirectory: __DIR__ . '/fonts',
);

$doc = Document::createStandalone($config);
$doc->setTitle('Quarterly Report');
$doc->addPage();

$html = <<<'HTML'
<h1 style="font-family:'DejaVu Sans';color:#1E3A8A;">Quarterly Report</h1>
<p>Body text resolves through CSS font-family matching against the configured
fonts directory. mPDF's fontdata map has no direct analogue — register the
family via CSS and the fonts directory instead.</p>
HTML;

$doc->writeHtml($html);

// Equivalent of $mpdf->Output('report.pdf', Destination::DOWNLOAD):
$doc->output('report.pdf', OutputDestination::Download);

Trường hợp đặc biệt & lưu ý

Tham số $mode trên WriteHTML. WriteHTML($html, $mode) của mPDF (2 = chỉ CSS, 1 = phần tử) không có đối ứng. Hãy đặt CSS vào trong HTML bạn truyền vào; không có trình tự “ghi CSS rồi ghi phần thân”.
Các ghi đè theo từng AddPage. mPDF cho phép AddPage() thay đổi format/orientation ở giữa tài liệu bằng tham số. NextPDF addPage() không nhận tham số như vậy; kích thước mô hình thay đổi trong tài liệu, chứ không qua từng lệnh gọi trang.
HTML đầu trang/chân trang. mPDF đăng ký các đầu trang chạy liên tục dưới dạng những đoạn HTML riêng biệt; đừng dán chúng vào phần thân. Hãy ánh xạ chúng sang cơ chế NextPDF header/footer.
Tên phông chữ. mPDF chuẩn hóa tên phông chữ qua bảng fontdata/core-font của nó. NextPDF đối sánh CSS font-family với thư mục phông chữ; một bí danh mPDF từng được phân giải ngầm có thể cần một @font-face/family.
Các ký tự đích đến. 'I'/'D'/'F'/'S' không được chấp nhận; hãy dùng enum OutputDestination hoặc save()/getPdfData().

Hiệu năng

writeHtml() chạy một lượt (ADR-001); bộ nhớ đỉnh bám theo kích thước tài liệu, không phải một Document Object Model (DOM) được giữ lại. Ngân sách cho ví dụ trong hướng dẫn này: wall_ms: 2000, peak_mb: 128. Với tài liệu dài, hãy chia nội dung qua nhiều lệnh gọi addPage() thay vì truyền một chuỗi khổng lồ. Đây là cùng một hướng dẫn áp dụng cho việc chia đoạn bằng $mode của mPDF, được biểu đạt qua mô hình trang.

Ghi chú bảo mật

Quyền hạn dựa trên sự hợp tác của trình đọc. SetProtection() → setEncryption() mang lại tính bảo mật, không phải kiểm soát truy cập: các bit quyền hạn ISO phụ thuộc vào một trình đọc hợp tác. Đừng giới thiệu mã hóa với người dùng như một cơ chế kiểm soát truy cập.
Siêu dữ liệu. SetTitle() và thông tin tài liệu nằm trong từ điển thông tin ISO 32000-2 §14 / XMP (iso32000_2_sec14#x1.x5.p5); đừng bao giờ lưu bí mật ở đó.
NextPDF không thực thi các script bên trong tài liệu; không có chỉ thị mPDF nào thay đổi điều đó ở đây.

Tuân thủ

Tuyên bố	Đặc tả	Điều khoản
Phông chữ được ghi dưới dạng chương trình phông chữ embedded/subset.	ISO 32000-2	§9
format/margins trang ánh xạ sang hộp giới hạn trang.	ISO 32000-2	§7
Siêu dữ liệu tiêu đề / bảo vệ nằm trong từ điển thông tin / XMP.	ISO 32000-2	§14
Việc đối sánh / dự phòng phông chữ là đặc thù của từng engine.	CSS Fonts 4	§5.5

NextPDF tạo ra nội dung ISO 32000-2; nó không khẳng định sự đồng nhất về mặt hình ảnh với mPDF. Hãy xem xét lại đầu ra mỗi khi bạn đổi trình kết xuất.

Bối cảnh thương mại

Không áp dụng. NextPDF core bao quát lộ trình di chuyển mPDF được mô tả ở đây.

Xem thêm

Chi tiết di chuyển (các phần bắt buộc của R6)

Đối tượng phù hợp

Các nhóm đang chạy mpdf/mpdf để chuyển HTML sang PDF phía máy chủ. Nếu mã của bạn được xây dựng quanh new Mpdf([...]) + WriteHTML + Output (+ header/footer tùy chọn), thì ánh xạ động từ và ánh xạ cấu hình sẽ bao quát trường hợp đó.

Phạm vi

Trong phạm vi: mảng cấu hình hàm khởi tạo Mpdf, WriteHTML/Output/AddPage, headers/footers, phông chữ, bảo vệ, siêu dữ liệu. Ngoài phạm vi: các lớp nội bộ của mPDF và bề mặt trợ giúp Quick Response (QR)/barcode/watermark. Hãy ánh xạ những phần đó sang các module NextPDF tương ứng — Barcode, Graphics — vốn không được trình bày ở đây.

Bảng tương thích

Tương thích về hành vi, không phải một shim thay thế trực tiếp: NextPDF không cung cấp shim lớp Mpdf. Hãy viết lại mọi điểm gọi. Dùng các hàng đã xác minh trong bảng hỗ trợ CSS để đặt kỳ vọng về tính năng CSS.

Ánh xạ mảng cấu hình của hàm khởi tạo

Các khóa cấu hình mPDF dưới đây được xác nhận đối chiếu với kho lưu trữ công khai gốc (mpdf/mpdf, development). Không có văn bản tài liệu gốc nào được tái hiện.

Khóa cấu hình mPDF	NextPDF	Ghi chú
`mode`	(không có đối ứng)	Chuỗi mode của mPDF (`'utf-8'`, `'c'`, `'+aCJK'`, …) chọn hành vi font/script. NextPDF luôn dùng Unicode; văn bản tiếng Trung, tiếng Nhật và tiếng Hàn (CJK) được xử lý bằng việc chọn phông chữ, không phải bằng một mode. Bỏ khóa này.
`format`	`Config->pageSize` (đối tượng giá trị (VO) `PageSize`)	Các định dạng có tên trở thành kích thước tính bằng điểm rõ ràng; các mảng `[w,h]` ánh xạ sang một `PageSize`.
`orientation`	hoán đổi `PageSize` của width/height	Không có cờ hướng; khổ ngang nghĩa là chiều rộng lớn hơn chiều cao.
`default_font_size`	cỡ phông chữ cơ sở của CSS	Đặt giá trị này trong bảng định kiểu cơ sở của bạn, không phải một khóa của hàm khởi tạo.
`default_font`	CSS `font-family` / phông chữ đã đăng ký	Đặt họ phông chữ mặc định thông qua CSS / đăng ký phông chữ.
`margin_left` / `margin_right` / `margin_top` / `margin_bottom`	`Config->margins` (VO `Margin`) tính theo điểm	Dùng một đối tượng giá trị `Margin` duy nhất; thứ tự hàm khởi tạo của nó là `Margin(top, right, bottom, left)` (được kiểm chứng với `src/ValueObjects/Margin.php`), chứ không phải thứ tự khóa của mPDF.
`margin_header` / `margin_footer`	độ lệch header/footer thông qua Layout API	Hãy ánh xạ những thứ này sang cấu hình NextPDF header/footer, không phải các khóa của hàm khởi tạo.

Khác biệt về xử lý phông chữ

Thư mục phông chữ duy nhất. Danh sách thư mục phông chữ, bản đồ fontdata và dự phòng core-font của mPDF được gộp thành Config->fontsDirectory cùng với việc đối sánh CSS font-family.
Luôn tạo tập con. NextPDF luôn tạo tập con cho các phông chữ nhúng (ISO 32000-2 §9, iso32000_2_sec9#x1.x45.p7); các cờ tập con của mPDF không có đối ứng và cũng không cần thiết.
Việc đối sánh là đặc thù của từng engine. Việc đối sánh và dự phòng phông chữ khác nhau theo từng engine (CSS Fonts 4 §5.5, css_fonts_4#x1.x5.x5.x1.p13); một bí danh phông chữ mPDF có thể cần một @font-face rõ ràng hoặc tên họ chính xác. Hãy thiết lập lại đường cơ sở cho kết xuất glyph sau khi di chuyển. Các khác biệt khi thay thế là điều được mong đợi, không phải lỗi.

Khác biệt về hành vi

Thay thế phông chữ (xem ở trên) — khác biệt nhìn thấy được chính.
Không có $mode trên WriteHTML — hãy truyền HTML hoàn chỉnh kèm CSS nội tuyến.
Không có ghi đè định dạng theo từng AddPage — kích thước mô hình thay đổi qua tài liệu.
Quyền hạn dựa trên sự hợp tác của trình đọc (xem ghi chú bảo mật).
Engine bố cục độc lập — việc xuống dòng / phân trang khác nhau trên nội dung dày đặc; hãy thiết lập lại đường cơ sở cho các so sánh hình ảnh.

Đây là các khác biệt về hành vi đã được ghi lại, không phải lỗi của bất kỳ engine nào.

Không hỗ trợ / không có đối ứng trực tiếp

mode chuỗi của hàm khởi tạo — không được mô hình hóa (luôn dùng Unicode).
Các tham số format/orientation/lề theo từng AddPage() — không phải tham số trong NextPDF.
Bản đồ fontdata của mPDF — được thay thế bằng thư mục phông chữ + đối sánh CSS.
Các ký tự đích đến 'I'/'D'/'F'/'S' của mPDF — được thay thế bằng enum OutputDestination + save()/getPdfData().

Trình tự di chuyển an toàn

Thêm nextpdf/core bên cạnh mpdf/mpdf; tạm thời giữ mPDF được cài đặt.
Chọn một tài liệu ít rủi ro. Chuyển đổi new Mpdf([...]) thông qua ánh xạ cấu hình và WriteHTML/Output thông qua ánh xạ động từ.
Đăng ký các phông chữ mà tài liệu sử dụng trong Config->fontsDirectory, và thêm các khai báo @font-face/family rõ ràng cho bất kỳ bí danh mPDF nào.
Tạo cả hai tệp PDF cho cùng một đầu vào và so sánh chúng bằng mắt. Các khác biệt (thay thế phông chữ, xuống dòng) là điều được mong đợi với các engine độc lập — hãy chấp nhận chúng theo từng tài liệu.
Ánh xạ bất kỳ HTML header/footer nào sang cơ chế NextPDF header/footer.
Lặp lại theo từng tài liệu, ít rủi ro nhất trước; giữ mPDF được cài đặt cho đến lần chuyển đổi cuối cùng.
Gỡ bỏ mpdf/mpdf khỏi composer.json sau lần chuyển đổi cuối cùng.

Kiểm thử việc di chuyển

Chụp ảnh nhanh đầu ra mPDF cho các tài liệu đại diện trước khi bạn thay đổi mã (đầu vào golden; các byte sẽ khác).
Với mỗi tài liệu đã di chuyển, hãy xác nhận việc chấp nhận bằng kiểm tra của riêng bạn (so sánh hình ảnh
- trích xuất văn bản). Hành vi phông chữ/HTML của NextPDF được thực thi bởi examples/04-text-and-fonts.php và examples/08-html-basic.php cùng các bộ kiểm thử Html/Font trong tests/ của core. Việc chấp nhận di chuyển phụ thuộc vào từng tài liệu và vẫn thuộc trách nhiệm của bạn.
Thêm một kiểm thử hồi quy cho mỗi tài liệu đã di chuyển.

Bằng chứng / khả năng truy vết

Mọi tuyên bố về hành vi của NextPDF trên trang này đều được hỗ trợ bởi một kiểm thử, ví dụ, chữ ký nguồn hoặc bản ghi quyết định kiến trúc (ADR) trong kho; riêng với các thuộc tính định dạng PDF, chúng được hỗ trợ bởi các điều khoản ISO 32000-2 / CSS được ghim qua truy xuất tăng cường tạo sinh (RAG) trong citations: ở front-matter và bảng Tuân thủ. Hành vi mPDF chỉ được khẳng định ở mức “engine độc lập — hãy mong đợi các khác biệt đã được ghi lại”; trang này không tuyên bố bất kỳ sự ngang bằng nào mà một tạo phẩm trong kho không chứng minh.

Tuyên bố về hành vi của NextPDF	Bằng chứng trong kho (đường dẫn)
`WriteHTML()` ánh xạ trực tiếp sang `Document::writeHtml(string $html): static`.	`src/Core/Concerns/HasTextOutput.php` (`writeHtml()`); `examples/08-html-basic.php`.
`WriteFixedPosHTML(...)` ánh xạ sang `writeHtmlCell(...)`.	`src/Core/Concerns/HasTextOutput.php` (`writeHtmlCell()`).
`createStandalone()` mặc định trang là A4 dọc (`595.276 × 841.890 pt`).	`src/Core/Config.php` (`PageSize` mặc định); `tests/Unit/Core/DocumentCreateStandaloneAndConfigWithersEdgeCaseTest.php`.
`Margin` có thứ tự hàm khởi tạo là `(top, right, bottom, left)`.	`src/ValueObjects/Margin.php` (thứ tự thuộc tính được khai báo trực tiếp).
Đích đến đầu ra là enum `NextPDF\Contracts\OutputDestination`; `'I'/'D'/'F'/'S'` không được chấp nhận.	`src/Contracts/OutputDestination.php` (các trường hợp `Inline`/`Download`/`File`/`String`); `tests/Unit/Core/Concerns/DocumentOutputDestinationDispatchTest.php`.
`Output('','S')` → `getPdfData()`; `Output($path,'F')` → `save($path)`.	`src/Core/Concerns/HasOutput.php` (`getPdfData()`, `save()`, `output()`).
`SetProtection()` ánh xạ sang `setEncryption(...)`; quyền hạn phụ thuộc vào sự hợp tác của trình đọc.	`src/Core/Concerns/HasSecurity.php` (`setEncryption()`); ISO 32000-2 §14 (`citations:` ở front-matter).
`SetTitle()` → `setTitle()`; siêu dữ liệu nằm trong từ điển thông tin / XMP.	`src/Core/Concerns/HasMetadata.php` (`setTitle()`); `tests/Unit/Core/Concerns/DocumentInfoMetadataSetterBaselineTest.php`; ISO 32000-2 §14 (`citations:` ở front-matter).
Phông chữ luôn được nhúng dưới dạng các chương trình tập con.	`tests/Unit/Core/Concerns/DocumentTextOutputFontSubsettingAndBorderEdgeCaseTest.php`; `examples/04-text-and-fonts.php`; ISO 32000-2 §9 (`citations:` ở front-matter).
Việc đối sánh / dự phòng phông chữ là đặc thù của từng engine (khác biệt khi thay thế).	CSS Fonts 4 §5.5 (`citations:` ở front-matter + Tuân thủ).
`writeHtml()` chạy một lượt; bộ nhớ đỉnh bám theo kích thước tài liệu.	`docs/architecture/adr/ADR-001-stream-based-rendering-pipeline.md`.

Khôi phục

Cả hai gói vẫn được cài đặt cho đến lần chuyển đổi cuối cùng, nên việc khôi phục theo từng điểm gọi nghĩa là hoàn nguyên điểm gọi đó về đường dẫn mPDF. Sau lần chuyển đổi cuối cùng, khôi phục nghĩa là phục hồi mpdf/mpdf và mã trước đó từ hệ thống quản lý phiên bản. Không liên quan đến việc di chuyển dữ liệu.

Cân nhắc về hiệu năng

Xem Hiệu năng. Mô hình chạy một lượt loại bỏ chi phí bộ đệm được giữ lại của mPDF. Chi phí mới theo từng tài liệu là việc phân giải phông chữ ở bước đầu (bước 3), vốn có thể được lưu vào bộ nhớ đệm qua thư mục phông chữ.

Cạm bẫy thường gặp

Giữ khóa mode và mong đợi hành vi CJK từ nó; NextPDF bỏ qua khóa này, và CJK là vấn đề chọn phông chữ.
Truyền WriteHTML($html, 2) (chế độ chỉ CSS); thay vào đó, hãy dùng CSS nội tuyến.
Dán HTML header/footer vào phần thân.
Mong đợi một bí danh mPDF phân giải sang cùng một phông chữ mà không có họ phông chữ rõ ràng.
Mong đợi đầu ra byte/pixel-identical (các engine độc lập — hướng dẫn này không bao giờ tuyên bố đây là sự thay thế trực tiếp hay tương thích (không phải byte-identical)).
Coi bảng hỗ trợ CSS là tài liệu tham khảo có tính khuyến nghị; đó là nguồn thẩm quyền về các tính năng đã được xác minh.