Afbeeldingen insluiten via NextPDF Connect

In het kort

Sluit via NextPDF Connect een afbeelding in een Portable Document Format-bestand (PDF) in. Gebruik als bron een bestandspad dat de server kan lezen of een inline base64-data-URI. Je gebruikt create_pdf, add_image en output_pdf — allemaal Core-tools. NextPDF tekent de afbeelding als een image-XObject, gerenderd door de operator Do (ISO 32000-2 §8.9).

Installeren

composer require nextpdf/server

Koppel een transport. NextPDF ondersteunt de rasterformaten PNG, JPEG en GIF.

Conceptueel overzicht

add_image krijgt een source en verwerkt die in deze vaste volgorde:

Data-URI — een tekenreeks die begint met data:. NextPDF leest het Multipurpose Internet Mail Extensions-type (MIME) uit, decodeert de base64-payload naar een tijdelijk bestand, sluit dat in en verwijdert vervolgens het tijdelijke bestand.
Onbewerkte base64 — NextPDF decodeert een lange base64-tekenreeks en behandelt deze als PNG.
Bestandspad — NextPDF behandelt alles wat overblijft als een bestandssysteempad dat het serverproces moet kunnen lezen.

De afbeelding verschijnt op x/y in gebruikerseenheden (standaard millimeters). Als je alleen width opgeeft, berekent NextPDF de hoogte zodat de beeldverhouding behouden blijft. Als je zowel width als height opgeeft, schaalt NextPDF de afbeelding exact naar die afmetingen. Het ingesloten object is een extern object dat in de pagina-inhoud wordt gerenderd (ISO 32000-2 §8.8).

API-oppervlak

Tool	Rol	Risicocategorie
`create_pdf`	Een sessie openen	Veilig
`add_image`	Een afbeelding insluiten vanuit een pad of data-URI	Voorzichtig
`output_pdf`	De PDF renderen en retourneren	Goedkeuring vereist / Beoordeling (base64)

De toolcatalogus is de gezaghebbende bron. Welke tools voor je beschikbaar zijn, hangt af van het geïnstalleerde niveau.

Codevoorbeeld — snelstart

create_pdf (A4 staand, titel) → document_id.
add_image met source ingesteld op een absoluut pad, x, y, width.
add_image met source ingesteld op een data:image/png;base64,...-URI en expliciete width en height.
output_pdf → base64.

Codevoorbeeld — productie

Gebruik een data-URI voor een afbeelding die de host in het geheugen heeft gegenereerd, zoals een grafiekweergave of een schermafbeelding. Gebruik een bestandspad voor een asset die al op de server staat. Gebruik altijd absolute paden. Een relatief pad wordt verwerkt ten opzichte van de werkmap van de server, en dat is meestal niet de werkmap van de host. Controleer voordat je verdergaat of de add_image-respons meldt dat de afbeelding op de verwachte pagina staat.

Randgevallen en valkuilen

Pad niet gevonden. Een ontbrekend bestandspad levert een image-not-found-fout op.
Niet-ondersteund formaat. NextPDF weigert SVG, BMP en WebP. Converteer de afbeelding eerst.
Onjuist gevormde base64 / data-URI. Een onjuiste payload of een data-URI zonder kommascheidingsteken levert een decodeerfout op.
Te grote afbeelding. Een afbeelding die groter is dan de pagina, wordt aan de rand bijgesneden, niet geweigerd. Bereken width/height ten opzichte van de pagina minus de marges (A4 staand is 210×297 mm).

Prestaties

De grootte van de uitvoer schaalt mee met de afbeeldingsinhoud. Twee kleine afbeeldingen komen doorgaans uit op 10–50 KB. Het budget voor het insluiten van afbeeldingen is ruimer dan het budget voor alleen tekst. Deze pagina gebruikt het profiel structural.

Beveiligingsopmerkingen

In bestandspadmodus leest NextPDF uit het bestandssysteem van de server met de rechten van het serverproces. Beperk welke paden de host mag doorgeven. Laat niet-vertrouwde aanroepers source niet naar willekeurige serverbestanden verwijzen. In base64-modus worden de bytes inline meegestuurd, waardoor serverpaden niet worden blootgesteld.

Conformiteit

Bewering	Specificatie	Clausule	reference_id
Een afbeelding is een image-XObject dat wordt gerenderd door `Do`.	ISO 32000-2	§8.9
Afbeeldingen zijn externe objecten die in de pagina-inhoud worden gerenderd.	ISO 32000-2	§8.8

Commerciële context

Niet van toepassing — alle tools zijn opgenomen in Core.

Beschikbaarheid van transport

Transport	Beschikbaar	Opmerkingen
MCP (stdio)	Ja	Grote base64-payloads vergroten het stdio-frame.
REST	Ja	Gebruik bij voorkeur multipart of een serverpad voor grote assets.
gRPC	Ja	Unary; berichtgroottelimieten gelden voor inline base64.

HITL-risicocategorie

create_pdf is Veilig, add_image is Voorzichtig en output_pdf is Goedkeuring vereist — in base64-modus verlaagd naar Beoordeling. Lezen in padmodus gebeurt aan de serverzijde en wordt niet apart afgeschermd; beperk dit daarom in de policylaag (HITL-risicocategorieën).

JSON-envelop van de bevestigingsgate

Base64-uitvoer hier:

{ "allowed": true }