NextPDF Artisan installieren

Auf einen Blick

Installieren Sie nextpdf/artisan mit Composer. Installieren Sie außerdem die Laufzeitabhängigkeit chrome-php/chrome, die Composer transitiv mitzieht. Sorgen Sie anschließend dafür, dass ein Chrome- oder Chromium-Binary für den PHP-Prozess erreichbar ist.

Installation

composer require nextpdf/artisan

Das Paket deklariert die folgenden Constraints in composer.json:

Anforderung	Constraint	Hinweise
php	>=8.4 <9.0	Nur PHP 8.4
nextpdf/core	^3.0 || ^5.2	Die quelloffene NextPDF-Engine
chrome-php/chrome	^1.15	CDP-Client-Bibliothek; wird transitiv mitgezogen
psr/log	^3.0	Optionaler Injektionspunkt für einen Logger

Composer löst chrome-php/chrome automatisch auf. Das Chrome-Binary ist eine Systemabhängigkeit; Composer installiert es niemals.

Das Chrome-Binary bereitstellen

Die Brücke benötigt ein ausführbares Chrome oder Chromium. Standardmäßig erkennt chrome-php/chrome ein Binary auf gängigen Pfaden automatisch. Wenn Sie einen expliziten Pfad festlegen möchten, geben Sie ihn über die Konfiguration weiter — siehe /integrations/artisan/configuration/ sowie die separate Seite /integrations/artisan/chrome-renderer-setup/.

# Debian / Ubuntu
apt-get install -y chromium

# RHEL / Fedora
dnf install -y chromium

# macOS (Homebrew)
brew install --cask chromium

Prüfen Sie, ob das Binary headless läuft, bevor Sie es in die Anwendung einbinden:

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

Ein erfolgreicher Lauf gibt ein leeres DOM-Dokument aus und beendet sich mit 0. Ein Exit-Code ungleich null bedeutet, dass das Binary oder seine Shared Libraries fehlen. Beheben Sie das, bevor Sie fortfahren, denn die Brücke meldet denselben Fehler zur Render-Zeit als ChromeRenderException.

Prüfen, ob das Paket eingebunden ist

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

Dies erstellt den Renderer und liest die Standard-HTML-Sicherheitsrichtlinie aus, ohne Chrome zu starten. Damit wird bestätigt, dass das Autoloading funktioniert und die Contract-Bindings von nextpdf/core aufgelöst werden. (Abgesichert durch tests/Unit/Artisan/ChromeHtmlRendererTest.php::usesDefaultHtmlSecurityPolicyWhenNoneInjected.)

Container-Installationen

In Docker kann die Chrome-Sandbox ohne zusätzliche Kernel-Capabilities in der Regel nicht als PID 1 / root starten. Für diesen Fall stellt das Paket einen noSandbox-Schalter bereit. Das Deaktivieren der Chrome-Sandbox bringt reale Sicherheitskosten mit sich. Die Seiten /integrations/artisan/security-and-operations/ und /integrations/artisan/chrome-renderer-setup/ dokumentieren diese Kosten und benennen die Grenzen ausdrücklich. Setzen Sie den Schalter nicht, ohne diesen Abschnitt gelesen zu haben.

Randfälle & Fallstricke

• chrome-php/chrome vorhanden, aber kein Binary. Composer läuft erfolgreich durch; der erste Render-Vorgang wirft ChromeRenderException und kapselt damit den Startfehler. Die Prüfung der Bibliothek ist von der Prüfung des Binarys getrennt.
• chrome-php/chrome fehlt. Wird die Bibliothek aus dem Autoloader entfernt, wirft BrowserPool::getBrowser() eine ChromeNotAvailableException mit dem genauen Behebungsbefehl. (Abgesichert durch tests/Unit/Artisan/BrowserPoolTest.php::getBrowserThrowsWhenChromePhpPackageIsUnavailable.)
• Versions-Constraint. nextpdf/core: ^3.0 || ^5.2 — Artisan unterstützt beide Major-Linien des Cores. Pinnen Sie die Core-Version, auf die Ihre Anwendung abzielt.

Sicherheitshinweise

Mit der Installation der Brücke holen Sie einen externen Prozess (Chrome) in die Vertrauensgrenze. Lesen Sie /integrations/artisan/security-and-operations/, bevor Sie irgendeinen Render-Pfad für von Benutzern geliefertes HTML offenlegen.

Siehe auch

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