Rời khỏi thư viện cũ: TCPDF, FPDF, và những thư viện tương tự

Spec: ISO 32000-2Spec: ISO 19005-4Spec: ETSI EN 319 142-1

Tổng quan nhanh

Nếu các PDF của bạn được tạo bởi TCPDF, FPDF, mPDF, hay dompdf, mã nguồn có lẽ vẫn chạy. Đó đúng là lý do khiến rắc rối dễ bị bỏ sót. Thư viện chạy, tệp mở được, và lỗ hổng chỉ lộ ra vào ngày ai đó yêu cầu một tài liệu đã ký, có thể lưu trữ, hay tiếp cận được và câu trả lời là “từ đây thì chúng ta không làm được.”

Trang này là câu chuyện di trú: những bức tường đó là gì, vì sao chúng mang tính cấu trúc chứ không phải ngẫu nhiên, và cách NextPDF cho bạn một lối đi theo từng giai đoạn để rời khỏi chúng — bao gồm một bề mặt tương thích TCPDF vốn là một công cụ hỗ trợ di trú, không phải một lời hứa thay thế tại chỗ giống hệt từng byte.

Vì sao điều này quan trọng

Một thư viện PDF không phải là một lời gọi kết xuất mà bạn thực hiện một lần. Nó là một dependency mà các tài liệu của bạn thừa hưởng chừng nào chúng còn tồn tại. Khi dependency đó ngừng chuyển động, các tài liệu của bạn ngừng có khả năng làm những việc mới — và bạn phát hiện ra điều đó vào thời điểm tệ nhất có thể, khi một khách hàng, một kiểm toán viên, hay một cơ quan quản lý đặt ra chuẩn.

Những bức tường trông như thế này. Định dạng đã tiến lên: PDF 2.0 là phiên bản hiện hành của chuẩn (Spec: ISO 32000-2), và một bộ ghi kẹt lại ở cấu trúc 1.x thì đã tụt sau định dạng mà phần còn lại của toolchain của bạn giả định. Việc ký mỏng manh hoặc bị gắn thêm vào, kém xa các profile baseline PAdES khiến một chữ ký đứng vững (Spec: ETSI EN 319 142-1, §4). Đầu ra lưu trữ sang họ PDF/A, và cấu trúc được gắn thẻ cho khả năng tiếp cận, hoặc vắng mặt hoặc mong manh. Và bản thân API thì không định kiểu — hướng kiểu chuỗi, các boolean theo vị trí, các giá trị mặc định mà bạn phát hiện ra một cách tình cờ — nên trình biên dịch không thể giúp bạn và một người duyệt mã cũng không.

Không cái nào trong số này là lỗi mà bạn có thể vá quanh. Chúng là hình dạng của một công cụ được dựng cho một thập kỷ trước đó, và vài công cụ trong số đó không còn tích cực tiến về phía các chuẩn mà tài liệu của bạn bây giờ phải đáp ứng.

Phiên bản ngắn gọn

Các thư viện PDF PHP cũ hầu hết vẫn chạy. Vấn đề là những gì chúng thường không thể tạo ra với mức tuân thủ hiện đại đầy đủ: PDF 2.0, các chữ ký tuân thủ baseline, PDF/A đã được kiểm định, khả năng tiếp cận được gắn thẻ — sự hỗ trợ trên các thư viện được nêu tên là hạn chế hoặc vắng mặt.
NextPDF là một engine PHP 8.4 ghi PDF 2.0 theo mặc định, với định kiểu nghiêm ngặt, các profile lưu trữ, và ký PAdES như các đầu ra hạng nhất.
Bạn không phải viết lại mọi thứ ngay ngày đầu. Bề mặt tương thích TCPDF cho phép các lời gọi quen thuộc tiếp tục hoạt động trong khi bạn dời phần logic tài liệu quan trọng.
Bề mặt đó tương thích với, chứ không giống hệt từng byte với TCPDF. Nó là một cây cầu bắc qua cuộc di trú, với các khác biệt hành vi được ghi lại — không phải một tuyên bố rằng mọi script đều chạy nguyên vẹn.
Phép thử thẳng thắn là liệu các khả năng mới có đáng để dời đi hay không. Với một số workload thì không đáng, và chúng tôi nói thẳng điều đó.

