Instalasi NextPDF Artisan

Sekilas pandang

Pasang nextpdf/artisan dengan Composer. Composer juga akan memasang dependensi runtime chrome-php/chrome. Setelah itu, sediakan biner Chrome atau Chromium agar dapat diakses oleh proses PHP.

Pemasangan

composer require nextpdf/artisan

Paket ini mendeklarasikan batasan berikut dalam composer.json:

Kebutuhan	Batasan	Catatan
php	>=8.4 <9.0	Hanya PHP 8.4
nextpdf/core	^3.0 || ^5.2	Mesin NextPDF sumber terbuka
chrome-php/chrome	^1.15	Pustaka klien Chrome DevTools Protocol (CDP); ditarik sebagai dependensi transitif
psr/log	^3.0	Titik injeksi untuk logger opsional

Composer menyelesaikan chrome-php/chrome secara otomatis. Composer tidak pernah memasang biner Chrome; biner tersebut merupakan dependensi sistem.

Menyediakan biner Chrome

Bridge ini memerlukan biner Chrome atau Chromium yang dapat dieksekusi. Secara baku, chrome-php/chrome mencari biner di jalur-jalur umum. Untuk menetapkan jalur secara eksplisit, tentukan melalui konfigurasi. Lihat /integrations/artisan/configuration/ dan halaman khusus /integrations/artisan/chrome-renderer-setup/.

# Debian / Ubuntu
apt-get install -y chromium

# RHEL / Fedora
dnf install -y chromium

# macOS (Homebrew)
brew install --cask chromium

Sebelum Anda menghubungkan biner ke aplikasi, pastikan biner tersebut berjalan secara headless:

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

Perintah yang berhasil mencetak dokumen Document Object Model (DOM) kosong dan keluar dengan kode 0. Kode keluar bukan nol berarti biner atau pustaka bersama yang dibutuhkannya tidak ada. Perbaiki hal itu sebelum melanjutkan, karena bridge akan memunculkan kegagalan yang sama berupa ChromeRenderException saat rendering.

Verifikasi paket telah tersambung

<?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

Cuplikan ini membuat renderer dan membaca kebijakan keamanan Hypertext Markup Language (HTML) baku tanpa meluncurkan Chrome. Cuplikan ini memastikan bahwa autoloading dan pengikatan kontrak nextpdf/core dapat diselesaikan. (Perilaku ini ditegaskan oleh tests/Unit/Artisan/ChromeHtmlRendererTest.php::usesDefaultHtmlSecurityPolicyWhenNoneInjected.)

Pemasangan dalam kontainer

Di Docker, sandbox Chrome biasanya tidak dapat dijalankan sebagai process ID (PID) 1 / root tanpa kapabilitas kernel tambahan. Paket ini menyediakan opsi noSandbox untuk kasus tersebut. Menonaktifkan sandbox Chrome memiliki konsekuensi keamanan yang nyata. Halaman /integrations/artisan/security-and-operations/ dan /integrations/artisan/chrome-renderer-setup/ mendokumentasikan konsekuensi tersebut dan menyatakan batasannya secara eksplisit. Jangan aktifkan opsi tersebut tanpa membaca bagian itu.

Kasus tepi & jebakan

• chrome-php/chrome ada tetapi binernya tidak ada. Composer berhasil; rendering pertama melempar ChromeRenderException dan membungkus kegagalan peluncuran. Pemeriksaan pustaka terpisah dari pemeriksaan biner.
• chrome-php/chrome tidak ada. Jika pustaka dihapus dari autoloader, BrowserPool::getBrowser() melempar ChromeNotAvailableException beserta perintah perbaikan yang tepat. (Ditegaskan oleh tests/Unit/Artisan/BrowserPoolTest.php::getBrowserThrowsWhenChromePhpPackageIsUnavailable.)
• Batasan versi. nextpdf/core: ^3.0 || ^5.2 — Artisan mendukung kedua lini mayor core. Tetapkan versi core yang menjadi target aplikasi Anda.

Catatan keamanan

Memasang bridge memasukkan proses eksternal (Chrome) ke dalam batas kepercayaan. Tinjau /integrations/artisan/security-and-operations/ sebelum Anda membuka jalur rendering apa pun untuk HTML yang dipasok pengguna.

Lihat juga

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