Chọn bản tích hợp

Dùng trang này để đối chiếu trường hợp sử dụng của bạn với bản tích hợp phù hợp. Mỗi đề xuất đều dựa trên phần mô tả trong composer.json và mục đích đã nêu của gói; cả hai đều được đọc trực tiếp từ kho mã nguồn. Khi hai bản tích hợp chồng lấn nhau, trang này nêu rõ điểm khác biệt để bạn có thể chọn một cách tự tin.

Tìm dòng phù hợp với tình huống của bạn, rồi bắt đầu từ đó.

Bắt đầu từ đây: bạn đang có gì?

Bạn đang có …	Dùng	Lý do (mục đích đã xác minh)
Một ứng dụng Laravel 12	`nextpdf/laravel`	Bản tích hợp framework Laravel: service provider, facade và các helper tạo phản hồi Portable Document Format (PDF).
Một ứng dụng Symfony 7	`nextpdf/symfony`	Bundle Symfony: các service cho dependency injection (DI) và các helper tạo phản hồi PDF.
Một ứng dụng CodeIgniter 4	`nextpdf/codeigniter`	Các service CodeIgniter 4, lớp wrapper thư viện và các helper tạo phản hồi PDF.
Một ứng dụng PHP không dùng framework	`nextpdf/core` trực tiếp	Không cần bản tích hợp framework; engine là thư viện thuần.
HTML cần engine Cascading Style Sheets (CSS) của trình duyệt và bạn có thể chạy Chrome	`nextpdf/artisan`	Bộ kết xuất Chrome DevTools Protocol (CDP) cho HTML cần bố cục CSS đạt chuẩn trình duyệt.
Một tài liệu Office cần chuyển đổi, chẳng hạn DOCX, XLSX hoặc ODT	`nextpdf/gotenberg`	Chuyển đổi Office sang PDF thông qua một microservice Gotenberg.
Nhu cầu kết xuất mà không cần vận hành tiến trình trình duyệt nào	`nextpdf/cloudflare`	Kết xuất serverless thông qua Cloudflare Browser Rendering API tại edge.
Mã được viết dựa trên một thư viện PDF cũ	`nextpdf/compat-legacy`	Lớp tương thích cho thư viện PDF cũ; gọi NextPDF mà không cần viết lại các điểm gọi.
Một môi trường runtime bị kẹt ở PHP 8.1 / 7.4	`nextpdf/backport-builder`	Pipeline hạ cấp bằng Rector để dựng phiên bản đích 8.1 / 7.4 của engine.
Bên gọi từ xa, từ một ngôn ngữ khác, hoặc một hệ thống trí tuệ nhân tạo (AI)	`nextpdf/server`	NextPDF Connect: bề mặt Representational State Transfer (REST), gRPC và Model Context Protocol để thực thi từ xa.

Khi hai bản tích hợp đều có thể phù hợp

Kết xuất HTML sang PDF: Artisan vs Gotenberg vs Cloudflare vs core

Cả ba cầu nối kết xuất đều biến markup thành PDF. Chúng khác nhau về cách vận hành, không phải về chất lượng. Hãy dùng chính khác biệt vận hành đó làm yếu tố quyết định.

nextpdf/artisan điều khiển Chrome ở chế độ headless qua Chrome DevTools Protocol. Nó cần một tiến trình Chrome mà ứng dụng có thể truy cập được. Hãy chọn nó khi bạn có thể vận hành tiến trình đó và tài liệu cần engine CSS của trình duyệt.
nextpdf/gotenberg gọi một microservice Gotenberg chạy ngoài tiến trình qua HTTP. Hãy chọn nó khi việc kết xuất phải được tách riêng trong service của chính nó, hoặc khi đầu vào là một tài liệu Office. Trong ba bản tích hợp, Gotenberg là bản duy nhất có mục đích đã nêu bao gồm chuyển đổi Office sang PDF.
nextpdf/cloudflare gọi Cloudflare Browser Rendering API. Hãy chọn nó khi bạn muốn kết xuất edge/serverless mà không phải chạy hay vá lỗi tiến trình trình duyệt nào.
Pipeline HTML của NextPDF core chạy trong tiến trình không cần bất kỳ thứ nào nêu trên. Chỉ dùng cầu nối kết xuất khi pipeline chạy trong tiến trình không thể mang lại độ trung thực bố cục hoặc mức cô lập tiến trình mà tài liệu cần. Cầu nối có chủ đích chuyển giao bước đó; đây không phải là con đường mặc định.

