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.

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 môi trường chạy của NextPDF, được đọc từ chính các tệp composer.json của các gói
Yêu cầu	Ràng buộc	Trạng thái	Ghi chú
PHP	`>=8.4 <9.0`	Bắt buộc	Composer từ chối cài đặt trên PHP 8.3 trở xuống, hoặc trên PHP 9.
Composer	`2.x`	Bắt buộc	Cần thiết để phân giải phụ thuộc và tạo bộ nạp tự động.
`ext-mbstring`	—	Bắt buộc	Xử lý chuỗi đa 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).
`ext-intl`	—	Bắt buộc	Các dịch vụ International Components for Unicode (ICU): văn bản hai chiều, ngắt dòng, và định dạng theo bản địa.
`ext-gd`	—	Bắt buộc	Giải mã và xử lý ảnh raster cho các ảnh nhúng.
`ext-curl`	—	Bắt buộc	Các lượt trao đổi qua mạng: đóng dấu thời gian RFC 3161 và tải tài nguyên từ xa. Việc tạo ngoại tuyến không dùng đến nó, nhưng Composer vẫn yêu cầu nó.
`ext-openssl`	—	Bắt buộc	Mật mã cho chữ ký số, cấu trúc CMS, và mã hóa.
Chrome or Chromium	—	Tùy chọn	Chỉ dành cho bộ kết xuất Artisan (writeHtmlChrome()).
Gotenberg service	—	Tùy chọn	Chỉ dành cho việc chuyển đổi tài liệu văn phòng và HTML thông qua Gotenberg.
Python	`3.10+`	Tùy chọn	Chỉ dành cho software development kit (SDK) của Python.

ext-mbstring và ext-zlib được bật sẵn trong hầu hết các bản build PHP; còn ext-intl, ext-gd, ext-curl và ext-openssl thì khác nhau tùy theo bản phân phối, vì vậy hãy kiểm tra cả sáu bằng php -m trước khi cài đặt. Khi khởi động, các bản tích hợp sẽ kiểm tra những phần mở rộng mà chúng cần và dừng lại kèm theo thông báo rõ ràng nếu thiếu bất kỳ phần nào.

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.

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.

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.

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.

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.

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.

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à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.

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.

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.

php bin/console debug:container nextpdf

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

./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ủ.

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ạnTạo một PDF từ PHP và kết xuất HTML thành PDF.

Chọn hướng đi của bạnQuyế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.

Mua và cấp phépMua giấy phép Pro hoặc Enterprise thông qua Merchant of Record của chúng tôi, rồi cài đặt và kích hoạt.

Các bản tích hợpBả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.