Di chuyển từ FPDF sang NextPDF

Tổng quan nhanh

Hướng dẫn này giúp bạn chuyển một mã nguồn dựa trên FPDF sang NextPDF core. FPDF là một trong những thư viện Portable Document Format (PDF) PHP cũ được triển khai rộng rãi nhất, và bề mặt vẽ của nó — AddPage, SetFont, Cell, MultiCell, Write, Text, Image, Output được điều khiển bởi một con trỏ x/y thủ công — ánh xạ gọn gàng sang chính API cell/text của NextPDF, vì các phương thức vẽ ở cấp thấp của NextPDF theo cùng dòng dõi FPDF/TCPDF. Tuy nhiên, NextPDF không phải là một bản sao FPDF cắm-là-chạy: nó là một engine PDF 2.0 hiện đại với kiểu nghiêm ngặt, tạo tập con phông chữ, ký, PDF/A, và khả năng tiếp cận (tagged PDF). Hai dịch chuyển thực sự là mô hình đơn vị (NextPDF làm việc theo điểm PDF; FPDF mặc định theo milimét) và các động từ đầu ra (một enum OutputDestination có kiểu thay cho các ký tự 'I'/'D'/'F'/'S' của FPDF).

Không có lớp shim FPDF nào trong core. Hãy viết lại mỗi vị trí lệnh gọi bằng ánh xạ động từ. Nếu bạn muốn thay đổi ban đầu nhỏ nhất cho một mã nguồn TCPDF 6.x thay vì vậy, xem bộ chuyển đổi tương thích TCPDF, vốn đi kèm một lối cắm-là-chạy gần-tương-thích-nguồn; FPDF không có bộ chuyển đổi như vậy.

Cài đặt

composer require nextpdf/core:^3

Giữ setasign/fpdf (hoặc fpdf/fpdf của bạn) đượ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

FPDF và NextPDF chia sẻ cùng một mô hình tư duy: một tài liệu gồm các trang, một con trỏ (vị trí x/y hiện tại), và các động từ vẽ tại hoặc tiến con trỏ đó. SetXY, Cell, Ln, và MultiCell đều đọc và thay đổi con trỏ trong cả hai thư viện, nên hầu hết mã FPDF thủ tục dịch từng dòng.

Các khác biệt là có chủ đích, không phải tình cờ:

Đơn vị. Hàm khởi tạo của FPDF (new FPDF($orientation, $unit, $size)) mặc định theo milimét. NextPDF làm việc theo điểm PDF (1 pt = 1/72 in, ISO 32000-2 §7). Không có nút đơn vị toàn-tài-liệu — hãy chuyển mm sang điểm một lần (pt = mm * 72 / 25.4).
Hướng Y giữ nguyên cho bạn. Giống FPDF, các tọa độ người dùng của NextPDF đặt y = 0 ở đỉnh trang và tăng xuống dưới, nên số học con trỏ chuyển trực tiếp. NextPDF chuyển sang gốc dưới-trái native của PDF ở bên trong.
Việc khởi tạo là tường minh. FPDF gấp hướng, đơn vị, và kích thước vào hàm khởi tạo; NextPDF nhận một đối tượng giá trị bất biến NextPDF\Core\Config (kích thước trang, lề, thư mục phông chữ) và một addPage() tường minh.
Luôn Unicode, luôn tạo tập con. Bản build core của FPDF là Latin-1 và cần biến thể tFPDF/UTF-8 cho Unicode. NextPDF là UTF-8 xuyên suốt và luôn nhúng phông chữ dưới dạng các chương trình tập con (ISO 32000-2 §9). Các tệp AddFont/metric-phông-chữ của FPDF không có đối ứng; hãy đăng ký một thư mục phông chữ TrueType/OpenType và chọn họ theo tên.

Bề mặt API

Các điểm vào core dùng bên dưới là Document::createStandalone(), Document::addPage(), Document::setFont(), Document::cell(), Document::multiCell(), Document::text(), Document::write(), Document::ln(), Document::image(), các bộ truy cập con trỏ (setXY/setX/ setY/getX/getY), Document::output(?string, OutputDestination), Document::save(string $path): void, Document::getPdfData(): string, và đối tượng giá trị NextPDF\Core\Config. Tài liệu tham chiếu đầy đủ cho các phương thức vẽ, văn bản, và đầu ra core này nằm trong các module core và chỉ mục tham chiếu, được tự sinh từ PHPDoc. Module Html là tài liệu đọc liên quan cho HTML-sang-PDF, không phải tham chiếu cho các động từ trên trang này.

