Cài đặt NextPDF Artisan

Tổng quan nhanh

Cài đặt nextpdf/artisan bằng Composer. Composer cũng cài đặt phần phụ thuộc khi chạy chrome-php/chrome. Sau đó, hãy cung cấp một tệp nhị phân Chrome hoặc Chromium cho tiến trình PHP.

Cài đặt

composer require nextpdf/artisan

Gói này khai báo các ràng buộc sau trong composer.json:

Yêu cầu	Ràng buộc	Ghi chú
php	>=8.4 <9.0	Chỉ PHP 8.4
nextpdf/core	^3.0 || ^5.2	Công cụ NextPDF mã nguồn mở
chrome-php/chrome	^1.15	Thư viện client cho Chrome DevTools Protocol (CDP); được kéo vào qua cầu nối
psr/log	^3.0	Điểm chèn logger tùy chọn

Composer tự động phân giải chrome-php/chrome. Composer không bao giờ cài đặt tệp nhị phân Chrome; tệp nhị phân đó là phần phụ thuộc cấp hệ thống.

Chuẩn bị tệp nhị phân Chrome

Cầu nối cần một tệp nhị phân Chrome hoặc Chromium có thể thực thi. Theo mặc định, chrome-php/chrome tìm tệp nhị phân trong các đường dẫn thông dụng. Để cố định một đường dẫn rõ ràng, hãy truyền đường dẫn đó qua cấu hình. Xem /integrations/artisan/configuration/ và trang chuyên biệt /integrations/artisan/chrome-renderer-setup/.

# Debian / Ubuntu
apt-get install -y chromium

# RHEL / Fedora
dnf install -y chromium

# macOS (Homebrew)
brew install --cask chromium

Trước khi kết nối tệp nhị phân với ứng dụng, hãy xác minh rằng tệp đó chạy ở chế độ headless:

chromium --headless --dump-dom about:blank

Một lần chạy thành công sẽ in ra tài liệu Document Object Model (DOM) rỗng và thoát với mã 0. Mã thoát khác 0 nghĩa là tệp nhị phân hoặc các thư viện dùng chung của nó bị thiếu. Hãy khắc phục vấn đề đó trước khi tiếp tục, vì cầu nối sẽ bộc lộ cùng lỗi này dưới dạng ChromeRenderException tại thời điểm kết xuất.

Xác minh gói đã được kết nối

<?php

declare(strict_types=1);

use NextPDF\Artisan\ChromeRendererConfig;
use NextPDF\Artisan\ChromeHtmlRenderer;

require __DIR__ . '/vendor/autoload.php';

$renderer = new ChromeHtmlRenderer(new ChromeRendererConfig());

echo $renderer->getHtmlSecurityPolicy()->getName(), PHP_EOL;
// Prints: default

Đoạn mã này tạo bộ kết xuất và đọc chính sách bảo mật Hypertext Markup Language (HTML) mặc định mà không cần khởi chạy Chrome. Nó xác nhận rằng cơ chế tự động nạp và các ràng buộc contract của nextpdf/core đã được phân giải. (Hành vi này được khẳng định bởi tests/Unit/Artisan/ChromeHtmlRendererTest.php::usesDefaultHtmlSecurityPolicyWhenNoneInjected.)

Cài đặt trong container

Trong Docker, sandbox của Chrome thường không thể khởi động dưới process ID (PID) 1 / root nếu không có thêm quyền kernel. Gói này cung cấp công tắc noSandbox cho trường hợp đó. Tắt sandbox của Chrome có chi phí bảo mật thực sự. Trang /integrations/artisan/security-and-operations/ và /integrations/artisan/chrome-renderer-setup/ ghi lại chi phí đó và nêu rõ các giới hạn của nó. Đừng bật công tắc này nếu chưa đọc phần đó.

Trường hợp đặc biệt & điểm cần lưu ý

• Có chrome-php/chrome nhưng không có tệp nhị phân. Composer hoàn tất thành công; lần kết xuất đầu tiên ném ra ChromeRenderException và bao bọc lỗi khởi chạy. Việc kiểm tra thư viện tách biệt với việc kiểm tra tệp nhị phân.
• Thiếu chrome-php/chrome. Nếu thư viện bị loại khỏi autoloader, BrowserPool::getBrowser() sẽ ném ra ChromeNotAvailableException kèm lệnh khắc phục chính xác. (Được khẳng định bởi tests/Unit/Artisan/BrowserPoolTest.php::getBrowserThrowsWhenChromePhpPackageIsUnavailable.)
• Ràng buộc phiên bản. nextpdf/core: ^3.0 || ^5.2 — Artisan hỗ trợ cả hai dòng phiên bản chính của core. Hãy cố định phiên bản core mà ứng dụng của bạn nhắm đến.

Ghi chú bảo mật

Việc cài đặt cầu nối đưa một tiến trình bên ngoài (Chrome) vào ranh giới tin cậy. Hãy xem lại /integrations/artisan/security-and-operations/ trước khi để bất kỳ đường kết xuất nào tiếp xúc với HTML do người dùng cung cấp.

Xem thêm

• /integrations/artisan/overview/
• /integrations/artisan/configuration/
• /integrations/artisan/quickstart/
• /integrations/artisan/chrome-renderer-setup/
• /integrations/artisan/security-and-operations/