Pro editie

Chart

In het kort

NextPDF Pro rendert staaf-, lijn- en taartdiagrammen rechtstreeks naar een PDF-pagina als vectorcontentoperatoren. Er is geen rasterisatiestap en geen afhankelijkheid van een headless browser, dus de uitvoer is deterministisch en reproduceerbaar.

Installatie

composer require nextpdf/pro:^3

Conceptueel overzicht

De Chart-module biedt drie native diagramrenderers. Elke renderer is een op zichzelf staande tekenprimitieve: deze rendert binnen een vast rechthoekig vak dat je aanlevert, zonder herverdeling, zonder containerbewustzijn en zonder lay-outonderhandeling. Jij plaatst het vak; de renderer vult het.

Staafdiagram — een verticaal staafdiagram met configureerbare staafkleur, askleur, staaftussenruimte en labellettergrootte.
Lijndiagram — een lijndiagram met één of meerdere series, met een kleur per serie, optionele datapuntmarkeringen, een optioneel raster en een configureerbare lijnbreedte.
Taartdiagram — een cirkeldiagram met automatische palettoewijzing, optionele percentagelabels en een optionele legenda.

Elke renderer volgt dezelfde vorm: een fromData(...)-fabriek, vloeiende with*()-configuratie en een render(ChartBox $box): string-aanroep die PDF-contentstreamoperatoren retourneert. De uitvoer is deterministisch — identieke invoer en configuratie produceren identieke operatoren, waardoor een document met diagrammen reproduceerbaar en veilig om te ondertekenen of te archiveren blijft.

Omdat de renderers vectoroperatoren uitzenden in plaats van afbeeldingen, blijven diagrammen scherp bij elke zoom en voegen ze geen rasterpayload toe aan het document.

Waarom het zo werkt

De dragende beslissing is om native PDF-vectoroperatoren uit te zenden in plaats van een afbeelding te rasteriseren of een headless browser aan te sturen. Die keuze maakt de uitvoer deterministisch: identieke gegevens en configuratie produceren altijd byte-identieke operatoren. Deterministische operatoren houden een document met diagrammen reproduceerbaar, en daarmee veilig om te ondertekenen of te archiveren. Door een externe renderer te vermijden verdwijnt ook een procesafhankelijkheid, zodat de doorvoer schaalt met datapunten in plaats van met de opstartkosten van een browser. Elke renderer verpakt zijn operatoren in een q/Q-paar voor de grafische status en herverdeelt nooit, waardoor deze voorspelbaar en goedkoop componeert.

Ontwerpachtergrond: Documentgeneratie op grote schaal.

API-oppervlak

composer require nextpdf/pro:^3

Het publieke Chart-oppervlak bestaat uit vijf klassen in NextPDF\Pro\Chart:

BarChart — fromData(), withBarColor(), withAxisColor(), withBarGap(), withFontSize(), render().
LineChart — create(), fromData(), addSeries(), withAxisColor(), withLineWidth(), withFontSize(), withDots(), withGrid(), render().
PieChart — fromData(), withColors(), withStrokeColor(), withFontSize(), withPercentages(), withLegend(), render().
ChartBox — plaatsingsrechthoek; fromUserSpace() converteert een gebruikersruimterechthoek met oorsprong linksboven naar de PDF-oorsprong linksonder; inset() voor opvulling.
ChartColor — rgb(), hex(), palette(), plus stroke/fill-operatoruitzenders.

Codevoorbeeld — Snelstart

use NextPDF\Pro\Chart\BarChart;
use NextPDF\Pro\Chart\ChartBox;

$box = ChartBox::fromUserSpace(72, 72, 400, 240, pageHeight: 842);
$stream = BarChart::fromData(['Q1', 'Q2', 'Q3', 'Q4'], [100, 200, 150, 300])
    ->render($box);
// $stream is appended to the target page content.

Codevoorbeeld — Productie

use NextPDF\Pro\Chart\ChartBox;
use NextPDF\Pro\Chart\ChartColor;
use NextPDF\Pro\Chart\LineChart;

$box = ChartBox::fromUserSpace(72, 72, 460, 260, pageHeight: 842)
    ->inset(8, 8, 8, 8);

$stream = LineChart::create(['Jan', 'Feb', 'Mar', 'Apr'])
    ->addSeries('Revenue', [120, 180, 150, 220], ChartColor::hex('#336699'))
    ->addSeries('Cost', [80, 90, 110, 130], ChartColor::palette(1))
    ->withGrid(true)
    ->withDots(true, 2.5)
    ->withLineWidth(1.2)
    ->render($box);

Randgevallen en valkuilen

Lege data retourneert een lege string in plaats van een exceptie te werpen, zodat een ontbrekende dataset niets rendert in plaats van de pagina kapot te maken.
Een taartdiagram met een totaal van nul of een negatief totaal retourneert een lege string.
Een lijnserie met één enkel punt tekent geen lijnsegment (één enkel punt heeft geen pad).
Een ChartBox met nulafmetingen rendert niets zinvols; geef het vak een grootte voordat je rendert.
Renderers knippen niet bij het vak; lever een vak aan dat past binnen de paginaregio die je voor ogen hebt.

Prestaties

Het renderen verloopt in één doorgang en lineair in het aantal datapunten. Er is geen rasterisatie, geen afbeeldingsbuffer en geen extern proces. De grootte van de uitgezonden operatorstring begrenst de geheugenkosten. Lijndiagrammen met meerdere series schalen lineair met het totale aantal punten over alle series.

Beveiligingsnotities

Diagramrenderers verwerken alleen numerieke gegevens en labelgegevens; ze evalueren of voeren invoer niet uit. De renderers zenden labels uit als PDF-tekstoperatoren en interpreteren ze nooit. De module logt geen diagramgegevens; de applicatie moet gevoelige labels opschonen voordat ze in een diagram worden geplaatst.

Conformiteit

Diagrammen worden niet door een externe standaard beheerst; de uitvoer is een PDF-contentstream die volgens de ISO 32000-2-contentstreamsemantiek in de pagina wordt gerenderd. Er is voor deze module geen symbologie- of cryptografisch conformiteitsoppervlak.

Publicatiegrens

Deze pagina documenteert uitsluitend extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespacepaden, hulpklassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.