Integrations-Cookbook
Integrations-Cookbook
Abschnitt betitelt „Integrations-Cookbook“NextPDF Core rendert PDF 2.0 aus PHP heraus. Die neun Integrationspakete im Ökosystem verbinden diese Engine mit einem Framework, einem Rendering-Backend, einer Legacy-Codebasis, einer Build-Pipeline oder einem Netzwerkdienst. Diese Seite erklärt, wofür jede Integration gedacht ist, hält den Paketnamen und die Core-Versionsbeschränkung der jeweiligen Integration fest (direkt aus der composer.json des jeweiligen Pakets gelesen) und verlinkt auf die Recipes je Integration, die hier erscheinen, sobald die Quell-Repositories ihre docs/public/-Verzeichnisbäume bereitstellen.
Diese Seite ist ein Index und trifft daher keine Aussagen zum Verhalten einzelner Integrationen. Die Recipes jeder Integration werden in ihrem eigenen Repository verwaltet. Der Aggregator übernimmt sie in diese Site; solange ein Recipe noch nicht aggregiert wurde, verweist der Link unten auf einen Platzhalter. Für eine anwendungsfallgetriebene Empfehlung lesen Sie Eine Integration auswählen. Für den Vertrag, dem jedes ausführbare Recipe folgt, lesen Sie Recipe-Konventionen.
Die fünf Integrationsformen
Abschnitt betitelt „Die fünf Integrationsformen“Die neun Pakete teilen sich in fünf Formen auf. Die Form beschreibt, welche Art von Problem die Integration löst.
- Framework-Integrationen verdrahten NextPDF in den Service-Container und den Request-Lebenszyklus eines Anwendungs-Frameworks:
nextpdf/laravel,nextpdf/symfony,nextpdf/codeigniter. Sie installieren eines davon, lösen einen Service auf und geben eine PDF-Response zurück. - Renderer-Brücken delegieren den HTML-zu-PDF- oder Office-zu-PDF-Schritt an ein externes Rendering-Backend und nicht an die In-Process-Pipeline:
nextpdf/artisan(headless Chrome über das Chrome DevTools Protocol),nextpdf/gotenberg(ein Gotenberg-Microservice),nextpdf/cloudflare(Cloudflare Browser Rendering am Edge). - Ein Kompatibilitäts-Shim ermöglicht einer Codebasis, die gegen eine Legacy-PDF-Bibliothek geschrieben wurde, NextPDF ohne Umschreiben aufzurufen:
nextpdf/compat-legacy. - Ein Build-Tool erzeugt einen PHP-8.1-/7.4-Backport von NextPDF für Laufzeitumgebungen, die 8.4 nicht ausführen können:
nextpdf/backport-builder. - Ein Netzwerkdienst stellt NextPDF über REST, gRPC und das Model Context Protocol für KI-Systeme und entfernte Aufrufer bereit:
nextpdf/server(vertrieben als NextPDF Connect).
Die Renderer-Brücken, die über HTTP kommunizieren (nextpdf/gotenberg, nextpdf/cloudflare und der HTTP-Client-Pfad in nextpdf/laravel), hängen von einem PSR-18-HTTP-Client ab, den die Host-Anwendung bereitstellt. Ein PSR-18-Client wirft nur dann eine typisierte Client-Exception, wenn er den Request überhaupt nicht senden kann, wie die maßgebliche Klausel PSR-18 §4 festlegt. Eine HTTP-4xx- oder -5xx-Response ist ein normaler Rückgabewert und keine Exception; auch das legt PSR-18 §4 fest. Recipes, die einen entfernten Renderer aufrufen, behandeln Transportfehler und Nicht-Erfolgsstatus als getrennte Fälle.
Referenz zu Paket und Core-Beschränkung
Abschnitt betitelt „Referenz zu Paket und Core-Beschränkung“Jeder Wert in der folgenden Tabelle wird aus der composer.json des jeweils genannten Pakets gelesen; diese Datei ist die maßgebliche Quelle. Die Core-Beschränkung ist die vom Paket deklarierte nextpdf/core-Anforderung. nextpdf/backport-builder deklariert keine nextpdf/core-Anforderung, weil es den Engine-Quellcode transformiert, statt zur Laufzeit von der Engine abzuhängen.
| Integration | Paket | Form | Core-Beschränkung | Recipe |
|---|---|---|---|---|
| Laravel | nextpdf/laravel | Framework | ^3.0 || ^5.2 | Laravel-Quickstart [[/integrations/laravel/quickstart/]] |
| Symfony | nextpdf/symfony | Framework | ^3.0 || ^5.2 | Symfony-Quickstart [[/integrations/symfony/quickstart/]] |
| CodeIgniter 4 | nextpdf/codeigniter | Framework | ^3.0 || ^5.2 | CodeIgniter-Quickstart [[/integrations/codeigniter/quickstart/]] |
| Artisan (Chrome) | nextpdf/artisan | Renderer-Brücke | ^3.0 || ^5.2 | Artisan-Quickstart [[/integrations/artisan/quickstart/]] |
| Gotenberg | nextpdf/gotenberg | Renderer-Brücke | ^3.0 | Gotenberg-Quickstart [[/integrations/gotenberg/quickstart/]] |
| Cloudflare | nextpdf/cloudflare | Renderer-Brücke | ^3.0 | Cloudflare-Quickstart [[/integrations/cloudflare/quickstart/]] |
| Compat (Legacy) | nextpdf/compat-legacy | Kompatibilitäts-Shim | ^3.0 | Compat-legacy-Quickstart [[/integrations/compat-legacy/quickstart/]] |
| Backport-Builder | nextpdf/backport-builder | Build-Tool | nicht zutreffend | Backport-Quickstart [[/integrations/backport/quickstart/]] |
| Connect (Server) | nextpdf/server | Netzwerkdienst | ^3.0 | Connect-Quickstart [[/integrations/connect/quickstart/]] |
NextPDF vertreibt nextpdf/server unter dem Produktnamen NextPDF Connect; die Recipes dafür liegen unter dem Slug connect. nextpdf/compat-legacy stammt aus der compat-Familie; die Recipes dafür liegen unter dem Slug compat-legacy.
Jedes Paket erfordert PHP >=8.4 <9.0 in seiner eigenen Laufzeitumgebung. nextpdf/backport-builder existiert speziell dazu, Artefakte zu erzeugen, die auf PHP 8.1 (und einem 7.4-Ziel) laufen; auf der älteren Laufzeitumgebung läuft die daraus resultierende backportete Engine, nicht der Builder.
Wofür jede Integration da ist
Abschnitt betitelt „Wofür jede Integration da ist“Framework-Integrationen
Abschnitt betitelt „Framework-Integrationen“nextpdf/laravel— ein Laravel-12-Service-Provider, eine Facade und PDF-Response-Helpers. Verwenden Sie es, wenn Ihre Anwendung eine Laravel-App ist und Sie NextPDF aus dem Container auflösen und ohne manuelle Verdrahtung als HTTP-Response zurückgeben möchten. Recipe: [[/integrations/laravel/quickstart/]].nextpdf/symfony— ein Symfony-7-Bundle mit Dependency-Injection-Services und PDF-Response-Helpers. Verwenden Sie es, wenn Ihre Anwendung eine Symfony-App ist; das Bundle registriert die Engine als Service und bindet sich insymfony/http-foundation-Responses ein. Recipe: [[/integrations/symfony/quickstart/]].nextpdf/codeigniter— ein CodeIgniter-4-Service, ein Library-Wrapper und PDF-Response-Helpers. Verwenden Sie es, wenn Ihre Anwendung eine CodeIgniter-4-App ist und Sie NextPDF über den Service-Locator des Frameworks verfügbar machen möchten. Recipe: [[/integrations/codeigniter/quickstart/]].
Renderer-Brücken
Abschnitt betitelt „Renderer-Brücken“nextpdf/artisan— ein Headless-Chrome-Renderer über das Chrome DevTools Protocol. Verwenden Sie es, wenn ein Dokument die CSS-Engine eines Browsers für eine Layouttreue benötigt, die die In-Process-HTML-Pipeline nicht anstrebt, und Sie einen Chrome-Prozess nahe der Anwendung betreiben können. Recipe: [[/integrations/artisan/quickstart/]].nextpdf/gotenberg— Office-zu-PDF- und HTML-zu-PDF-Konvertierung über einen Gotenberg-Microservice. Verwenden Sie es, wenn die Eingabe ein Office-Dokument ist oder das Rendering out-of-process in einem separaten Service laufen muss. Es spricht HTTP über einen vom Host bereitgestellten PSR-18-Client. Recipe: [[/integrations/gotenberg/quickstart/]].nextpdf/cloudflare— serverloses Rendering über die Cloudflare Browser Rendering API. Verwenden Sie es, wenn das Rendering am Edge laufen soll, ohne einen langlebigen Browser-Prozess betreiben zu müssen. Es spricht HTTP über einen vom Host bereitgestellten PSR-18-Client. Recipe: [[/integrations/cloudflare/quickstart/]].
Kompatibilitäts-Shim
Abschnitt betitelt „Kompatibilitäts-Shim“nextpdf/compat-legacy— eine Kompatibilitätsschicht für Codebasen, die gegen eine Legacy-PDF-Bibliothek geschrieben wurden. Verwenden Sie es, um NextPDF aus bestehendem Code aufzurufen, ohne die Aufrufstellen vorher umzuschreiben; es ist eine Migrationshilfe, keine dauerhafte Abhängigkeit. Recipe: [[/integrations/compat-legacy/quickstart/]].
Build-Tool
Abschnitt betitelt „Build-Tool“nextpdf/backport-builder— eine Rector-basierte Downgrade-Pipeline, die einen PHP-8.1-Build (mit 7.4-Ziel) von NextPDF erzeugt. Verwenden Sie es, wenn eine Laufzeitumgebung nicht auf PHP 8.4 umgestellt werden kann und Sie die Engine dort trotzdem benötigen. Es dient als Build-Infrastruktur; es wird nicht zu den Laufzeitabhängigkeiten einer Anwendung hinzugefügt. Recipe: [[/integrations/backport/quickstart/]].
Netzwerkdienst
Abschnitt betitelt „Netzwerkdienst“nextpdf/server(NextPDF Connect) — stellt NextPDF über eine REST-API, einen gRPC-Service und das Model Context Protocol bereit. Verwenden Sie es, wenn die Aufrufer remote sind, in einer anderen Sprache implementiert sind oder KI-Systeme sind, die einen Tool-Endpunkt statt einer PHP-Bibliothek benötigen. Recipe: [[/integrations/connect/quickstart/]].
Wie die Recipe-Links aufgelöst werden
Abschnitt betitelt „Wie die Recipe-Links aufgelöst werden“Jeder [[…]]-Platzhalter oben ist eine Vorwärtsreferenz auf eine Seite, die im eigenen Repository der Integration unter docs/public/ verfasst und vom Aggregator in diese Site übernommen wird. Die Ziel-Slugs folgen einer einzigen Konvention:
/integrations/<integration>/<recipe>/Der <integration>-Token ist der Kurzname, der direkt aus der Referenztabelle zu Paket und Core-Beschränkung oben übernommen wird; jede Zeile dieser Tabelle liefert einen solchen Kurznamen. Das erste Recipe, das jede Integration bereitstellt, heißt quickstart; weitere Recipes verwenden zusätzliche <recipe>-Segmente unter derselben <integration>-Wurzel. Solange eine Zielseite noch nicht aggregiert wurde, ist ihr Link ein Platzhalter und wird nicht aufgelöst. Dieser Index trifft keine Aussagen zum Verhalten einer Zielseite. Er hält nur die aus der composer.json verifizierten Paketfakten und den Slug fest, unter dem die Recipes jedes Repositorys liegen werden.
Siehe auch
Abschnitt betitelt „Siehe auch“- Eine Integration auswählen — eine Entscheidungsmatrix vom Anwendungsfall zur Integration.
- Recipe-Konventionen — der Vertrag, dem jedes ausführbare Recipe in diesem Cookbook folgt.