Genereer uw eerste PDF met NextPDF Connect

In het kort

Dit recipe biedt u de kortste route van een lege sessie naar een gerenderde PDF met NextPDF Connect. U maakt een document van één pagina op A4-formaat, voegt een kop en een ondertitel toe en retourneert het bestand vervolgens als base64. Drie Core-tools doen het werk: create_pdf, add_text en output_pdf. U hebt geen lettertypen, afbeeldingen of een gelicentieerd niveau nodig.

Een Connect-transport verstuurt elke toolaanroep als een verzoek en retourneert het resultaat van de tool als een respons. De transportlaag staat los van het resultaat dat de tool rapporteert (PSR-18 §p2).

Installeren

Installeer NextPDF Server en koppel een transport:

composer require nextpdf/server

Start de server met het transport dat uw host verwacht: Model Context Protocol via stdio, REST of gRPC. Zie Beschikbaarheid van transporten hieronder. De tools in dit recipe zijn Core-tools. Ze worden met de server meegeleverd, dus u hebt geen Pro- of Enterprise-pakket nodig.

Conceptueel overzicht

Een Connect-sessie is documentopslag aan de serverzijde die op een document_id wordt geïndexeerd. create_pdf opent een sessie en retourneert de ID. Elke volgende toolaanroep gebruikt die ID. Het document begint met één lege pagina. De paginaboom is de structuur die een lezer gebruikt om elke pagina te bereiken (ISO 32000-2 §7.7.3). output_pdf rendert de sessie naar een PDF. Standaard vernietigt het daarna de sessie om geheugen vrij te maken.

Wanneer u add_text aanroept zonder expliciete x of y, wordt de tekst automatisch geplaatst. De tekst begint bij de huidige cursor, en de cursor schuift na elke aanroep op.

API-oppervlak

Het toolregister resolveert deze tools wanneer de server start. De hier getoonde namen zijn de protocolnamen van het register. De geldende catalogus is de samengevoegde toolcatalogus. Welke tools beschikbaar zijn, hangt af van het geïnstalleerde niveau, maar deze drie zijn altijd aanwezig in Core.

Tool	Rol	Risiconiveau
`create_pdf`	Een documentsessie openen	Safe
`add_text`	Tekst in het document schrijven	Caution
`output_pdf`	De PDF renderen en retourneren	Approval Required (bestandsmodus) / Review (base64)

Codevoorbeeld — Snelstart

De host voert drie toolaanroepen uit. In deze volgorde:

Roep create_pdf aan met page_size: "A4", orientation: "portrait", en de titel en auteur van het document. De server retourneert een document_id.
Roep add_text aan met die document_id, de koptekst, een grote font_size, width: 0 (de volledige contentbreedte), en alignment: "center".
Roep output_pdf aan met de document_id. Zonder file_path retourneert de server de PDF als base64 en vernietigt de sessie.

Hier is een minimaal argumentobject voor create_pdf:

{
  "page_size": "A4",
  "orientation": "portrait",
  "title": "Hello World",
  "author": "NextPDF Cookbook"
}

De respons bevat de document_id, het aantal pagina’s en de paginageometrie. Behandel de ID als een opaque waarde en leid er geen betekenis uit af.

Codevoorbeeld — Productie

Een client in productie controleert elke respons voordat die de volgende aanroep doet. Die hergebruikt een document_id nooit nadat output_pdf de sessie heeft vernietigd.

create_pdf — controleer of de respons een document_id bevat. Als de server een sessielimietfout retourneert, geef dan ongebruikte sessies vrij en probeer het opnieuw.
add_text (kop) — controleer of de respons een position retourneert.
add_text (ondertitel) — gebruik een kleinere font_size; de cursor gaat verder onder de kop.
output_pdf — lees het veld base64 en decodeer het naar bytes. De vlag destroyed bevestigt dat de sessie is verwijderd.

De uitvoer komt inline terug (base64-modus), dus er is geen bestandssysteemeffect en geen menselijke goedkeuringspoort. Zie HITL-risiconiveau.

Randgevallen en valkuilen

Vernietigde sessie. Nadat output_pdf wordt uitgevoerd met de standaardwaarde destroy: true, is de document_id niet langer geldig. Elke latere aanroep die deze gebruikt, retourneert een fout voor een onbekend document. Maak in plaats daarvan een nieuwe sessie.
Onbekend paginaformaat. De server weigert een page_size die hij niet herkent en retourneert een duidelijke fout. Gebruik een gedocumenteerd formaat (A3, A4, A5, A6, Letter, Legal, Tabloid).
Lege tekst. Een lege text produceert een vermelding met breedte nul, geen fout. Controleer uw invoer vóór de aanroep.
Sessielimiet. De in-memory opslag beperkt het aantal sessies dat tegelijk actief is. Geef sessies tijdig vrij met output_pdf.

Prestaties

Een pagina met alleen tekst wordt ruim binnen het paginabudget gerenderd, en de uitvoer is doorgaans 1–3 KB. Dit recipe gebruikt het reproduceerbaarheidsprofiel met dubbele rendering structural. De PDF bevat een trailer /ID en tijdstempels die van run tot run veranderen, dus een structurele (genormaliseerde) vergelijking is de nauwkeurigste keuze.

Beveiligingsnotities

Het base64-pad heeft geen bestandssysteemeffect. Bij bestandsuitvoer is dat effect er wel, en dat pad is afgeschermd. Zie het HITL-gedeelte. Behandel de geretourneerde base64 als documentinhoud, niet als een vertrouwd kanaal. Het gaat exact om de bytes die de tools hebben geproduceerd.

Conformiteit

Verklaring	Spec	Clausule	reference_id
Een transport verstuurt een verzoek en ontvangt een respons, onafhankelijk van het resultaat.	PSR-18	§p2
Pagina’s worden bereikt via de paginaboom van het document.	ISO 32000-2	§7.7.3

Dit recipe beschrijft hoe de server uitvoer produceert. Het doet geen uitspraak over profielconformiteit.

Commerciële context

Niet van toepassing — alle drie de tools zijn Core.

Beschikbaarheid van transporten

Transport	Beschikbaar	Notities
MCP (stdio)	Ja	Toolaanroepen worden toegewezen aan MCP `tools/call`.
REST	Ja	Elke tool is een REST-bewerking; het resultaat is de body van de respons.
gRPC	Ja	Elke tool is een unaire aanroep.

Het toolresultaat is voor alle transporten hetzelfde; alleen de framing verschilt. Een mislukt resultaat is nog steeds een normale respons, geen transportfout (PSR-18 §p2).

HITL-risiconiveau

De server plaatst elke toolaanroep op een risicoladder voor human-in-the-loop (HITL): Safe (0) → Caution (1) → Review (2) → Approval Required (3). create_pdf is Safe, en add_text is Caution. output_pdf is Approval Required, maar in base64-modus (geen file_path) wordt het verlaagd naar Review en draait het zonder menselijke bevestiging. Bij schrijven naar een bestand blijft het Approval Required. Zie output-approval en de naslag over HITL-risiconiveaus.

JSON-envelop van de bevestigingspoort

Dit recipe blijft in base64-modus, dus de bevestigingspoort retourneert de allow-envelop:

{ "allowed": true }

De challenge-envelop (allowed: false, met een challenge-string en een eenmalig token) is gedocumenteerd in output-approval.