Hướng dẫn chọn cách tích hợp

Spec: ISO/IEC/IEEE 26514:2022, §3.x162 Spec: ISO 24495-1:2023, §5 Evidence: Editorial

Tổng quan nhanh

Hệ sinh thái NextPDF gồm một engine lõi nhỏ gọn và một nhóm gói có vai trò tập trung: các cầu nối framework, hai bộ kết xuất HTML, một bộ kết xuất edge và một máy chủ thực thi. Trang này ánh xạ các trường hợp sử dụng thực tế tới gói phù hợp, dựa trên những gì mỗi gói thực sự cung cấp. Quyết định vẫn thuộc về bạn, dựa trên bằng chứng chứ không phải hàm ý trong tài liệu.

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

Chọn sai cách tích hợp sẽ gây tốn kém theo những cách không lộ ra ngay. Nếu bạn chọn một bộ kết xuất trình duyệt từ xa trong khi engine in-process vốn đã có thể kết xuất tài liệu đúng cách, bạn sẽ thêm một chặng mạng và một phụ thuộc về độ sẵn sàng vào mỗi tệp PDF. Nếu bạn chọn engine in-process cho một tài liệu thực sự cần engine bố cục trình duyệt đầy đủ, bạn sẽ nhận được một tệp sai nhưng khó phát hiện. Gói bạn chọn sẽ định hình độ trễ, các chế độ lỗi và bề mặt vận hành, nên quyết định này cần được làm rõ.

Tóm tắt nhanh

Hãy bắt đầu với engine lõi. Mọi thứ khác chỉ là phần bổ sung. Nếu engine in-process kết xuất tài liệu của bạn đúng cách, bạn hoàn toàn không cần gói kết xuất nào.
Cầu nối framework đi theo framework của bạn, không phải theo tài liệu của bạn. Các bản tích hợp Laravel, Symfony và CodeIgniter tồn tại để cung cấp một facade hoặc factory, một phản hồi PDF, khả năng tạo qua hàng đợi và tự động khám phá — chúng không thay đổi những gì engine có thể kết xuất.
Chỉ dùng một bộ kết xuất khi độ trung thực CSS đòi hỏi một trình duyệt. Artisan (Chrome cục bộ) và Cloudflare (trình duyệt edge) tồn tại chính vì lý do đó; Gotenberg tồn tại để đưa các tài liệu Office vào.
Dùng Connect khi thành phần gọi là một dịch vụ hoặc một AI agent, chứ không phải một lệnh gọi PHP. Nó phơi bày engine qua MCP, REST và gRPC kèm một cổng xác nhận của con người cho các thao tác nguy hiểm.

Cách NextPDF tiếp cận vấn đề này

Hệ sinh thái được phân lớp có chủ đích để mỗi gói chỉ đảm nhận một nhiệm vụ. Engine lõi kết xuất PDF in-process. Một cầu nối framework điều chỉnh engine đó cho phù hợp với lối viết quen thuộc của một framework. Một gói kết xuất ủy thác bố cục HTML hoặc Office cho một engine bên ngoài khi engine in-process không phải là công cụ phù hợp. Connect biến engine thành một dịch vụ mạng. Không gói nào trong số này chồng lấn trách nhiệm của gói khác, và đó chính là điều làm cho quyết định trở nên dễ xử lý. Bạn không chọn giữa các công cụ cạnh tranh nhau. Bạn đang kết hợp những công cụ bổ trợ cho nhau.

Hãy đưa ra quyết định dựa trên trường hợp sử dụng. Bảng dưới đây ánh xạ mỗi tình huống tới gói phù hợp và nêu rõ sự đánh đổi mà bạn chấp nhận.

