Gids voor integratiebeslissingen

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

In het kort

Het NextPDF-ecosysteem bestaat uit een kleine core engine plus een aantal gerichte packages: frameworkbruggen, twee HTML-renderers, een edge-renderer en een uitvoeringsserver. Deze pagina koppelt praktische use cases aan het package dat past, op basis van wat elk package daadwerkelijk bevat. De keuze blijft bij u: onderbouwd met bewijs, niet impliciet voorgeschreven door de documentatie.

Waarom dit belangrijk is

De verkeerde integratie kiezen is duurder dan op het eerste gezicht zichtbaar wordt. Kiest u voor een externe browser-renderer terwijl de in-process engine het document correct had weergegeven, dan voegt u voor elke PDF een netwerkstap en een beschikbaarheidsafhankelijkheid toe. Kiest u de in-process engine voor een document dat werkelijk een volledige browser-layout-engine nodig heeft, dan krijgt u een bestand dat subtiel verkeerd is. Het package dat u kiest, bepaalt latentie, faalmodi en het operationele oppervlak, dus de beslissing verdient het om expliciet te zijn.

De korte versie

Begin met de core engine. Al het overige is aanvullend. Als de in-process engine uw document correct weergeeft, hebt u helemaal geen renderer-package nodig.
De frameworkbrug volgt uw framework, niet uw document. De integraties voor Laravel, Symfony en CodeIgniter bestaan zodat u een facade of factory, een PDF-respons, generatie via een wachtrij en auto-discovery krijgt — ze veranderen niets aan wat de engine kan weergeven.
Gebruik pas een renderer wanneer CSS-getrouwheid een browser vereist. Artisan (lokale Chrome) en Cloudflare (edge-browser) bestaan precies daarvoor; Gotenberg is er voor Office-documenten.
Gebruik Connect wanneer de aanroeper een service of AI-agent is, geen PHP-aanroep. Het stelt de engine beschikbaar via MCP, REST en gRPC, met een goedkeuringsstap door een mens voor gevaarlijke bewerkingen.

Hoe NextPDF dit aanpakt

Het ecosysteem is bewust gelaagd zodat elk package één taak heeft. De core engine geeft PDF in-process weer. Een frameworkbrug past die engine aan de idiomen van een framework aan. Een renderer-package delegeert de lay-out van HTML of Office-documenten aan een externe engine wanneer de in-process variant niet het juiste gereedschap is. Connect maakt van de engine een netwerkservice. Geen van deze packages overlapt de verantwoordelijkheid van een ander, en juist dat maakt de beslissing hanteerbaar. U kiest niet tussen concurrerende tools. U stelt complementaire tools samen.

Neem de beslissing op basis van de use case. De tabel koppelt elk scenario aan het package dat past en benoemt de afweging die u daarmee accepteert.

