Sổ tay tích hợp

NextPDF core kết xuất Portable Document Format (PDF) 2.0 từ PHP. Chín gói tích hợp kết nối engine này với một framework, backend kết xuất, codebase cũ, pipeline build hoặc dịch vụ mạng. Trang này giải thích mục đích của từng tích hợp, liệt kê tên gói và ràng buộc phiên bản core của gói đó (đọc trực tiếp từ composer.json của gói), đồng thời liên kết đến các recipe của từng tích hợp khi các repository nguồn phát hành cây docs/public/ của mình.

Trang này là một mục lục, nên không đưa ra tuyên bố nào về hành vi của bất kỳ tích hợp nào. Repository của từng tích hợp sở hữu các recipe riêng của tích hợp đó. Bộ tổng hợp kéo các recipe đó vào trang này. Cho đến khi một recipe được đưa vào, liên kết của recipe đó sẽ trỏ tới một placeholder. Để có gợi ý theo trường hợp sử dụng, hãy đọc Chọn một tích hợp. Để biết hợp đồng mà mọi recipe chạy được đều tuân theo, hãy đọc Quy ước recipe.

Năm dạng tích hợp

Chín gói được chia thành năm dạng. Mỗi dạng cho biết tích hợp đó giải quyết loại vấn đề nào.

Tích hợp framework kết nối NextPDF vào service container và vòng đời request của một framework ứng dụng: nextpdf/laravel, nextpdf/symfony, nextpdf/codeigniter. Bạn cài đặt một gói, resolve một service và trả về một response PDF.
Cầu nối renderer gửi bước chuyển HTML sang PDF hoặc Office sang PDF tới một backend kết xuất bên ngoài, thay vì dùng pipeline trong tiến trình: nextpdf/artisan (Chrome headless qua Chrome DevTools Protocol), nextpdf/gotenberg (một microservice Gotenberg), nextpdf/cloudflare (Cloudflare Browser Rendering tại edge).
Một lớp tương thích (shim) cho phép một codebase viết cho thư viện PDF cũ gọi NextPDF trước khi bạn viết lại codebase đó: nextpdf/compat-legacy.
Một công cụ build tạo bản backport PHP 8.1 / 7.4 của NextPDF cho các runtime không thể chạy 8.4: nextpdf/backport-builder.
Một dịch vụ mạng cung cấp NextPDF qua Representational State Transfer (REST), gRPC và Model Context Protocol cho các hệ thống AI cũng như bên gọi từ xa: nextpdf/server (phân phối dưới tên NextPDF Connect).

Các cầu nối renderer giao tiếp bằng Hypertext Transfer Protocol (HTTP) (nextpdf/gotenberg, nextpdf/cloudflare, và đường HTTP-client trong nextpdf/laravel) phụ thuộc vào một HTTP client PHP Standard Recommendation 18 (PSR-18) do ứng dụng host cung cấp. Theo PSR-18 §4, client chỉ ném một client exception có kiểu khi hoàn toàn không thể gửi request. Một response HTTP 4xx hoặc 5xx là giá trị trả về bình thường, không phải exception, theo cùng điều khoản PSR-18 §4. Các recipe gọi renderer từ xa xử lý lỗi truyền tải và các trạng thái không thành công như những trường hợp riêng biệt.

Tham chiếu gói và ràng buộc core

Mọi giá trị bên dưới đều được lấy từ composer.json của gói được nêu tên (nguồn có thẩm quyền). Ràng buộc core là yêu cầu nextpdf/core mà gói khai báo. nextpdf/backport-builder không khai báo yêu cầu nextpdf/core nào vì nó biến đổi mã nguồn của engine thay vì phụ thuộc vào engine tại runtime.

Tích hợp	Gói	Dạng	Ràng buộc core	Recipe
Laravel	`nextpdf/laravel`	Framework	`^3.0 \|\| ^5.2`	Laravel quickstart [[/integrations/laravel/quickstart/]]
Symfony	`nextpdf/symfony`	Framework	`^3.0 \|\| ^5.2`	Symfony quickstart [[/integrations/symfony/quickstart/]]
CodeIgniter 4	`nextpdf/codeigniter`	Framework	`^3.0 \|\| ^5.2`	CodeIgniter quickstart [[/integrations/codeigniter/quickstart/]]
Artisan (Chrome)	`nextpdf/artisan`	Cầu nối renderer	`^3.0 \|\| ^5.2`	Artisan quickstart [[/integrations/artisan/quickstart/]]
Gotenberg	`nextpdf/gotenberg`	Cầu nối renderer	`^3.0`	Gotenberg quickstart [[/integrations/gotenberg/quickstart/]]
Cloudflare	`nextpdf/cloudflare`	Cầu nối renderer	`^3.0`	Cloudflare quickstart [[/integrations/cloudflare/quickstart/]]
Compat (legacy)	`nextpdf/compat-legacy`	Lớp tương thích (shim)	`^3.0`	Compat-legacy quickstart [[/integrations/compat-legacy/quickstart/]]
Backport builder	`nextpdf/backport-builder`	Công cụ build	không áp dụng	Backport quickstart [[/integrations/backport/quickstart/]]
Connect (server)	`nextpdf/server`	Dịch vụ mạng	`^3.0`	Connect quickstart [[/integrations/connect/quickstart/]]