Trường hợp sử dụng	Gói phù hợp	Những gì nó thực sự cung cấp	Sự đánh đổi bạn chấp nhận
PDF trong một ứng dụng Laravel	`nextpdf/laravel`	Service provider được tự động khám phá, facade `Pdf`, `PdfResponse` (nội tuyến/tải xuống/truyền luồng, các header OWASP), một `GeneratePdfJob` chạy qua hàng đợi với tries/timeout/backoff, các registry được khóa an toàn cho Octane	Một phụ thuộc Laravel 12; các khả năng của engine không thay đổi
PDF trong một ứng dụng Symfony	`nextpdf/symfony`	Bundle được tự động đăng ký, `PdfFactory` có thể inject, `PdfResponse`, một handler Messenger tùy chọn để tạo bất đồng bộ	Một phụ thuộc bundle Symfony 7.2; các khả năng không thay đổi
PDF trong một ứng dụng CodeIgniter 4	`nextpdf/codeigniter`	`service('pdf')` / `pdf()` helper, một thư viện `Pdf` bao bọc một `Document` dùng một lần, một `PdfResponse`, một job chạy qua hàng đợi tùy chọn	Một phụ thuộc CodeIgniter 4.6; các khả năng không thay đổi
Tài liệu cần CSS trình duyệt đầy đủ (flex/grid/web fonts) nằm sát quy trình in-process	`nextpdf/artisan`	Chrome headless qua CDP, được kết xuất rồi nhập lại dưới dạng Form XObject để văn bản vẫn có thể chọn được; một browser pool	Một runtime Chrome và chi phí memory/process của nó trên máy chủ của bạn
Chuyển tài liệu Office (`.docx`, `.xlsx`) sang PDF	`nextpdf/gotenberg`	Một cầu nối PSR-18 tới một microservice Gotenberg với lớp truyền tải được tăng cường chống SSRF, ghim theo IP	Một dịch vụ Gotenberg bên ngoài và một phụ thuộc mạng
HTML→PDF ở edge / không có Chrome cục bộ	`nextpdf/cloudflare`	Cloudflare Browser Rendering qua lớp truyền tải đã ghim, kèm tùy chọn dự phòng bằng Chrome cục bộ	Một tài khoản Cloudflare và một phụ thuộc mạng; phương án dự phòng cần Artisan
Engine được sử dụng bởi một dịch vụ hoặc AI agent	`nextpdf/server` (Connect)	Một engine duy nhất qua MCP (stdio), REST (OpenAPI 3.1) và gRPC; khám phá công cụ theo mô hình phụ thuộc mềm; một cổng xác nhận của con người cho các công cụ rủi ro cao	Vận hành một bề mặt dịch vụ; kỷ luật thực thi mang tính tất định

Đây là hai quyết định độc lập, nhưng nhiều người thường gộp chúng làm một. Cầu nối framework được chọn theo framework mà bạn đang dùng — nó không mở rộng hay hạn chế những gì engine kết xuất. Bộ kết xuất được chọn theo tài liệu. Câu hỏi quyết định là liệu engine CSS in-process có đủ hay không, hay tài liệu có thực sự cần một engine bố cục trình duyệt. Bạn có thể cần một cầu nối framework mà không cần bộ kết xuất, một bộ kết xuất mà không cần cầu nối, cả hai, hoặc không cần gì cả. Xem chúng như một câu hỏi duy nhất là sai lầm tích hợp phổ biến nhất, và đó là lý do trang này tách riêng chúng.

Bằng chứng cho thấy điều gì

Trang này mang tính biên tập — một quyết định định tuyến — nhưng việc định tuyến dựa trên những gì manifest và các lớp chính của mỗi gói chứa.