Ánh xạ động từ API

Các tên phương thức công khai của FPDF lâu đời và nổi tiếng. Cột NextPDF dưới đây được xác nhận đối chiếu với các chữ ký nguồn core (xem Bằng chứng / khả năng truy vết).

FPDF	NextPDF	Ghi chú
`new FPDF($orient, $unit, $size)`	`Document::createStandalone($config)`	Các đối số hàm khởi tạo hướng/đơn vị/kích thước trở thành một `NextPDF\Core\Config` (`pageSize`, `margins`, `fontsDirectory`). Không có `$unit` — làm việc theo điểm. Trang `createStandalone()` mặc định là A4 dọc.
`$pdf->AddPage($orient, $size)`	`$doc->addPage($size, $orientation)`	Ánh xạ trực tiếp. `$size` là một đối tượng giá trị `PageSize`; `$orientation` là enum `Orientation` (`Portrait`/`Landscape`).
`$pdf->SetFont($family, $style, $size)`	`$doc->setFont($family, $style, $size)`	Ánh xạ trực tiếp. `$style` dùng cùng các mã `''`/`'B'`/`'I'`/`'BI'` (cộng với `'U'` gạch dưới).
`$pdf->Cell($w, $h, $txt, $border, $ln, $align, $fill)`	`$doc->cell($w, $h, $txt, $border, $newLine, $align, $fill)`	Ánh xạ trực tiếp. `$align` là enum `Alignment` (`Left`/`Center`/`Right`/`Justify`); `$border` chấp nhận `bool` hoặc một chuỗi `'LTRB'`; `$ln` trở thành `bool $newLine`.
`$pdf->MultiCell($w, $h, $txt, $border, $align, $fill)`	`$doc->multiCell($w, $h, $txt, $border, $align)`	Ngắt từ theo metric phông chữ thực. Không có đối số `$fill`; hãy vẽ một `rect()` được tô trước nếu bạn cần một nền.
`$pdf->Write($h, $txt, $link)`	`$doc->write($h, $txt, $link)`	Văn bản chảy từ con trỏ; `$link` gắn một chú thích liên kết URL.
`$pdf->Text($x, $y, $txt)`	`$doc->text($x, $y, $txt)`	Văn bản vị-trí-tuyệt-đối. Ánh xạ trực tiếp.
`$pdf->Ln($h)`	`$doc->ln($h)`	Ngắt dòng tới lề trái; `0` = chiều cao dòng mặc định.
`$pdf->Image($file, $x, $y, $w, $h)`	`$doc->image($file, $x, $y, $w, $h)`	Ánh xạ trực tiếp; `$x`/`$y`/`$w`/`$h` có thể null (null = con trỏ hiện tại / kích thước nội tại).
`$pdf->SetXY($x, $y)` / `SetX` / `SetY`	`$doc->setXY($x, $y)` / `setX` / `setY`	Ánh xạ trực tiếp. `getX()`/`getY()` đọc con trỏ.
`$pdf->SetMargins($l, $t, $r)`	`$doc->setMargins(new Margin($t, $r, $bottom, $l))`	Một đối tượng giá trị `Margin`; thứ tự hàm khởi tạo là `(top, right, bottom, left)` — không phải `(left, top, right)` của FPDF. FPDF `SetMargins` không có đối số bottom (lề dưới của nó đến từ `SetAutoPageBreak($auto, $margin)`), nên hãy tự chọn `$bottom` — thường bằng lề trên, hoặc truyền lề ngắt-trang-tự-động.
`$pdf->SetAutoPageBreak($auto, $margin)`	`$doc->setAutoPageBreak($auto, $margin)`	Ánh xạ trực tiếp.
`$pdf->SetDrawColor` / `SetFillColor` / `SetTextColor`	`$doc->setDrawColor` / `setFillColor` / `setTextColor`	RGB `(r, g, b)`, hoặc một giá trị duy nhất cho thang xám.
`$pdf->Line` / `Rect` / `SetLineWidth`	`$doc->line` / `rect` / `setLineWidth`	Ánh xạ trực tiếp. `rect()` nhận một chuỗi style (`'S'`/`'F'`/`'DF'`).
`$pdf->SetTitle/SetAuthor/SetSubject/SetKeywords/SetCreator`	`$doc->setTitle/setAuthor/setSubject/setKeywords/setCreator`	Ánh xạ trực tiếp. Rơi vào từ điển thông tin ISO 32000-2 §14 / Extensible Metadata Platform (XMP).
`$pdf->Output($dest, $name)`	`$doc->output($name, OutputDestination::…)`	Các ký tự đích FPDF (`I`/`D`/`F`/`S`) ánh xạ sang enum `OutputDestination`; lưu ý thứ tự đối số hoán đổi (tên trước trong NextPDF).
`$pdf->Output('S')`	`$doc->getPdfData()`	Trả về các byte PDF.
`$pdf->Output('F', $path)`	`$doc->save($path)`	Ghi vào một đường dẫn tệp.
`$pdf->GetStringWidth($s)`	(no public method)	Độ rộng chuỗi được tính ở bên trong trong lúc ngắt của `cell()`/`multiCell()`; không có động từ đo theo-từng-chuỗi công khai. Hãy điều khiển việc ngắt qua `multiCell()` thay vì đo bằng tay.

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

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\Alignment;
use NextPDF\Core\Document;