Cách NextPDF tiếp cận việc này

Cách tiếp cận là biến di trú thành một chuỗi, không phải một bước nhảy. Bạn tiếp tục tạo ra tài liệu suốt cả chặng đường, và bạn đổi bỏ các ràng buộc cũ từng cái một thay vì đặt cược cả một bản phát hành vào một cuộc viết lại “bùng nổ một lần.”

InventoryCatalogue what your documents actually need to emit — signatures, archival profiles, tagged structure, fonts — not just which calls you make today.
BridgeAdopt the TCPDF-compatibility surface so the existing call sites keep producing files while the engine underneath becomes NextPDF.
PortMove the document logic that matters onto the native typed API, where intent is explicit and the compiler checks it.
UpgradeTurn on the outputs many legacy libraries cannot reach with full modern conformance: PDF 2.0 structure, validated PDF/A, PAdES signatures, tagged accessibility.
VerifyConfirm the result against a real validator, so 'archival' or 'signed' means a tool agrees, not just that the file opened.

A staged migration off a legacy PDF library: start on the compatibility surface so existing calls keep working, then move document logic onto the typed native API, then turn on the standards-grade outputs (PDF 2.0, PDF/A, PAdES, accessibility) that many legacy libraries cannot produce with full modern conformance.

PDF 2.0 là nền tảng, không phải một cờ tính năng. NextPDF ghi phiên bản hiện hành của định dạng theo mặc định (Spec: ISO 32000-2), và có thể tuần tự hóa các cấu trúc cũ hơn khi một profile yêu cầu chúng. Một thư viện đông cứng ở cấu trúc 1.x không thể gặp bạn ở đây; không phải một thiết lập mà nó thiếu, mà là một thời đại mà nó ra đời trước.

Lưu trữ và khả năng tiếp cận là các tính chất của bộ ghi. Tạo ra một tệp mà một trình kiểm định chấp nhận là PDF/A là điều engine phải làm khi nó ghi — nó không thể được dập ghim vào sau (Spec: ISO 19005-4). Điều tương tự đúng với cấu trúc được gắn thẻ làm cho một PDF tiếp cận được. NextPDF dựng những thứ này trong quá trình tạo, vốn chính là bước mà nhiều công cụ cũ không thể thực hiện — hoặc chỉ thực hiện một phần, kém xa mức một trình kiểm định chấp nhận.

Việc ký vượt qua mức baseline. Các chữ ký điện tử nâng cao trong một PDF tuân theo các profile PAdES (Spec: ETSI EN 319 142-1, §4), nơi digest bao phủ một dải byte đã khai báo và chữ ký mang theo siêu dữ liệu mà một trình kiểm định kiểm tra. Một bộ hỗ trợ ký gắn thêm hiếm khi đạt tới mức đó. NextPDF coi nó là một đầu ra hạng nhất, không phải một thứ phụ thêm vào sau.

Bề mặt tương thích là cây cầu, được nêu một cách thẳng thắn. Tầng tương thích TCPDF tồn tại để các vị trí gọi hiện có của bạn tiếp tục tạo ra tài liệu trong khi bạn di trú những phần quan trọng. Nó theo cùng một mô hình như mọi hướng dẫn di trú của NextPDF: tương thích với thư viện nguồn, không giống hệt từng byte, với các khác biệt hành vi được ghi lại. Sự thẳng thắn đó chính là điểm mấu chốt — một tuyên bố thầm lặng kiểu “thay thế tại chỗ 99%” chính là loại phỏng đoán mà engine này được dựng ra để từ chối.

