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 recipe quickstart của từng tích hợp.

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 đó, và bộ tổng hợp xuất bản chúng lên trang này. Để 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
Symfony	nextpdf/symfony	Framework	^3.0 || ^5.2	Symfony quickstart
CodeIgniter 4	nextpdf/codeigniter	Framework	^3.0 || ^5.2	CodeIgniter quickstart
Artisan (Chrome)	nextpdf/artisan	Cầu nối renderer	^3.0 || ^5.2	Artisan quickstart
Gotenberg	nextpdf/gotenberg	Cầu nối renderer	^3.0	Gotenberg quickstart
Cloudflare	nextpdf/cloudflare	Cầu nối renderer	^3.0	Cloudflare quickstart
Compat (legacy)	nextpdf/compat-legacy	Lớp tương thích (shim)	^3.0	TCPDF-compat quickstart
Backport builder	nextpdf/backport-builder	Công cụ build	không áp dụng	Backport quickstart
Connect (server)	nextpdf/server	Dịch vụ mạng	^3.0	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 cấp cao nhất. 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 tcpdf-compat, được đặt tên theo bề mặt mà nó mô phỏng.

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: 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: 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: 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: 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: 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: 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: TCPDF-compat 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: 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: Connect quickstart.

Cách tổ chức các slug recipe

Các recipe nằm dưới /integrations/<integration>/<recipe>/, trong đó <integration> là tên ngắn từ bảng tham chiếu ở trên (thay vào đó, các recipe của Connect nằm dưới slug connect cấp cao nhất). 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 một gố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 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.