Use case	Package dat past	Wat het daadwerkelijk biedt	De afweging die u accepteert
PDF in een Laravel-app	`nextpdf/laravel`	Automatisch gedetecteerde service provider, `Pdf`-facade, `PdfResponse` (inline/download/gestreamd, OWASP-headers), een `GeneratePdfJob` in de wachtrij met tries/timeout/backoff, Octane-veilige vergrendelde registries	Een afhankelijkheid van Laravel 12; de mogelijkheden van de engine blijven onveranderd
PDF in een Symfony-app	`nextpdf/symfony`	Automatisch geregistreerde bundle, injecteerbare `PdfFactory`, `PdfResponse`, een optionele Messenger-handler voor asynchrone generatie	Een afhankelijkheid van een Symfony 7.2-bundle; mogelijkheden onveranderd
PDF in een CodeIgniter 4-app	`nextpdf/codeigniter`	`service('pdf')`- / `pdf()`-helper, een `Pdf`-library die een wegwerpbaar `Document` omhult, een `PdfResponse`, een optionele job in de wachtrij	Een afhankelijkheid van CodeIgniter 4.6; mogelijkheden onveranderd
Document heeft volledige browser-CSS nodig (flex/grid/webfonts), dicht bij de in-process uitvoering	`nextpdf/artisan`	Headless Chrome via CDP, weergegeven en vervolgens teruggeïmporteerd als een Form XObject zodat tekst selecteerbaar blijft; een browserpool	Een Chrome-runtime en de bijbehorende memory/process-kosten op uw host
Office-documenten (`.docx`, `.xlsx`) naar PDF	`nextpdf/gotenberg`	Een PSR-18-brug naar een Gotenberg-microservice met SSRF-gehard, IP-vastgepind transport	Een externe Gotenberg-service en een netwerkafhankelijkheid
HTML→PDF aan de edge / geen lokale Chrome	`nextpdf/cloudflare`	Cloudflare Browser Rendering via vastgepind transport, met optionele terugval op lokale Chrome	Een Cloudflare-account en een netwerkafhankelijkheid; de terugval vereist Artisan
Engine aangeroepen door een service of AI-agent	`nextpdf/server` (Connect)	Eén engine via MCP (stdio), REST (OpenAPI 3.1) en gRPC; tool-discovery via soft dependencies; een bevestigingsstap door een mens voor tools met een hoog risico	Een te beheren serviceoppervlak; discipline rond deterministische uitvoering

Wat het bewijs zegt

Deze pagina is redactioneel — een routeringsbeslissing — maar de routering is gebaseerd op wat het manifest en de hoofdklassen van elk package bevatten.

De bruggen bestaan echt en lopen parallel. Elk declareert zijn frameworkafhankelijkheid en automatische registratie in zijn composer.json (extra.laravel.providers, extra.symfony.bundles, de CodeIgniter-Registrar). Elk levert daarnaast een PdfResponse, een binding voor een wegwerpdocument en een optionele job in de wachtrij. Geen ervan voegt een weergavemogelijkheid toe — ze passen dezelfde engine aan. De renderers bestaan echt en onderscheiden zich van elkaar. Artisan is afhankelijk van chrome-php/chrome en importeert de Chrome-PDF terug als een Form XObject zodat tekst selecteerbaar blijft. Gotenberg en Cloudflare zijn PSR-18 HTTP-bruggen met expliciet SSRF-gehard, IP-vastgepind transport. Cloudflare kan terugvallen op Artisan wanneer de Worker onbereikbaar is. De composer.json van Connect declareert de drie transportmechanismen en een model van soft dependencies waarbij tools verschijnen naarmate hun packages worden geïnstalleerd, beheerst door een risicomodel met vier niveaus en een bevestigingsstap door een mens.

De manier waarop deze pagina u routeert, is qua vorm gestaafd door normen: Spec: ISO 24495-1:2023, §5 stelt dat lezers snel moeten kunnen bepalen of inhoud aan hun doel beantwoordt, en Spec: ISO/IEC/IEEE 26514:2022, §3.x222 vereist dat koppelingen en verwijzingen hun bestemming vermelden — en daarom noemt de tabel het concrete package en de afweging in plaats van vaag naar „een integratie” te verwijzen.

Praktisch voorbeeld

De beslissing is een reeks rechttoe rechtaan vragen, geen functievergelijking. De volgende beslisstroom lost de gangbare gevallen op.

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.

Het punt zit in de structuur: weergave en aanroep zijn afzonderlijke assen. Ze als één vraag beantwoorden is hoe teams eindigen met een externe renderer die ze niet nodig hadden, of een brug die hun getrouwheidsprobleem niet oplost.

Veelvoorkomend misverstand

Het overheersende misverstand is „Ik heb een renderer-package nodig om PDF’s te genereren.” Dat hebt u niet. De core engine genereert PDF in-process. Renderer-packages bestaan alleen voor het specifieke geval waarin een layout-engine op browserniveau vereist is of de bron een Office-document is. Wanneer de in-process engine al het juiste bestand produceert, voegt het onnodig toevoegen van een renderer een runtime-afhankelijkheid en een faalmodus toe zonder enig voordeel.