NextPDF phân phối nextpdf/server dưới tên sản phẩm NextPDF Connect; các recipe của gói này nằm dưới slug connect. nextpdf/compat-legacy được phát hành từ họ compat; các recipe của gói này nằm dưới slug compat-legacy.

Mọi gói đều yêu cầu PHP >=8.4 <9.0 tại runtime của chính gói đó. nextpdf/backport-builder tồn tại để tạo ra các artifact chạy trên PHP 8.1 (và mục tiêu 7.4). Chính engine đã được backport, chứ không phải builder, mới chạy trên runtime cũ hơn.

Mục đích của từng tích hợp

Tích hợp framework

nextpdf/laravel — một service provider Laravel 12, facade và các helper response PDF. Dùng nó khi ứng dụng của bạn là ứng dụng Laravel và bạn muốn NextPDF được resolve từ container, rồi trả về dưới dạng một response HTTP mà không cần đấu nối thủ công. Recipe: [[/integrations/laravel/quickstart/]].
nextpdf/symfony — một bundle Symfony 7 với các service dependency injection và các helper response PDF. Dùng nó khi ứng dụng của bạn là ứng dụng Symfony. Bundle này đăng ký engine như một service và tích hợp với các response symfony/http-foundation. Recipe: [[/integrations/symfony/quickstart/]].
nextpdf/codeigniter — một service CodeIgniter 4, library wrapper và các helper response PDF. Dùng nó khi ứng dụng của bạn là ứng dụng CodeIgniter 4 và bạn muốn NextPDF có sẵn thông qua service locator của framework. Recipe: [[/integrations/codeigniter/quickstart/]].

Cầu nối renderer

nextpdf/artisan — một renderer Chrome headless qua Chrome DevTools Protocol. Dùng nó khi tài liệu cần engine Cascading Style Sheets (CSS) của trình duyệt để đạt độ trung thực bố cục mà pipeline HTML trong tiến trình không nhắm tới, và bạn có thể chạy một tiến trình Chrome gần ứng dụng. Recipe: [[/integrations/artisan/quickstart/]].
nextpdf/gotenberg — chuyển đổi Office sang PDF và HTML sang PDF thông qua một microservice Gotenberg. Dùng nó khi đầu vào là tài liệu Office, hoặc khi việc kết xuất phải chạy ngoài tiến trình trong một dịch vụ riêng. Nó giao tiếp HTTP qua một PSR-18 client do host cung cấp. Recipe: [[/integrations/gotenberg/quickstart/]].
nextpdf/cloudflare — kết xuất serverless qua Cloudflare Browser Rendering API. Dùng nó khi việc kết xuất nên chạy tại edge mà không cần vận hành một tiến trình trình duyệt chạy lâu dài. Nó giao tiếp HTTP qua một PSR-18 client do host cung cấp. Recipe: [[/integrations/cloudflare/quickstart/]].

Lớp tương thích (shim)

nextpdf/compat-legacy — một lớp tương thích cho các codebase được viết dựa trên một thư viện PDF cũ. Dùng nó để gọi NextPDF từ mã hiện có trước khi bạn viết lại các vị trí gọi. Đây là công cụ hỗ trợ di chuyển, không phải dependency lâu dài. Recipe: [[/integrations/compat-legacy/quickstart/]].

Công cụ build

nextpdf/backport-builder — một pipeline hạ cấp dựa trên Rector tạo ra bản build PHP 8.1 (và mục tiêu 7.4) của NextPDF. Dùng nó khi một runtime không thể chuyển sang PHP 8.4 nhưng bạn vẫn cần engine ở đó. Đây là hạ tầng build, không phải dependency runtime của ứng dụng. Recipe: [[/integrations/backport/quickstart/]].

Dịch vụ mạng

nextpdf/server (NextPDF Connect) — cung cấp NextPDF qua một REST API, một dịch vụ gRPC và Model Context Protocol. Dùng nó khi bên gọi ở xa, dùng một ngôn ngữ khác, hoặc là hệ thống AI cần một tool endpoint thay vì thư viện PHP. Recipe: [[/integrations/connect/quickstart/]].

Cách các liên kết recipe được phân giải

Mỗi placeholder [[…]] ở trên là một tham chiếu chuyển tiếp, trỏ đến một trang được biên soạn trong repository của tích hợp dưới docs/public/ và được bộ tổng hợp kéo vào trang này. Các slug đích tuân theo một quy ước:

/integrations/<integration>/<recipe>/

Token <integration> là tên ngắn lấy trực tiếp từ bảng tham chiếu gói và ràng buộc core ở trên. Mỗi hàng trong bảng đó cung cấp một tên ngắn. Recipe đầu tiên mà mỗi tích hợp phát hành được đặt tên là quickstart; các recipe về sau dùng thêm các phân đoạn <recipe> dưới cùng gốc <integration>. Cho đến khi một trang đích được tổng hợp, liên kết của trang đó là một placeholder và không phân giải được. Mục lục này không đưa ra tuyên bố nào về hành vi của bất kỳ trang đích nào. Nó chỉ ghi lại các dữ kiện về gói đã được xác minh từ composer.json và slug mà các recipe của từng repository sẽ chiếm.

Xem thêm

Chọn một tích hợp — một ma trận quyết định ánh xạ các trường hợp sử dụng đến các tích hợp.
Quy ước recipe — hợp đồng mà mọi recipe chạy được trong sổ tay này đều tuân theo.