Các cầu nối tồn tại thật và song song với nhau. Mỗi cầu nối khai báo phụ thuộc framework và tự động đăng ký trong composer.json của nó (extra.laravel.providers, extra.symfony.bundles, Registrar của CodeIgniter). Mỗi cầu nối cũng đi kèm một PdfResponse, một binding tài liệu dùng một lần và một job chạy qua hàng đợi tùy chọn. Không cầu nối nào thêm một khả năng kết xuất — chúng chỉ điều chỉnh cùng một engine. Các bộ kết xuất cũng tồn tại thật và khác biệt với nhau. Artisan phụ thuộc vào chrome-php/chrome và nhập tệp PDF từ Chrome trở lại dưới dạng Form XObject để giữ cho văn bản vẫn có thể chọn được. Gotenberg và Cloudflare là các cầu nối HTTP PSR-18 với lớp truyền tải được tăng cường chống SSRF một cách rõ ràng và ghim theo IP. Cloudflare có thể dự phòng bằng Artisan khi không thể kết nối tới Worker. composer.json của Connect khai báo ba lớp truyền tải và một mô hình phụ thuộc mềm, trong đó các công cụ xuất hiện khi các gói của chúng được cài đặt, được quản lý bởi một mô hình rủi ro bốn cấp với một cổng xác nhận của con người.

Cách trang này định tuyến lựa chọn cho bạn được các chuẩn hỗ trợ về mặt hình thức: Spec: ISO 24495-1:2023, §5 nói rằng người đọc nên có thể nhanh chóng xác định liệu nội dung có phục vụ mục đích của họ hay không, và Spec: ISO/IEC/IEEE 26514:2022, §3.x222 yêu cầu các liên kết và các tham chiếu phải nêu rõ đích đến của chúng — đó là lý do bảng gọi tên gói cụ thể và sự đánh đổi thay vì nói mơ hồ về “một bản tích hợp”.

Ví dụ thực tế

Quyết định là một chuỗi câu hỏi trung thực, không phải một bảng so sánh tính năng. Luồng dưới đây xử lý các trường hợp thường gặp.

1. Does the in-process engine render the document correctly?
   YES → you need NO renderer package. Stop here for rendering.
   NO  → continue.

2. Is the source an Office file (.docx/.xlsx)?
   YES → nextpdf/gotenberg (external Gotenberg service).
   NO  → continue (it is HTML/CSS fidelity you need).

3. Can you run a local Chrome on the host?
   YES → nextpdf/artisan (local CDP renderer).
   NO  → nextpdf/cloudflare (edge; optional Artisan fallback).

Independently of 1–3, choose how the engine is CALLED:
   In a PHP web app?        → the matching framework bridge.
   By a service / AI agent? → nextpdf/server (Connect).
   Neither?                 → use the core engine directly.

Cấu trúc chính là bài học: kết xuất và cách gọi là hai trục riêng biệt. Trả lời gộp hai câu hỏi này là cách các nhóm rốt cuộc dùng một bộ kết xuất từ xa mà họ không cần, hoặc dùng một cầu nối không giải quyết được vấn đề về độ trung thực của họ.

Hiểu lầm phổ biến

Hiểu lầm phổ biến nhất là “Tôi cần một gói kết xuất để tạo PDF.” Bạn không cần. Engine lõi tạo PDF in-process. Các gói kết xuất chỉ tồn tại cho những trường hợp cụ thể cần một engine bố cục cấp trình duyệt hoặc khi nguồn là một tài liệu Office. Khi engine in-process đã tạo ra tệp đúng, việc dùng một bộ kết xuất theo phản xạ chỉ thêm một phụ thuộc runtime và một chế độ lỗi mà không mang lại lợi ích gì.

Hiểu lầm ngược lại là “cầu nối framework mở khóa các khả năng.” Không phải vậy. Một cầu nối thay đổi cách bạn gọi engine — facade, factory, phản hồi, job chạy qua hàng đợi — chứ không phải những gì nó có thể tạo ra. Ký số, PDF/A và hóa đơn có cấu trúc là những vấn đề thuộc về cấp dịch vụ và engine, giống nhau dù bạn gọi qua một cầu nối hay gọi trực tiếp.

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