Hai cầu nối HTTP (nextpdf/gotenberg, nextpdf/cloudflare) cần một HTTP client PSR-18 do host cung cấp. Các recipe của chúng coi lỗi truyền tải và trạng thái HTTP không thành công là hai kết quả riêng biệt.

Chuyển đổi một tài liệu Office

nextpdf/gotenberg là bản tích hợp mà phần mô tả đã xác minh trong composer.json nêu rõ việc chuyển đổi Office sang PDF. Các cầu nối kết xuất khác mô tả việc kết xuất HTML, chứ không phải đầu vào Office. Nếu nguồn là DOCX/XLSX/ODT, hãy dùng bản tích hợp này.

Di chuyển khỏi một thư viện PDF cũ

Theo mục đích đã nêu, nextpdf/compat-legacy là một lớp tương thích cho những codebase được viết dựa trên một thư viện PDF cũ. Nó cho phép các điểm gọi hiện có gọi NextPDF trước khi bạn viết lại chúng. Hãy xem nó là một công cụ hỗ trợ di chuyển sẽ được loại bỏ theo kế hoạch, không phải là một phụ thuộc runtime lâu dài. Mã mới nên gọi nextpdf/core (hoặc bản tích hợp framework tương ứng) trực tiếp.

Chạy trên PHP 8.1 hoặc 7.4

Mọi gói trong hệ sinh thái đều khai báo PHP >=8.4 <9.0. nextpdf/backport-builder tồn tại chính vì ràng buộc này: mục đích đã nêu của nó là một pipeline hạ cấp bằng Rector để dựng một artifact PHP 8.1+ (và một phiên bản đích 7.4). Nó là một công cụ build, không phải là một phụ thuộc runtime cho ứng dụng của bạn. Chạy builder để tạo engine đã được backport, rồi triển khai engine đó.

Một bên gọi không phải PHP hoặc một AI agent

nextpdf/server (NextPDF Connect) phơi bày engine qua một REST API, một service gRPC và Model Context Protocol. Hãy chọn nó khi bên gọi ở xa, được viết bằng một ngôn ngữ khác, hoặc là một hệ thống AI dùng một tool endpoint thay vì một thư viện PHP. Một ứng dụng PHP trong cùng tiến trình nên dùng nextpdf/core hoặc một bản tích hợp framework thay vì thêm một bước nhảy qua mạng.

Dùng nhiều hơn một bản tích hợp cùng lúc

Một bản tích hợp framework và một cầu nối kết xuất hoạt động ở các lớp khác nhau, nên bạn có thể cài cả hai. Bản tích hợp framework đảm nhiệm phần đấu nối container và phản hồi HTTP; cầu nối kết xuất đảm nhiệm backend kết xuất. Khi bạn giải một bộ phụ thuộc kết hợp, hãy kiểm tra xem mỗi gói chấp nhận những phiên bản nextpdf/core nào. Tài liệu tham chiếu về ràng buộc core trong chỉ mục cookbook tích hợp là nguồn chuẩn xác. Các recipe cho từng tổ hợp nằm trong những kho mã liên quan và được liên kết từ chỉ mục đó.

Xem thêm

Cookbook tích hợp — tài liệu tham chiếu về gói và ràng buộc core, cùng với chỉ mục liên kết recipe.
Quy ước recipe — quy ước mà mọi recipe chạy được đều tuân theo.