Der Leitfaden zur Integrationsentscheidung

Spec: ISO/IEC/IEEE 26514:2022, §3.x162 Spec: ISO 24495-1:2023, §5 Evidence: Editorial

Auf einen Blick

Das NextPDF-Ökosystem besteht aus einer kleinen Kern-Engine und einer Reihe fokussierter Pakete — Framework-Bridges, zwei HTML-Renderer, ein Edge-Renderer und ein Ausführungsserver. Diese Seite ordnet reale Anwendungsfälle dem jeweils passenden Paket zu und stützt sich dabei darauf, was jedes Paket tatsächlich enthält. Die Wahl bleibt damit eine Entscheidung, die Sie anhand der Belege treffen, nicht eine, die diese Dokumentation für Sie vorwegnimmt.

Warum das wichtig ist

Eine falsche Integrationswahl ist auf eine Weise teuer, die sich nicht sofort zeigt. Wenn Sie einen entfernten Browser-Renderer wählen, obwohl die In-Process-Engine das Dokument einwandfrei gerendert hätte, fügen Sie jedem PDF einen Netzwerk-Hop und eine Verfügbarkeitsabhängigkeit hinzu. Wenn Sie die In-Process-Engine für ein Dokument wählen, das wirklich eine vollständige Browser-Layout-Engine benötigt, erhalten Sie eine Datei, die auf subtile Weise fehlerhaft ist. Das Paket, das Sie einsetzen, prägt Ihre Latenz, Ihre Fehlerszenarien und Ihren betrieblichen Footprint, weshalb die Entscheidung ausdrücklich getroffen werden sollte.

Die Kurzfassung

Beginnen Sie mit der Kern-Engine. Alles andere ist additiv. Wenn die In-Process-Engine Ihr Dokument korrekt rendert, benötigen Sie kein Renderer-Paket.
Die Framework-Bridge folgt Ihrem Framework, nicht Ihrem Dokument. Die Integrationen für Laravel, Symfony und CodeIgniter existieren, damit Ihnen eine Fassade oder Factory, eine PDF-Antwort, Generierung über eine Queue und Auto-Discovery zur Verfügung stehen — sie ändern nicht, was die Engine rendern kann.
Verwenden Sie einen Renderer nur, wenn die CSS-Wiedergabetreue einen Browser erfordert. Artisan (lokales Chrome) und Cloudflare (Edge-Browser) existieren genau dafür; Gotenberg existiert, um Office-Dokumente zu verarbeiten.
Verwenden Sie Connect, wenn der Aufrufer ein Dienst oder ein KI-Agent ist und kein PHP-Aufruf. Es stellt die Engine über MCP, REST und gRPC bereit, mit einem Bestätigungs-Gate durch Menschen für gefährliche Operationen.

Wie NextPDF es angeht

Das Ökosystem ist absichtlich geschichtet, sodass jedes Paket eine Aufgabe hat. Die Kern-Engine rendert PDFs in-process. Eine Framework-Bridge passt diese Engine an die Idiome eines Frameworks an. Ein Renderer-Paket delegiert HTML- oder Office-Layout an eine externe Engine, wenn die In-Process-Engine nicht das richtige Werkzeug ist. Connect macht die Engine zu einem Netzwerkdienst. Keines dieser Pakete überschneidet sich mit der Zuständigkeit eines anderen, was die Entscheidung handhabbar macht. Sie wählen nicht zwischen konkurrierenden Werkzeugen; Sie kombinieren einander ergänzende Werkzeuge.

Am besten treffen Sie die Entscheidung anhand des Anwendungsfalls. Die Tabelle ordnet jedes Szenario dem passenden Paket zu und benennt den Kompromiss, den Sie eingehen.