// FPDF:
//   $pdf = new FPDF();           // mm, A4 portrait
//   $pdf->AddPage();
//   $pdf->SetFont('Arial', 'B', 16);
//   $pdf->Cell(40, 10, 'Invoice');
//   $pdf->Output('F', 'out.pdf');

// NextPDF — points, default page is A4 portrait:
$doc = Document::createStandalone();
$doc->setTitle('Invoice');
$doc->addPage();
$doc->setFont('Helvetica', 'B', 16.0);
$doc->cell(113.4, 28.3, 'Invoice', false, true, Alignment::Left); // ~40mm x ~10mm in points
$doc->save(__DIR__ . '/out.pdf');

echo "Wrote out.pdf\n";

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

Ví dụ này khớp với examples/04-text-and-fonts.php. Nó dùng một kích thước trang tường minh, các lề, một thư mục phông chữ đã đăng ký, và mô hình cell được điều khiển bởi con trỏ mà một mã nguồn FPDF vốn đã dùng.

<?php

declare(strict_types=1);

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

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

// Equivalent of: new FPDF('P', 'mm', 'A4') + SetMargins(20, 16, 20)
// i.e. FPDF left=20mm, top=16mm, right=20mm. FPDF SetMargins has no bottom
// argument, so we pick bottom = top = 16mm. Convert each mm to points
// (pt = mm * 72 / 25.4): 16mm = 45.354pt, 20mm = 56.693pt.
// Margin constructor order is (top, right, bottom, left) — NOT FPDF's (L, T, R).
$config = new Config(
    pageSize: new PageSize(595.276, 841.890, 'A4'),
    margins: new Margin(45.354, 56.693, 45.354, 56.693), // top,right,bottom,left in points
    fontsDirectory: __DIR__ . '/fonts',
);

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

// SetFont + Cell, the FPDF way — but in points and with a real Unicode font.
$doc->setFont('DejaVuSans', 'B', 18.0);
$doc->setTextColor(30, 58, 138);
$doc->cell(0, 24.0, 'Quarterly Report', false, true, Alignment::Left);

$doc->setFont('DejaVuSans', '', 11.0);
$doc->setTextColor(0, 0, 0);
$doc->multiCell(0, 16.0, "Body text wraps on real font metrics. Unicode is "
    . "native, so accented and non-Latin characters need no tFPDF variant — "
    . "register the family in the fonts directory and select it by name.");

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

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

Đơn vị. Mọi tọa độ số, độ rộng, chiều cao, và lề bạn sao chép từ FPDF đều theo milimét mặc định. Hãy nhân với 72 / 25.4 để ra điểm, một lần, trong quá trình chuyển. Trộn lẫn hai cái âm thầm định cỡ sai mọi thứ.
Thứ tự đối số của Output(). FPDF là Output($dest, $name); NextPDF là output($name, $dest). Đích là enum OutputDestination, không phải một ký tự. Hãy ưu tiên save() / getPdfData() cho đầu ra tệp / chuỗi.
Thứ tự của SetMargins. FPDF là (left, top, right); đối tượng giá trị Margin của NextPDF là (top, right, bottom, left). Hãy sắp xếp lại, đừng chép nguyên.
Phông chữ. Các tệp AddFont() + .php metric của FPDF không có tương đương. Đặt tệp TrueType/OpenType vào thư mục phông chữ và gọi setFont() với tên họ. Các tên Base14 của Core (Helvetica, Times, Courier) phân giải không cần một tệp; dưới PDF/A hoặc tagged PDF chúng được tự động thay thế bằng một phông chữ nhúng được.
GetStringWidth. Không có phương thức đo-chuỗi công khai. Nếu mã FPDF của bạn đo các chuỗi để bố trí cột bằng tay, hãy chuyển khối đó sang multiCell() (vốn ngắt theo metric) hoặc các lệnh gọi cell() chiều-rộng-cố-định.