Het spiegelbeeldige misverstand is „de frameworkbrug ontgrendelt mogelijkheden.” Dat doet ze niet. Een brug verandert hoe u de engine aanroept — facade, factory, respons, job in de wachtrij — niet wat ze kan produceren. Ondertekening, PDF/A en gestructureerde facturen zijn zaken van het niveau en de engine, identiek of u nu via een brug of rechtstreeks aanroept.

Grenzen en beperkingen

Deze pagina routeert; ze voert geen benchmarks uit en rangschikt niet. Ze benoemt wat elk package biedt en de afweging. De keuze daartussen is uw beslissing, op basis van uw randvoorwaarden.
De mogelijkheden van packages zijn een momentopname van hun manifesten en hoofdklassen. Beschouw de eigen documentatie van elk package als gezaghebbend voor zijn huidige API. Deze gids is de kaart, niet de specificatie.
Er wordt geen vergelijking met concurrenten geboden of gesuggereerd. Het enige onderwerp is het NextPDF-ecosysteem en hoe de onderdelen ervan samenhangen.
De frameworkbrug en de renderer zijn onafhankelijke keuzes. Een brug breidt de mogelijkheden van de engine niet uit; een renderer is niet afhankelijk van een framework.
Externe renderers voegen een beschikbaarheidsafhankelijkheid toe. Gotenberg en Cloudflare introduceren een netwerkaanroep en een te beheren service; dat is de geaccepteerde afweging, geen verborgen kostenpost.
Mogelijkheden die door het niveau worden ontgrendeld, staan los van de integratie. Commerciële functies worden ontgrendeld door het niveau, niet door enige brug of renderer; zie de grens hieronder.

Ecosystem packages and niveauing — edition availability
Edition	Availability
Core	Elk integratiepackage (bruggen, Artisan, Gotenberg, Cloudflare, Connect) werkt met Core en is Apache-2.0. Ze passen de engine aan of stellen die beschikbaar; ze leggen geen functievoorwaarden op.
Pro	Commerciële mogelijkheden (PAdES baseline-ondertekening, PDF/A, geavanceerde barcodes) worden ontgrendeld door het niveau en zijn dan beschikbaar via elke integratie, niet door van integratie te wisselen.
Enterprise	Gestructureerde facturen, validatiebeleid en de Connect- bevestigingsstap door een mens voor tools met een hoog risico zijn mogelijkheden van het niveau, eveneens onafhankelijk van de integratie.

Gerelateerde documentatie

De HTML-pijplijn — wat de in-process CSS-engine dekt, zodat u weet wanneer een browser-renderer daadwerkelijk nodig is.
Wanneer u NextPDF niet moet gebruiken — de eerlijke grens voor documentproblemen waarvoor de engine niet het juiste gereedschap is.
De PHP 8.4-fundamenten — de runtime-ondergrens die elk package deelt en wat het backport-pad intact houdt.

Woordenlijst

Core engine — nextpdf/core, de in-process PDF 2.0-engine waarop elk ander package voortbouwt.
Frameworkbrug — een integratiepackage (Laravel/Symfony/CodeIgniter) dat de engine aanpast aan de idiomen van een framework zonder de mogelijkheden ervan te veranderen.
Renderer-package — een package dat de lay-out van HTML of Office delegeert aan een externe engine (Artisan/Cloudflare/Gotenberg) wanneer de in-process engine niet het juiste gereedschap is.
Form XObject — een herbruikbaar PDF-inhoudsfragment; Artisan importeert een door de browser weergegeven pagina als zodanig zodat de tekst ervan selecteerbaar blijft.
NextPDF Connect — nextpdf/server, het package dat de engine beschikbaar stelt via MCP, REST en gRPC met een deterministisch uitvoeringsoppervlak.
Soft dependency — het model van Connect waarbij tools automatisch verschijnen naarmate optionele NextPDF-packages worden geïnstalleerd, zonder codewijzigingen.