Cài đặt NextPDF

Tổng quan nhanh

Cài đặt bất kỳ bản phân phối NextPDF nào bằng một lệnh của trình quản lý gói. Các bản phân phối PHP dùng Composer; Python software development kit (SDK) dùng pip. Chọn tab phù hợp với thứ bạn đang xây dựng. Chạy lệnh, rồi kiểm tra kết quả ở cuối trang này.

Một engine, nhiều cửa vào

Engine lõi là nextpdf/core. Các bản tích hợp framework, bộ kết xuất Hypertext Markup Language (HTML), máy chủ và client Python đều thêm một gói ở lớp trên. Chúng không thay thế engine lõi; chúng cài đặt engine lõi cho bạn.

Yêu cầu

NextPDF hướng tới một runtime hiện đại duy nhất. Các ràng buộc này được lấy trực tiếp từ chính các tệp composer.json của các gói.

Yêu cầu	Ràng buộc	Ghi chú
PHP	>=8.4 <9.0	Composer từ chối cài đặt trên PHP 8.3 trở xuống hoặc trên PHP 9.
Composer	2.7 trở lên	Bắt buộc để phân giải dependency và tạo autoloader.
ext-mbstring	Bắt buộc	Xử lý chuỗi multi-byte cho bố cục văn bản.
ext-zlib	Bắt buộc	Nén luồng cho các đối tượng Portable Document Format (PDF).
Chrome hoặc Chromium	Tùy chọn	Chỉ dành cho bộ kết xuất Artisan (writeHtmlChrome()).
Dịch vụ Gotenberg	Tùy chọn	Chỉ dành cho chuyển đổi tài liệu văn phòng và HTML qua Gotenberg.
Python	3.10 trở lên	Chỉ dành cho Python SDK.

ext-mbstring và ext-zlib được bật sẵn trong mọi bản build PHP được hỗ trợ. Các bản tích hợp kiểm tra chúng khi khởi động và dừng với thông báo rõ ràng nếu thiếu một trong hai.

Cài đặt engine lõi

Để tạo và kiểm tra tệp PDF từ PHP, bạn chỉ cần engine lõi.

composer require nextpdf/core

Hãy commit composer.lock để mọi worker đã triển khai đều phân giải cùng một phiên bản engine. Sau khi cài đặt, hãy chuyển sang PDF đầu tiên của bạn.

Cài đặt bản tích hợp framework

Cài đặt adapter framework để có container binding, response helper và queue job. Mỗi adapter đều khai báo nextpdf/core và phân giải nó cho bạn.

Laravel

composer require nextpdf/laravel

Auto-discovery đăng ký service provider và facade Pdf. Sau đó, publish tệp cấu hình:

php artisan vendor:publish --tag=nextpdf-config

Xem hướng dẫn cài đặt Laravel và hướng dẫn bắt đầu nhanh Laravel.

Symfony

composer require nextpdf/symfony

Trong ứng dụng Symfony Flex, bundle này tự đăng ký. Với ứng dụng không dùng Flex, bạn tự thêm NextPDF\Symfony\NextPdfBundle vào config/bundles.php. Xem hướng dẫn cài đặt Symfony.

CodeIgniter

composer require nextpdf/codeigniter

CodeIgniter 4 tự phát hiện lớp Services và helper pdf(), nên bạn không cần đăng ký thủ công. Xem hướng dẫn cài đặt CodeIgniter.

Cài đặt bộ kết xuất hoặc dịch vụ

NextPDF kết xuất HTML thành PDF theo ba cách. Hãy cài đặt tùy chọn tương ứng với nơi bạn muốn quá trình kết xuất diễn ra. Không tùy chọn nào trong số này thay thế writeHtml(), pipeline HTML thuần PHP tích hợp sẵn trong engine lõi.

Artisan (Chrome)

composer require nextpdf/artisan