Hiệu năng

NextPDF phát nội dung trong một lượt stream duy nhất (bản ghi quyết định kiến trúc ADR-001); đỉnh bộ nhớ bám theo kích thước tài liệu, không phải một cây đối tượng được giữ lại. Ngân sách cho ví dụ của hướng dẫn này là wall_ms: 2000, peak_mb: 128. Với các tài liệu dài, hãy điều khiển nội dung qua các lệnh gọi addPage() — cùng hình dạng vòng lặp mà một báo cáo FPDF vốn đã dùng.

Ghi chú bảo mật

Metadata. SetTitle()/SetAuthor() ánh xạ sang các setter có kiểu ghi vào từ điển thông tin ISO 32000-2 §14 / XMP. Đừng bao giờ lưu bí mật ở đó.
Đường dẫn ảnh. image() từ chối các lược đồ stream-wrapper và các byte NUL được nhúng trước khi đọc. Hãy truyền các đường dẫn do ứng dụng kiểm soát.
Không có mã trong-tài-liệu. NextPDF không thực thi script trong-tài-liệu nào; không gì trong FPDF thay đổi điều đó.

Tuân thủ

Tuyên bố	Spec	Điều khoản
Định dạng/hướng trang ánh xạ sang hộp ranh giới trang.	ISO 32000-2	§7
Phông chữ được ghi dưới dạng các chương trình phông chữ nhúng/tập con.	ISO 32000-2	§9
Tiêu đề / metadata rơi vào từ điển thông tin / XMP.	ISO 32000-2	§14
Đường, hình chữ nhật, và ảnh là việc tô luồng-nội-dung.	ISO 32000-2	§8

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 FPDF. Hãy xem xét lại đầu ra bất cứ khi nào bạn đổi renderer.

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

Không áp dụng. NextPDF core phủ lối di chuyển FPDF đượ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 FPDF (hoặc tFPDF) để tạo PDF thủ tục phía máy chủ. Nếu mã của bạn là một chuỗi các lệnh gọi AddPage / SetFont / Cell / MultiCell / Image / Output được điều khiển bởi SetXY và Ln, thì ánh xạ động từ phủ toàn bộ bề mặt của bạn.

Phạm vi

Trong phạm vi: các động từ vẽ của FPDF, mô hình con trỏ, phông chữ, màu sắc, đường và hình chữ nhật, metadata, và đầu ra. Ngoài phạm vi: bộ công cụ tệp-metric AddFont của FPDF và các mở-rộng-script FPDF của bên thứ ba (mã vạch, xoay, bookmark) — hãy ánh xạ chúng sang các module NextPDF tương ứng (Barcode, Transforms, Navigation), vốn không được bao quát ở đây.

Bảng tương thích

Tương thích về hành vi, không phải một shim cắm-là-chạy: core không cung cấp lớp shim FPDF nào. Hãy viết lại mọi vị trí lệnh gọi. Các động từ xếp khớp sát nhau vì API cell/text của NextPDF chia sẻ dòng dõi FPDF/TCPDF, nhưng mô hình đơn vị, thứ tự đối số Output, và các kiểu Margin/enum khác nhau — nên một bản chép nguyên là sai, một bản dịch mới đúng.

Ánh xạ đơn vị và cấu hình

