NextPDF Artisan installeren

In het kort

Installeer nextpdf/artisan met Composer. Composer installeert ook de runtime-afhankelijkheid chrome-php/chrome. Stel daarna een Chrome- of Chromium-binary beschikbaar voor het PHP-proces.

Installeren

composer require nextpdf/artisan

Het package definieert deze constraints in composer.json:

Vereiste	Constraint	Opmerkingen
php	>=8.4 <9.0	Alleen PHP 8.4
nextpdf/core	^3.0 || ^5.2	De open-source NextPDF-engine
chrome-php/chrome	^1.15	Clientbibliotheek voor het Chrome DevTools Protocol (CDP); meegeïnstalleerd als transitieve afhankelijkheid
psr/log	^3.0	Optioneel injectiepunt voor een logger

Composer lost chrome-php/chrome automatisch op, maar installeert nooit de Chrome-binary; die binary is een systeemafhankelijkheid.

De Chrome-binary inrichten

De brug vereist een uitvoerbare Chrome- of Chromium-binary. Standaard zoekt chrome-php/chrome op de gebruikelijke paden naar een binary. Geef via de configuratie een expliciet pad door om dat vast te leggen. Raadpleeg /integrations/artisan/configuration/ en de specifieke pagina /integrations/artisan/chrome-renderer-setup/.

# Debian / Ubuntu
apt-get install -y chromium

# RHEL / Fedora
dnf install -y chromium

# macOS (Homebrew)
brew install --cask chromium

Controleer of de binary headless draait voordat je deze in de applicatie aansluit:

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

Een geslaagde uitvoering geeft een leeg Document Object Model (DOM)-document weer en sluit af met code 0. Een exitcode anders dan nul betekent dat de binary of de bijbehorende gedeelde bibliotheken ontbreken. Los dit op voordat je verdergaat, want tijdens het renderen geeft de brug dezelfde fout door als een ChromeRenderException.

Controleer of het package is aangesloten

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

Dit maakt de renderer aan en leest het standaardbeveiligingsbeleid voor Hypertext Markup Language (HTML) zonder Chrome te starten. Zo bevestig je dat de autoloading en de contractbindingen van nextpdf/core correct worden opgelost. (Gedrag bevestigd door tests/Unit/Artisan/ChromeHtmlRendererTest.php::usesDefaultHtmlSecurityPolicyWhenNoneInjected.)

Installaties in containers

In Docker kan de Chrome-sandbox zonder extra kernel-capabilities doorgaans niet starten als process-ID (PID) 1 / root. Het package biedt hiervoor een noSandbox-schakelaar. Het uitschakelen van de Chrome-sandbox heeft een reële beveiligingsimpact. De pagina’s /integrations/artisan/security-and-operations/ en /integrations/artisan/chrome-renderer-setup/ documenteren die impact en benoemen de grenzen ervan expliciet. Zet de schakelaar niet aan zonder die toelichting te lezen.

Randgevallen en valkuilen

• chrome-php/chrome aanwezig, maar geen binary. Composer slaagt; de eerste render gooit een ChromeRenderException en verpakt de opstartfout. De controle van de bibliotheek staat los van de controle van de binary.
• chrome-php/chrome ontbreekt. Als de bibliotheek uit de autoloader wordt verwijderd, gooit BrowserPool::getBrowser() een ChromeNotAvailableException met het exacte herstelcommando. (Bevestigd door tests/Unit/Artisan/BrowserPoolTest.php::getBrowserThrowsWhenChromePhpPackageIsUnavailable.)
• Versieconstraint. nextpdf/core: ^3.0 || ^5.2 — Artisan ondersteunt beide major-versielijnen van core. Leg de core-versie vast waarop je applicatie is afgestemd.

Beveiligingsopmerkingen

Het installeren van de brug haalt een extern proces (Chrome) binnen de vertrouwensgrens. Raadpleeg /integrations/artisan/security-and-operations/ voordat je een renderpad blootstelt aan door gebruikers aangeleverde HTML.

Zie ook

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