Installare NextPDF Artisan

In breve

Installare nextpdf/artisan con Composer. Installare la dipendenza di runtime chrome-php/chrome richiamata dal pacchetto. Rendere quindi disponibile al processo PHP un binario Chrome o Chromium.

Installazione

composer require nextpdf/artisan

Il pacchetto dichiara i seguenti vincoli in composer.json:

Requisito	Vincolo	Note
`php`	`>=8.4 <9.0`	Solo PHP 8.4
`nextpdf/core`	`^3.0 \|\| ^5.2`	Il motore NextPDF open source
`chrome-php/chrome`	`^1.15`	Libreria client CDP; inclusa in modo transitivo
`psr/log`	`^3.0`	Punto di iniezione opzionale per il logger

Composer risolve chrome-php/chrome automaticamente. Il binario di Chrome è una dipendenza di sistema e non viene mai installato da Composer.

Predisporre il binario Chrome

Il bridge richiede un eseguibile Chrome o Chromium. Per impostazione predefinita, chrome-php/chrome rileva automaticamente un binario nei percorsi comuni. Per fissare un percorso esplicito, passarlo tramite la configurazione: vedere /integrations/artisan/configuration/ e la pagina dedicata /integrations/artisan/chrome-renderer-setup/.

# Debian / Ubuntu
apt-get install -y chromium

# RHEL / Fedora
dnf install -y chromium

# macOS (Homebrew)
brew install --cask chromium

Verificare che il binario possa essere eseguito in modalità headless prima di integrarlo nell’applicazione:

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

Un’esecuzione riuscita stampa un documento DOM vuoto e termina con codice 0. Un codice di uscita diverso da zero indica che il binario o le relative librerie condivise mancano. Correggere il problema prima di continuare, perché in fase di rendering il bridge espone lo stesso errore come ChromeRenderException.

Verificare il collegamento del pacchetto

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

Il frammento costruisce il renderer e rilegge il criterio di sicurezza HTML predefinito senza avviare Chrome. Conferma che l’autoloading e i binding del contratto nextpdf/core siano risolti. (Comportamento verificato da tests/Unit/Artisan/ChromeHtmlRendererTest.php::usesDefaultHtmlSecurityPolicyWhenNoneInjected.)

Installazioni in container

In Docker, di solito la sandbox di Chrome non può avviarsi come PID 1 / root senza capability del kernel aggiuntive. Per questo scenario il pacchetto espone l’opzione noSandbox. Disabilitare la sandbox di Chrome comporta un costo reale in termini di sicurezza. Le pagine /integrations/artisan/security-and-operations/ e /integrations/artisan/chrome-renderer-setup/ documentano tale costo e ne dichiarano esplicitamente i limiti. Non impostare l’opzione senza aver letto quelle sezioni.

Casi limite e insidie

chrome-php/chrome presente ma senza binario. Composer va a buon fine; il primo rendering genera ChromeRenderException, che incapsula l’errore di avvio. La verifica della libreria è distinta da quella del binario.
chrome-php/chrome assente. Se la libreria viene rimossa dall’autoloader, BrowserPool::getBrowser() genera ChromeNotAvailableException con l’esatto comando di risoluzione. (Verificato da tests/Unit/Artisan/BrowserPoolTest.php::getBrowserThrowsWhenChromePhpPackageIsUnavailable.)
Vincolo di versione. nextpdf/core: ^3.0 || ^5.2 — Artisan supporta entrambe le linee major del core. Fissare la versione del core a cui deve puntare l’applicazione.

Note sulla sicurezza

L’installazione del bridge introduce un processo esterno (Chrome) all’interno del confine di attendibilità. Consultare /integrations/artisan/security-and-operations/ prima di esporre qualsiasi percorso di rendering a HTML fornito dall’utente.

Vedere anche

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