Anwendungsfall	Passendes Paket	Was es tatsächlich bereitstellt	Der Kompromiss, den Sie eingehen
PDF in einer Laravel-App	`nextpdf/laravel`	Automatisch erkannter Service Provider, `Pdf`-Fassade, `PdfResponse` (inline/Download/gestreamt, OWASP-Header), ein `GeneratePdfJob` in der Warteschlange mit tries/timeout/Backoff, Octane-sichere, gesperrte Registries	Eine Laravel-12-Abhängigkeit; die Fähigkeiten der Engine bleiben unverändert
PDF in einer Symfony-App	`nextpdf/symfony`	Automatisch registriertes Bundle, injizierbare `PdfFactory`, `PdfResponse`, ein optionaler Messenger-Handler für asynchrone Generierung	Eine Symfony-7.2-Bundle-Abhängigkeit; die Fähigkeiten bleiben unverändert
PDF in einer CodeIgniter-4-App	`nextpdf/codeigniter`	`service('pdf')` / `pdf()`-Helper, eine `Pdf`-Bibliothek, die ein nur einmal verwendbares `Document` umschließt, ein `PdfResponse`, ein optionaler Job in der Warteschlange	Eine CodeIgniter-4.6-Abhängigkeit; die Fähigkeiten bleiben unverändert
Dokument benötigt vollständiges Browser-CSS (Flex/Grid/Webfonts), möglichst in-process-nah	`nextpdf/artisan`	Headless Chrome über CDP, gerendert und dann als Form-XObject zurückimportiert, sodass Text auswählbar bleibt; ein Browser-Pool	Eine Chrome-Laufzeitumgebung und ihre memory/process-Kosten auf Ihrem Host
Office-Dokumente (`.docx`, `.xlsx`) zu PDF	`nextpdf/gotenberg`	Eine PSR-18-Bridge zu einem Gotenberg-Microservice mit SSRF-gehärtetem, IP-gepinntem Transport	Ein externer Gotenberg-Dienst und eine Netzwerkabhängigkeit
HTML→PDF am Edge / kein lokales Chrome	`nextpdf/cloudflare`	Cloudflare Browser Rendering über gepinnten Transport, mit optionalem lokalem Chrome-Fallback	Ein Cloudflare-Konto und eine Netzwerkabhängigkeit; der Fallback benötigt Artisan
Engine, die von einem Dienst oder KI-Agenten konsumiert wird	`nextpdf/server` (Connect)	Die Engine über MCP (stdio), REST (OpenAPI 3.1) und gRPC; Soft-Dependency-Tool-Discovery; ein Bestätigungs-Gate durch Menschen für Hochrisiko-Tools	Betrieb einer Dienstschnittstelle; Disziplin bei deterministischer Ausführung

Was die Belege sagen

Diese Seite ist redaktionell — eine Routing-Entscheidung —, aber das Routing stützt sich darauf, was das Manifest und die Hauptklassen jedes Pakets tatsächlich enthalten.

Die Bridges sind real und parallel aufgebaut. Jede deklariert ihre Framework-Abhängigkeit und Auto-Registrierung in ihrer composer.json (extra.laravel.providers, extra.symfony.bundles, der CodeIgniter-Registrar). Jede liefert außerdem ein PdfResponse, eine Bindung für ein nur einmal verwendbares Dokument und einen optionalen Job in der Warteschlange. Keine von ihnen fügt eine Rendering-Fähigkeit hinzu — sie passen dieselbe Engine an. Die Renderer sind real und klar voneinander abgegrenzt. Artisan hängt von chrome-php/chrome ab und importiert das Chrome-PDF als Form-XObject zurück, um Text auswählbar zu halten. Gotenberg und Cloudflare sind PSR-18-HTTP-Bridges mit ausdrücklich SSRF-gehärteten, IP-gepinnten Transporten. Cloudflare kann auf Artisan zurückfallen, wenn der Worker nicht erreichbar ist. Die composer.json von Connect deklariert die drei Transporte und ein Soft-Dependency-Modell, in dem Tools erscheinen, sobald ihre Pakete installiert werden, gesteuert durch ein vierstufiges Risikomodell mit einem Bestätigungs-Gate durch Menschen.

Die Form, in der diese Seite Sie leitet, ist standardgestützt: Spec: ISO 24495-1:2023, §5 besagt, dass Leser in der Lage sein sollten schnell festzustellen, ob ein Inhalt ihrem Zweck dient (Chunk), und Spec: ISO/IEC/IEEE 26514:2022, §3.x222 verlangt, dass Links und Verweise ihr Ziel angeben — deshalb benennt die Tabelle das konkrete Paket und den Kompromiss, anstatt vage auf „eine Integration“ zu verweisen.

Praktisches Beispiel

Die Entscheidung ergibt sich aus ehrlichen Fragen, nicht aus einem Funktionsvergleich. Der folgende Ablauf klärt die häufigen Fälle.

1. Does the in-process engine render the document correctly?
   YES → you need NO renderer package. Stop here for rendering.
   NO  → continue.

2. Is the source an Office file (.docx/.xlsx)?
   YES → nextpdf/gotenberg (external Gotenberg service).
   NO  → continue (it is HTML/CSS fidelity you need).

3. Can you run a local Chrome on the host?
   YES → nextpdf/artisan (local CDP renderer).
   NO  → nextpdf/cloudflare (edge; optional Artisan fallback).

Independently of 1–3, choose how the engine is CALLED:
   In a PHP web app?        → the matching framework bridge.
   By a service / AI agent? → nextpdf/server (Connect).
   Neither?                 → use the core engine directly.

Die Struktur ist der entscheidende Punkt: Rendering und Aufruf sind getrennte Achsen. Wer beides zusammen beantwortet, landet leicht bei einem entfernten Renderer, der nicht gebraucht wurde, oder bei einer Bridge, die das Wiedergabetreue-Problem nicht löst.