Lý do để di trú hiếm khi là mã nguồn bạn có hôm nay; nó là tài liệu mà bạn sẽ được yêu cầu vào ngày mai. Khả năng bảo trì là một thuộc tính chất lượng có tên — mức độ một hệ thống có thể được phân tích và thay đổi dễ dàng ra sao khi nhu cầu dịch chuyển (Spec: ISO/IEC 25010, §3.6). Một dependency đã ngừng chuyển động lặng lẽ làm xói mòn nó, và bạn chỉ cảm nhận được cái giá khi một yêu cầu mới tới và câu trả lời buộc phải là “từ đây thì không.” Một cuộc dời đi theo từng giai đoạn trả cái giá đó theo lịch trình của bạn, trong khi các tài liệu vẫn tiếp tục chảy, thay vì tất cả cùng một lúc dưới áp lực hạn chót.

Ví dụ thực tế

Hình dạng của một cuộc di trú là nhỏ ở vị trí gọi. Mã cũ tiếp tục tạo ra một tệp qua bề mặt tương thích; mã mới nêu ý định qua API native có định kiểu và yêu cầu một đầu ra mà thư viện cũ không thể đạt tới, hoặc chỉ đạt tới với mức tuân thủ hạn chế.

<?php

declare(strict_types=1);

use NextPDF\Compat\Tcpdf\TCPDF;
use NextPDF\Contracts\Orientation;
use NextPDF\Contracts\OutputDestination;
use NextPDF\Core\Document;
use NextPDF\ValueObjects\PageSize;

// 1) The bridge: a familiar TCPDF-shaped call keeps producing a file
//    while the engine underneath is already NextPDF. Behaviour is
//    compatible, not byte-identical — differences are documented.
$legacy = new TCPDF();
$legacy->AddPage();
$legacy->SetFont('helvetica', 'B', 16);
$legacy->Cell(0, 12, 'Migrated invoice', ln: 1);
$bridgedBytes = $legacy->Output('', 'S');

// 2) The destination: the same document expressed natively, where intent
//    is typed and the engine can emit what many legacy tools cannot.
$document = Document::createStandalone();
$document->setTitle('Migrated invoice');
$document->addPage(PageSize::a4(), Orientation::Portrait);
$document->setFont('helvetica', 'B', 16);
$document->cell(0, 12, 'Migrated invoice', newLine: true);

// Bytes only, no HTTP headers, no file side effect — stated, not inferred.
$nativeBytes = $document->output(dest: OutputDestination::String);

Khối đầu là chỗ đặt chân: không gì trong ứng dụng của bạn phải thay đổi để các tài liệu tiếp tục chảy. Khối thứ hai là đích đến: một lời gọi có định kiểu trong đó “portrait”, “string output”, và font là rõ ràng, và nơi lưu trữ, ký, và khả năng tiếp cận trở thành các đầu ra mà bạn có thể bật lên thay vì những bức tường bạn đâm phải.

Hiểu lầm thường gặp

Niềm hy vọng thường gặp là “chắc phải có một cờ làm cho thư viện cũ của tôi làm được PDF 2.0 và chữ ký.” Không có. Đây không phải là các tùy chọn mà một thư viện trưởng thành quên phơi ra; chúng là các khả năng mà kiến trúc của nó chưa bao giờ được dựng quanh. Bạn không thể cấu hình để có được một phiên bản định dạng hay một profile chữ ký mà một bộ ghi không hiện thực.

Hiểu lầm phản chiếu là rằng NextPDF là một bản thay thế tại chỗ 100% cho TCPDF, nên di trú là miễn phí. Nó không phải vậy, và chúng tôi sẽ không giả vờ ngược lại. Bề mặt tương thích bao phủ một lát cắt thật, đã được ghi lại, của API để đưa bạn vượt qua cuộc dời đi; một số lời gọi hành xử khác đi, và một vài lời gọi nằm ngoài phạm vi. Hãy coi nó là một cây cầu có bản đồ được công bố, không phải một bảo đảm rằng mọi script cũ chạy mà không cần đụng tới.