Trang này định tuyến; nó không benchmark hay xếp hạng. Nó nêu rõ những gì mỗi gói cung cấp và sự đánh đổi. Lựa chọn trong số đó là quyết định của bạn dựa trên các ràng buộc của chính bạn.
Các khả năng của gói được đọc từ manifest và các lớp chính của chúng tại một thời điểm. Hãy coi tài liệu riêng của mỗi gói là nguồn chính thức cho API hiện tại của nó. Hướng dẫn này là bản đồ, không phải bản đặc tả.
Không đưa ra hay ngụ ý bất kỳ so sánh nào với đối thủ cạnh tranh. Đối tượng duy nhất là hệ sinh thái NextPDF và cách các thành phần của nó khớp với nhau.
Cầu nối framework và bộ kết xuất là hai lựa chọn độc lập. Một cầu nối không mở rộng khả năng của engine; một bộ kết xuất không phụ thuộc vào một framework.
Các bộ kết xuất bên ngoài thêm một phụ thuộc về độ sẵn sàng. Gotenberg và Cloudflare thêm một lệnh gọi mạng và một dịch vụ cần vận hành; đó là sự đánh đổi được chấp nhận, không phải một chi phí ẩn.
Các khả năng bị giới hạn theo cấp dịch vụ là độc lập với cách tích hợp. Các tính năng thương mại được mở khóa bởi cấp dịch vụ, không phải bởi bất kỳ cầu nối hay bộ kết xuất nào; xem ranh giới bên dưới.

Ecosystem packages and tiering — edition availability
Edition	Availability
Core	Mọi gói tích hợp (các cầu nối, Artisan, Gotenberg, Cloudflare, Connect) đều hoạt động với Core và theo giấy phép Apache-2.0. Chúng điều chỉnh hoặc phơi bày engine; chúng không giới hạn các tính năng.
Pro	Các khả năng thương mại (ký số baseline PAdES, PDF/A, mã vạch nâng cao) được mở khóa bởi cấp dịch vụ, rồi có sẵn thông qua bất kỳ cách tích hợp nào, chứ không phải bằng cách đổi sang cách tích hợp khác.
Enterprise	Hóa đơn có cấu trúc, các chính sách xác thực và cổng xác nhận của con người trong Connect cho các công cụ rủi ro cao là các khả năng theo cấp dịch vụ, cũng độc lập với cách tích hợp.

Tài liệu liên quan

Quy trình HTML — những gì engine CSS in-process xử lý, để bạn biết khi nào thực sự cần một bộ kết xuất trình duyệt.
Khi nào không nên dùng NextPDF — ranh giới trung thực về các bài toán tài liệu mà engine không phải là công cụ phù hợp.
Nền tảng PHP 8.4 — mức runtime tối thiểu mà mọi gói chia sẻ và những gì lộ trình backport bảo toàn.

Thuật ngữ

Engine lõi — nextpdf/core, engine PDF 2.0 in-process mà mọi gói khác xây dựng dựa trên.
Cầu nối framework — một gói tích hợp (Laravel/Symfony/CodeIgniter) điều chỉnh engine cho phù hợp với lối viết quen thuộc của một framework mà không thay đổi các khả năng của nó.
Gói kết xuất — một gói ủy thác bố cục HTML hoặc Office cho một engine bên ngoài (Artisan/Cloudflare/Gotenberg) khi engine in-process không phải là công cụ phù hợp.
Form XObject — một đoạn nội dung PDF có thể tái sử dụng; Artisan nhập một trang được trình duyệt kết xuất thành một đoạn như vậy để văn bản của nó vẫn có thể chọn được.
NextPDF Connect — nextpdf/server, gói phơi bày engine qua MCP, REST và gRPC với một bề mặt thực thi mang tính tất định.
Phụ thuộc mềm — mô hình của Connect, trong đó các công cụ xuất hiện tự động khi các gói NextPDF tùy chọn được cài đặt, mà không cần thay đổi mã.