Cấu trúc FPDF	NextPDF	Ghi chú
`$unit` (`'mm'` default)	(no equivalent)	Làm việc theo điểm PDF. Chuyển các kích thước với `pt = mm * 72 / 25.4` một lần trong quá trình chuyển.
`$orientation` (`'P'`/`'L'`)	`Orientation` enum on `addPage()`, or swap `PageSize` width/height	Ngang = chiều rộng > chiều cao.
`$size` (`'A4'`, `[w,h]`)	`Config->pageSize` (`PageSize` value object)	Các định dạng có tên trở thành kích thước điểm tường minh; các factory `PageSize::A4()`…`A0()` và `Letter`/`Legal` tồn tại.
`SetMargins($l, $t, $r)`	`Config->margins` (`Margin` VO)	Thứ tự hàm khởi tạo `(top, right, bottom, left)`.
`AddFont($family, $style, $file)`	fonts directory + `setFont()` by name	Bỏ tệp metric; đặt TTF/OTF vào `Config->fontsDirectory`.

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

Các thư mục phông chữ. Việc đăng ký AddFont theo-từng-phông của FPDF gom lại thành một thư mục phông chữ cộng với việc đối sánh họ qua setFont(). Hãy bắt đầu với Config->fontsDirectory (đường dẫn tìm kiếm mặc định); đăng ký các thư mục bổ sung qua FontRegistry::addFontDirectory() hoặc Document::addFontDirectory() khi phông chữ nằm ở nhiều nơi.
Luôn Unicode. Không có mặc định Latin-1 và không có bản build tFPDF riêng; đầu vào UTF-8 là chuẩn mực.
Luôn tạo tập con. NextPDF luôn tạo tập con các phông chữ nhúng (ISO 32000-2 §9); các lựa chọn nhúng-phông-chữ của FPDF không có tương đương và không cần thiết.
Đặt lại đường cơ sở glyph. Việc đối sánh và dự phòng phông chữ là đặc thù của từng engine; một bí danh phông chữ FPDF có thể cần một tên họ chính xác. Các khác biệt khi thay thế là dự kiến, không phải lỗi.

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

Chuyển đổi đơn vị (mm → pt) — lỗi chuyển phổ biến nhất; xem ở trên.
Thứ tự đối số Output hoán đổi và đích trở thành một enum.
Margin / Alignment / Orientation là các đối tượng/enum có kiểu, không phải các ký tự hay bộ ba vị trí (l, t, r).
Không có GetStringWidth công khai — hãy điều khiển việc ngắt qua multiCell().
Raster hóa độc lập — việc ngắt dòng và phân trang trên nội dung dày đặc có thể khác; hãy đặt lại đường cơ sở cho các diff hình ảnh.

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

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

Bộ chọn $unit của FPDF — không được mô hình hóa (luôn là điểm).
Các tệp metric AddFont() + .php/.z — được thay bằng một thư mục phông chữ.
GetStringWidth() — không có động từ đo-chuỗi công khai.
Các ký tự đích 'I'/'D'/'F'/'S' của FPDF — được thay bằng enum OutputDestination + save()/getPdfData().

Mã phụ thuộc vào những thứ này không “di chuyển” nguyên văn. Hãy diễn đạt lại nó bằng các hàng ở trên.

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

Thêm nextpdf/core bên cạnh FPDF; giữ FPDF được cài tạm thời.
Chọn một tài liệu ít rủi ro. Chuyển đổi hàm khởi tạo qua ánh xạ đơn vị, rồi port từng động từ với ánh xạ động từ. Chuyển mọi tọa độ mm sang điểm.
Đặt các phông chữ của tài liệu vào Config->fontsDirectory và chọn chúng theo tên họ; bỏ các lệnh gọi AddFont.
Tạo cả hai PDF cho cùng một đầu vào và so sánh trực quan chúng. Các khác biệt (thay thế phông chữ, ngắt dòng) là dự kiến cho các engine độc lập — hãy chấp nhận chúng theo từng tài liệu.
Thay bất kỳ bố-cục-bằng-tay dựa-trên-GetStringWidth nào bằng multiCell() hoặc các lệnh gọi cell() chiều-rộng-cố-định.
Lặp lại theo từng tài liệu, ít rủi ro nhất trước; giữ FPDF được cài cho tới lần chuyển đổi cuối cùng.
Gỡ FPDF khỏi composer.json sau lần chuyển đổi cuối cùng.

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