Giới hạn và ranh giới

TCPDF-compatibility surface as a migration aid — edition availability
Edition	Availability
Core	Bề mặt tương thích tương thích với, chứ không giống hệt từng byte với TCPDF. Nó bao phủ một tập con đã được ghi lại của API để giữ cho các vị trí gọi hiện có tiếp tục tạo ra tệp trong lúc di trú. Nó là một cây cầu, không phải một bản thay thế tại chỗ: một số hành vi khác đi và một số lời gọi không được hỗ trợ, tất cả được liệt kê trong các trang về phạm vi phủ phương thức và di trú. Đích đến là API native có định kiểu, nơi đầu ra đạt chuẩn cư trú.
Pro	Available
Enterprise	Available

Di trú là một phương tiện, không phải một đức tính. Nếu các tài liệu của bạn đơn giản, thư viện của bạn vẫn còn được bảo trì, và bạn sẽ không bao giờ cần PDF 2.0, ký, PDF/A, hay khả năng tiếp cận, câu trả lời thẳng thắn có thể là cứ ở yên chỗ bạn đang đứng — chi phí chuyển đổi là có thật và một cuộc dời đi bạn không cần là một cuộc dời đi bạn không nên làm. Trang về khi nào không nên dùng NextPDF vạch ra lằn ranh đó mà không nao núng.

Trang này mô tả lối đi di trú và các đích nhắm của engine. Phạm vi phủ API chính xác, các khác biệt hành vi, và quy trình từng bước nằm trong tài liệu tương thích, vốn là thẩm quyền cho việc mỗi lời gọi làm gì. Không gì ở đây hứa hẹn rằng một script cũ bất kỳ chạy nguyên vẹn.

Tài liệu liên quan

PDF 2.0 đã thay đổi điều gì — phiên bản định dạng mà nhiều thư viện cũ không thể phát ra, và vì sao nó quan trọng.
Bề mặt tương thích TCPDF — hướng dẫn có thẩm quyền về những gì cây cầu bao phủ và nơi nó khác đi.
Khi nào không nên dùng NextPDF — ranh giới thẳng thắn, để một cuộc di trú bạn không cần là một cuộc bạn có thể bỏ qua.
Một engine, mọi framework — nơi engine bạn di trú tới cắm vào ngăn xếp bạn đã chạy.

Bảng thuật ngữ

PDF 2.0 — phiên bản hiện hành của chuẩn Portable Document Format (ISO 32000-2). Được mở rộng ở lần dùng đầu; định dạng mà NextPDF ghi theo mặc định.
PDF/A — họ tuân thủ lưu trữ (chuỗi ISO 19005) định nghĩa điều gì làm cho một PDF an toàn để bảo tồn lâu dài. Một tính chất mà bộ ghi phải tạo ra, không phải một thứ mà người gọi có thể thêm vào sau.
PAdES — PDF Advanced Electronic Signatures, họ profile của ETSI (EN 319 142) để nhúng các chữ ký đạt chuẩn vào một PDF. Được mở rộng ở lần dùng đầu; được bàn sâu trong các trang về ký.
Bề mặt tương thích — một tầng API có hình dạng giống một thư viện nguồn (ở đây là TCPDF) cho phép các vị trí gọi hiện có tiếp tục hoạt động trong lúc di trú. Tương thích với, chứ không giống hệt từng byte với, bản gốc — một cây cầu, không phải một bản thay thế tại chỗ.
Bản thay thế tại chỗ (drop-in replacement) — một thứ thay thế chạy được mã hiện có mà không thay đổi. Bề mặt tương thích TCPDF có chủ đích không được mô tả theo cách này; nó là một công cụ hỗ trợ di trú đã được ghi lại với các khác biệt hành vi đã biết.