Häufiges Missverständnis

Das häufigste Missverständnis lautet „Ich brauche ein Renderer-Paket, um PDFs zu erzeugen.“ Das brauchen Sie nicht. Die Kern-Engine erzeugt PDF in-process. Renderer-Pakete existieren nur für den speziellen Fall, dass eine Layout-Engine mit Browser-Qualität erforderlich ist oder die Quelle ein Office-Dokument ist. Wenn die In-Process-Engine bereits eine korrekte Datei erzeugt, fügt die reflexhafte Übernahme eines Renderers eine Laufzeitabhängigkeit und ein Fehlerszenario ohne jeden Nutzen hinzu.

Das spiegelbildliche Missverständnis lautet „Die Framework-Bridge schaltet Fähigkeiten frei.“ Das tut sie nicht. Eine Bridge ändert, wie Sie die Engine aufrufen — Fassade, Factory, Antwort, Job in der Warteschlange — nicht, was sie erzeugen kann. Signieren, PDF/A und strukturierte Rechnungen sind Belange der Edition und der Engine, unabhängig davon, ob Sie über eine Bridge oder direkt aufrufen.

Grenzen und Abgrenzungen

Diese Seite leitet; sie führt keine Benchmarks durch und erstellt kein Ranking. Sie benennt, was jedes Paket bereitstellt und welchen Kompromiss Sie eingehen. Die Auswahl treffen Sie anhand Ihrer Rahmenbedingungen.
Die Paketfähigkeiten werden zu einem bestimmten Zeitpunkt aus den jeweiligen Manifesten und Hauptklassen gelesen. Behandeln Sie die eigene Dokumentation des jeweiligen Pakets als maßgeblich für dessen aktuelle API. Dieser Leitfaden ist die Landkarte, nicht die Spezifikation.
Es wird kein Wettbewerbervergleich angeboten oder impliziert. Das einzige Thema ist das NextPDF-Ökosystem und wie seine Teile zusammenpassen.
Die Framework-Bridge und der Renderer sind voneinander unabhängige Entscheidungen. Eine Bridge erweitert nicht die Fähigkeiten der Engine; ein Renderer hängt nicht von einem Framework ab.
Externe Renderer fügen eine Verfügbarkeitsabhängigkeit hinzu. Gotenberg und Cloudflare führen einen Netzwerkaufruf und einen Dienst ein, den Sie betreiben müssen; das ist der akzeptierte Kompromiss, kein versteckter Kostenpunkt.
Editionsgebundene Fähigkeiten sind orthogonal zur Integration. Kommerzielle Funktionen werden durch die Edition freigeschaltet, nicht durch eine Bridge oder einen Renderer; siehe die Abgrenzung unten.

Ecosystem packages and tiering — edition availability
Edition	Availability
Core	Jedes Integrationspaket (Bridges, Artisan, Gotenberg, Cloudflare, Connect) arbeitet mit Core und ist Apache-2.0. Sie passen die Engine an oder stellen sie bereit; sie schalten keine Funktionen frei.
Pro	Kommerzielle Fähigkeiten (PAdES-Baseline-Signierung, PDF/A, erweiterte Barcodes) werden durch die Edition freigeschaltet und sind dann über jede Integration verfügbar, nicht durch einen Wechsel der Integration.
Enterprise	Strukturierte Rechnungen, Validierungsrichtlinien und das Bestätigungs-Gate durch Menschen für Hochrisiko-Tools von Connect sind Editionsfähigkeiten, ebenfalls integrationsunabhängig.

Glossar

Kern-Engine — nextpdf/core, die In-Process-PDF-2.0-Engine, auf der jedes andere Paket aufbaut.
Framework-Bridge — ein Integrationspaket (Laravel/Symfony/CodeIgniter), das die Engine an die Idiome eines Frameworks anpasst, ohne ihre Fähigkeiten zu ändern.
Renderer-Paket — ein Paket, das HTML- oder Office-Layout an eine externe Engine (Artisan/Cloudflare/Gotenberg) delegiert, wenn die In-Process-Engine nicht das richtige Werkzeug ist.
Form-XObject — ein wiederverwendbares PDF-Inhaltsfragment; Artisan importiert eine browsergerenderte Seite als ein solches, sodass ihr Text auswählbar bleibt.
NextPDF Connect — nextpdf/server, das Paket, das die Engine über MCP, REST und gRPC mit einer deterministischen Ausführungsoberfläche bereitstellt.
Soft-Dependency — das Modell von Connect, bei dem Tools automatisch verfügbar werden, sobald optionale NextPDF-Pakete installiert werden, ohne Codeänderung.