Chụp snapshot đầu ra FPDF cho các tài liệu tiêu biểu trước khi bạn đổi mã (đầu vào golden; các byte sẽ khác).
Với mỗi tài liệu được di chuyển, hãy khẳng định việc chấp nhận bằng kiểm tra của riêng bạn (so sánh trực quan + trích xuất văn bản). Hành vi cell/phông-chữ của NextPDF được thực thi bởi examples/04-text-and-fonts.php cộng với các bộ Font và text-output trong tests/ của core. Việc chấp nhận di chuyển là đặc thù theo tài liệu và vẫn là 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 được 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 chữ ký nguồn, ví dụ, 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 trong citations: ở front-matter và bảng Tuân thủ. Hành vi FPDF 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ố hành vi của NextPDF	Bằng chứng trong kho (đường dẫn)
`AddPage` ánh xạ sang `addPage(?PageSize, Orientation): static`.	`src/Core/Concerns/HasPages.php` (`addPage()`).
`SetFont($family, $style, $size)` ánh xạ sang `setFont(string, string, float): static`; các style `''`/`'B'`/`'I'`/`'BI'`/`'U'`.	`src/Core/Concerns/HasTypography.php` (`setFont()`).
`Cell` ánh xạ sang `cell($w, $h, $txt, $border, $newLine, $align, $fill): static`.	`src/Core/Concerns/HasTextOutput.php` (`cell()`).
`MultiCell` ánh xạ sang `multiCell($w, $h, $txt, $border, $align): static` (ngắt dựa-trên-metric).	`src/Core/Concerns/HasTextOutput.php` (`multiCell()`, `wrapText()`).
`Write`/`Text`/`Ln` ánh xạ sang `write()`/`text()`/`ln()`.	`src/Core/Concerns/HasTextOutput.php` (`write()`, `text()`, `ln()`).
`SetXY`/`SetX`/`SetY`/`GetX`/`GetY` ánh xạ trực tiếp; `SetMargins` nhận một `Margin` VO.	`src/Core/Concerns/HasPages.php` (`setXY()`, `getX()`, `setMargins()`); `src/ValueObjects/Margin.php` (`(top, right, bottom, left)`).
`Image` ánh xạ sang `image($file, ?$x, ?$y, ?$w, ?$h): static`; từ chối các đường dẫn scheme/NUL.	`src/Core/Concerns/HasImages.php` (`image()`, `assertImageFilePath()`).
`Line`/`Rect`/`SetLineWidth`/`SetDrawColor`/`SetFillColor`/`SetTextColor` ánh xạ trực tiếp.	`src/Core/Concerns/HasDrawing.php` (`line()`, `rect()`, `setLineWidth()`); `src/Core/Concerns/HasColors.php` (`setDrawColor()`, `setFillColor()`, `setTextColor()`).
Trang mặc định của `createStandalone()` là A4 dọc (`595.276 × 841.890 pt`).	`src/Core/Document.php` (`createStandalone()`); `src/ValueObjects/PageSize.php` (`A4()`).
Đích đầu ra là enum `OutputDestination` (`Inline`/`Download`/`File`/`String`); `Output('S')` → `getPdfData()`, `Output('F', $p)` → `save($p)`.	`src/Contracts/OutputDestination.php`; `src/Core/Concerns/HasOutput.php` (`output()`).
`SetTitle`/`SetAuthor`/… ánh xạ sang các setter metadata có kiểu; rơi vào từ điển thông tin / XMP.	`src/Core/Concerns/HasMetadata.php` (`setTitle()`, `setAuthor()`); 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.	`src/Core/Concerns/HasTypography.php` (`buildFontData()`); ISO 32000-2 §9 (`citations:` ở front-matter).
Nội dung được phát một-lượt.	`docs/architecture/adr/ADR-001-stream-based-rendering-pipeline.md`.

Khôi phục

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

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

Xem Hiệu năng. Mô hình một-lượt loại bỏ mọi chi phí bộ đệm được giữ lại. Chi phí mới theo từng tài liệu là việc phân giải phông chữ háo hức (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

Chép các tọa độ milimét thành điểm mà không có phép chuyển * 72 / 25.4.
Để Output() theo thứ tự ($dest, $name) của FPDF, hoặc truyền một ký tự thay vì enum OutputDestination.
Chép SetMargins($l, $t, $r) thẳng vào Margin (vốn có thứ tự top, right, bottom, left).
Mong các tệp metric AddFont sẽ port; hãy đặt TTF/OTF vào thư mục phông chữ thay vì vậy.
Với tới một tương đương GetStringWidth; hãy dùng multiCell() cho việc ngắt.
Mong đợi đầu ra giống hệt từng byte/pixel (các engine độc lập — hướng dẫn này không bao giờ khẳng định cắm-là-chạy hay tương thích 100%).