Gói này bổ sung khả năng kết xuất bằng headless-Chrome thông qua Chrome DevTools Protocol (CDP). Bạn cũng cần một binary Chrome hoặc Chromium mà host có thể truy cập. Sau khi cài đặt, hãy gọi writeHtmlChrome() trên một tài liệu. Xem hướng dẫn bắt đầu nhanh Artisan.

Cloudflare

composer require nextpdf/cloudflare guzzlehttp/guzzle

Quá trình kết xuất chạy qua Cloudflare Browser Rendering tại edge. Cầu nối này chỉ phụ thuộc vào các contract PHP Standards Recommendation (PSR) là PSR-18 và PSR-17, nên bạn tự cung cấp client Hypertext Transfer Protocol (HTTP) của riêng mình (ở đây là Guzzle). Xem hướng dẫn cài đặt Cloudflare.

Gotenberg

composer require nextpdf/gotenberg guzzlehttp/guzzle

Gói này chuyển đổi tài liệu văn phòng và HTML thông qua dịch vụ Gotenberg. Bạn cung cấp client PSR-18 và một instance Gotenberg có thể truy cập được. Xem hướng dẫn cài đặt Gotenberg.

Các bộ kết xuất vươn ra ngoài PHP

Artisan khởi chạy một tiến trình trình duyệt, còn Cloudflare và Gotenberg gọi một dịch vụ mạng. Hãy coi HTML là không đáng tin cậy. Hãy đọc trang bảo mật và vận hành của từng gói trước khi kết xuất đầu vào chịu ảnh hưởng từ người dùng.

Cài đặt máy chủ

NextPDF Server (còn gọi là Connect) là dịch vụ độc lập. Nó cung cấp engine qua Model Context Protocol (MCP), Representational State Transfer (REST) và gRPC.

composer require nextpdf/server

Gói này thêm các entry point console vào vendor/bin/, bao gồm vendor/bin/nextpdf-mcp (máy chủ stdio MCP) và vendor/bin/nextpdf-server (máy chủ REST). Các transport REST và gRPC cũng cần binary RoadRunner:

./vendor/bin/rr get-binary

Xem hướng dẫn cài đặt Connect và hướng dẫn bắt đầu nhanh Connect.

Cài đặt Python SDK

Python SDK là client có kiểu dữ liệu dành cho NextPDF Server đang chạy. Hãy cài đặt nó từ Python Package Index (PyPI):

pip install nextpdf

SDK cần Python 3.10 trở lên và endpoint NextPDF Server có thể truy cập được. Xem hướng dẫn bắt đầu nhanh Python SDK.

Kiểm tra bản cài đặt

Hãy xác nhận từng bản phân phối đã được cài đặt đúng trước khi bắt đầu viết code.

Core / PHP

composer show nextpdf/core

Một dòng phiên bản xác nhận engine đã được cài đặt và sẵn sàng cho autoloader.

Laravel

php artisan package:discover --ansi

Kết quả liệt kê nextpdf/laravel trong danh sách các gói được phát hiện.

Symfony

php bin/console debug:container nextpdf

Container báo cáo alias nextpdf.document và service PdfFactory.

Server

./vendor/bin/generate-skills --dry-run --list-tools

Lệnh này khởi động registry và in ra các công cụ mà bản cài đặt này cung cấp, nhưng không khởi động máy chủ.

Python

nextpdf version

Một chuỗi phiên bản xác nhận SDK được import thành công.

Xem thêm

PDF đầu tiên của bạn Tạo một PDF từ PHP và kết xuất HTML thành PDF.

Chọn hướng đi của bạn Quyết định bản phân phối và bộ kết xuất HTML nào phù hợp với ứng dụng của bạn.

Các bản tích hợp Bản đồ phần mở rộng đầy đủ và hướng dẫn lựa chọn.

Connect (máy chủ) Chạy engine như một dịch vụ mạng qua MCP, REST và gRPC.