Pro editie

Chart — Diepe referentie

In één oogopslag

Deze pagina is de referentie op contractniveau voor de NextPDF Pro Chart-module. Het oppervlak bestaat uit vijf publieke classes in NextPDF\Pro\Chart: de renderers BarChart, LineChart en PieChart, de plaatsingsrechthoek ChartBox en het value-object ChartColor. Elke renderer is een drawing-primitive. Een statische factory creëert die, fluent with*()-aanroepen configureren die, en render(ChartBox $box): string retourneert PDF-content-stream-operatoren voor de aangeleverde rechthoek. De uitvoer is vector-only en deterministisch: identieke invoer en configuratie leveren identieke bytes op. Gedegenereerde invoer retourneert een lege string in plaats van te werpen, zodat een chart nooit de omringende pagina breekt. De taakgerichte weergave vind je op de capability-pagina.

Beschikbaarheid en licentie

Deze capability wordt geleverd in NextPDF Pro (nextpdf/pro) en activeert met een licentie-envelope op Pro-niveau. Een deployment zonder die entitlement laadt de classes van de capability niet. Vergelijk edities en vraag een licentie aan.

Chart-renderers zijn capability-gelicentieerd onder de chart.*-capabilityfamilie. Wanneer de capability niet gelicentieerd is, zijn de chart-renderers niet beschikbaar.

Publiek API-oppervlak

composer require nextpdf/pro:^3

Symbool	Parameters	Standaardgedrag	Retourneert	Werpt of faalt met	Notities
`BarChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Waarden worden naar float gecast	`self`	Werpt niet	Enige constructiepad; de constructor is private
`BarChart::withBarColor()`	`ChartColor $color`	Bar-fill; standaard is palette-entry 0	`self`	Werpt niet	Fluent; muteert de receiver
`BarChart::withAxisColor()`	`ChartColor $color`	Axis-stroke; standaard `#333333`	`self`	Werpt niet	—
`BarChart::withBarGap()`	`float $gap`	Gap als fractie van de slot-breedte; standaard `0.2`	`self`	Werpt niet	Geclampt naar `0.0`–`0.9`; out-of-range-invoer wordt geclampt, niet afgewezen
`BarChart::withFontSize()`	`float $size`	Label-fontgrootte in punten; standaard `7.0`	`self`	Werpt niet	—
`BarChart::render()`	`ChartBox $box`	Assen, bars, categorielabels, vijf value-ticks	`string`-operatoren	Werpt niet; lege data retourneert `''`	Een niet-positief maximum schaalt tegen `1.0`
`LineChart::create()`	`list<string> $labels`	Chart zonder series	`self`	Werpt niet	De constructor is private
`LineChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Voegt één naamloze series toe	`self`	Werpt niet	Single-series-gemak
`LineChart::addSeries()`	`string $name`, `list<int\|float> $values`, `?ChartColor $color = null`	Een `null`-kleur wordt automatisch toegewezen vanuit de palette op basis van de series-index	`self`	Werpt niet	De series-naam is gereserveerd voor legend-gebruik
`LineChart::withAxisColor()`	`ChartColor $color`	Axis-stroke; standaard `#333333`	`self`	Werpt niet	—
`LineChart::withLineWidth()`	`float $width`	Series-stroke-breedte; standaard `1.5`	`self`	Werpt niet	—
`LineChart::withFontSize()`	`float $size`	Label-fontgrootte; standaard `7.0`	`self`	Werpt niet	—
`LineChart::withDots()`	`bool $show`, `float $radius = 2.5`	Data-point-markers; standaard aan	`self`	Werpt niet	Markers worden getekend als Bezier-benaderde cirkels
`LineChart::withGrid()`	`bool $show`	Horizontale kwartiel-grid; standaard aan	`self`	Werpt niet	—
`LineChart::render()`	`ChartBox $box`	Grid, assen, één path per series, labels	`string`-operatoren	Werpt niet; geen series retourneert `''`	Een series korter dan twee punten tekent geen path
`PieChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Proporties berekend uit de som van de waarden	`self`	Werpt niet	De constructor is private
`PieChart::withColors()`	`list<ChartColor> $colors`	Eén kleur per slice, op volgorde	`self`	Werpt niet	Ontbrekende entries vallen terug op de palette
`PieChart::withStrokeColor()`	`ChartColor $color`	Slice-outline; standaard wit	`self`	Werpt niet	—
`PieChart::withFontSize()`	`float $size`	Label-fontgrootte; standaard `7.0`	`self`	Werpt niet	—
`PieChart::withPercentages()`	`bool $show`	Percentage-labels; standaard aan	`self`	Werpt niet	Labels worden alleen gerenderd op slices die meer dan 15 graden bestrijken
`PieChart::withLegend()`	`bool $show`	Legend aan de rechterkant; standaard aan	`self`	Werpt niet	De legend reserveert 80 punten box-breedte
`PieChart::render()`	`ChartBox $box`	Sectoren, optionele labels, optionele legend	`string`-operatoren	Werpt niet; lege data of een totaal op of onder nul retourneert `''`	Bogen splitsen in Bezier-segmenten van maximaal 90 graden
`ChartBox::__construct()`	`float $x`, `float $y`, `float $width`, `float $height`	PDF-oorsprong linksonder, in punten	—	Werpt niet	`final readonly`; dimensies worden niet gevalideerd
`ChartBox::fromUserSpace()`	`float $x`, `float $y`, `float $width`, `float $height`, `float $pageHeight`	Klapt een rechthoek met oorsprong linksboven om naar PDF-coördinaten	`self`	Werpt niet	—
`ChartBox::right()`	geen	`x + width`	`float`	Werpt niet	Methode, geen property
`ChartBox::top()`	geen	`y + height`	`float`	Werpt niet	Methode, geen property
`ChartBox::inset()`	`float $left`, `float $bottom`, `float $right`, `float $top`	Sub-box verkleind met de gegeven insets	`self`	Werpt niet	Te grote insets leveren negatieve dimensies op; niet gevalideerd
`ChartColor::__construct()`	`float $r`, `float $g`, `float $b`, elk `0.0`–`1.0`	—	—	Werpt niet	`final readonly`; componenten worden niet geclampt
`ChartColor::rgb()`	`int $r`, `int $g`, `int $b`, elk `0`–`255`	Schaalt componenten naar `0.0`–`1.0`	`self`	Werpt niet	—
`ChartColor::hex()`	`string $hex`	Accepteert `#`-geprefixte of kale zescijferige hex	`self`	Werpt niet	Ontbrekende achterliggende cijfers decoderen als nul
`ChartColor::palette()`	`int $index`	Ingebouwde 12-kleuren-palette	`self`	`TypeError` bij een negatieve index	Niet-negatieve indexen wrappen modulo 12
`ChartColor::strokeOperator()`	geen	Stroke-kleuroperator (`RG`), drie decimalen	`string`	Werpt niet	Methode, geen property
`ChartColor::fillOperator()`	geen	Fill-kleuroperator (`rg`), drie decimalen	`string`	Werpt niet	Methode, geen property

Entry-point-signaturen

public static function fromData(array $labels, array $values): self
public function withBarColor(ChartColor $color): self
public function withAxisColor(ChartColor $color): self
public function withBarGap(float $gap): self
public function withFontSize(float $size): self
public function render(ChartBox $box): string

public static function create(array $labels): self
public static function fromData(array $labels, array $values): self
public function addSeries(string $name, array $values, ?ChartColor $color = null): self
public function withAxisColor(ChartColor $color): self
public function withLineWidth(float $width): self
public function withFontSize(float $size): self
public function withDots(bool $show, float $radius = 2.5): self
public function withGrid(bool $show): self
public function render(ChartBox $box): string

public static function fromData(array $labels, array $values): self
public function withColors(array $colors): self
public function withStrokeColor(ChartColor $color): self
public function withFontSize(float $size): self
public function withPercentages(bool $show): self
public function withLegend(bool $show): self
public function render(ChartBox $box): string

public function __construct(
    public float $x,
    public float $y,
    public float $width,
    public float $height,
)

public static function fromUserSpace(
    float $x,
    float $y,
    float $width,
    float $height,
    float $pageHeight,
): self

public function right(): float
public function top(): float
public function inset(float $left, float $bottom, float $right, float $top): self

public static function rgb(int $r, int $g, int $b): self
public static function hex(string $hex): self
public static function palette(int $index): self
public function strokeOperator(): string
public function fillOperator(): string

Gedragscontract

Gemeenschappelijke renderer-vorm

Alle drie de renderers volgen één lifecycle: een statische factory, fluent configuratie, één render()-aanroep. Configuratiemethoden muteren de receiver en retourneren die; renderers zijn geen immutable value-objecten. render() leest de configuratie zonder die te muteren, zodat één geconfigureerde renderer in meerdere boxes kan renderen. Elke render wikkelt de uitvoer in een save/restore-graphics-state-paar, zodat chart-state nooit naar de pagina lekt. Coördinaten worden met twee decimalen uitgezonden en kleurcomponenten met drie, wat de uitvoer byte-stabiel houdt. Tekst wordt gerenderd via de font-resourcenaam /ChartFont op de geconfigureerde grootte; de aanroeper registreert een font onder die naam in de resource-dictionary van de doelpagina. Label-strings escapen backslash en haakjes voordat ze in string-operanden terechtkomen. Renderers voeren geen reflow, geen clipping en geen container-onderhandeling uit: de aanroeper is eigenaar van de plaatsing.

Schaling en layout

Bar- en line-charts reserveren een vaste plot-inset binnen de box: 40 punten links, 20 onder, 10 rechts, 10 boven. Het resterende plot-gebied schaalt waarden lineair tegen het series-maximum. Een maximum van nul of lager schaalt in plaats daarvan tegen 1.0, zodat all-zero-data assen rendert met vlakke inhoud in plaats van te delen door nul. Beide tekenen X- en Y-assen op 0.5-punt-breedte en vijf value-ticks op kwartielposities. Bar-charts formatteren tick-waarden met K- en M-suffixen boven duizend en één miljoen; line-charts printen kale getallen.

Staafdiagram

Elke waarde bezet een gelijke slot over de plot-breedte. De bar vult de slot minus de geconfigureerde gap-fractie en wordt in de slot gecentreerd. Categorielabels worden 12 punten onder het plot-gebied getekend.

Lijndiagram

De grid tekent, indien ingeschakeld, vier horizontale kwartiellijnen in lichtgrijs (0.85 0.85 0.85 RG) onder de assen en series. Elke series tekent één polyline door zijn punten, over de volledige plot-breedte. Optionele markers worden getekend als Bezier-cirkels van vier segmenten op elk data-point. Series-kleuren vallen standaard terug op opeenvolgende palette-entries in invoegvolgorde.

Cirkeldiagram

Slices worden uitgelegd in data-volgorde, beginnend bij de positieve X-as en tegen de klok in bestrijkend. Elk sector-path sluit en schildert met gecombineerde fill en stroke (h B); bogen splitsen in Bezier-segmenten van maximaal 90 graden. Percentage-labels ronden af op hele procenten en worden alleen gerenderd op slices die meer dan 15 graden bestrijken. De legend reserveert, indien ingeschakeld, 80 punten box-breedte aan de rechterkant en rendert een swatch van 8 punten per entry op een lijnhoogte van 12 punten. De radius is de helft van de kleinste van de resterende breedte en de box-hoogte, minus een marge van 10 punten.

Plaatsings- en kleur-value-objecten

ChartBox is een immutable rechthoek in PDF-user-units (punten) met een oorsprong linksonder. ChartBox::fromUserSpace() converteert een rechthoek met oorsprong linksboven door om te klappen tegen de aangeleverde paginahoogte. inset() retourneert een nieuwe, kleinere box; right() en top() zijn accessor-methoden. ChartColor is zelfstandig en is niet afhankelijk van de Core-kleur-classes. De palette met 12 entries wijst series- en slice-kleuren toe wanneer de aanroeper er geen aanlevert.

Support-matrix (evidence-backed)

Een chart-type of -feature verdient alleen Verified wanneer een pro/tests/**-fixture die oefent. Geen externe standaard regelt charts, dus het bewijs is gedragsdekking op unit-niveau.

Chart-type / feature	Status	Bewijs (testpad)	Vertrouwen	Notities
Bar chart — render, axes, bar-rectangles, gap-clamping, empty/all-zero-data, K/M-value-formatting	Verified	`pro/tests/Unit/Chart/BarChartTest.php`; `BarChartArithmeticCoverageTest.php`; `BarChartBoundaryCoverageTest.php`	high	Graphics-state-wrap, axis-lijnen, bar-hoogteproporties, tick-count en formatting-grenzen geasserteerd.
Line chart — single- en multi-series, line path, axes, dots, grid, single-point	Verified	`pro/tests/Unit/Chart/LineChartTest.php`; `LineChartCoverageTest.php`; `LineChartArithmeticCoverageTest.php`; `LineChartTypeCastCoverageTest.php`	high	Multi-series, single-point no-line, empty-series, grid- en dot-paden gedekt.
Pie chart — sectors, Bezier-segmentatie, percentages, legend, zero/negative-total	Verified	`pro/tests/Unit/Chart/PieChartTest.php`; `PieChartArithmeticCoverageTest.php`; `PieChartBoundaryCoverageTest.php`	high	Sector-paden, segmentaantallen per sweep, de 15-graden-label-drempel, legend-geometrie en empty-string-gedrag gedekt.
`ChartBox` — coördinaatconversie (user-space naar PDF), page top/bottom, zero dims, inset	Verified	`pro/tests/Unit/Chart/ChartBoxTest.php`	high	Top-left-origin- naar bottom-left-origin-conversie bij paginatop, -bodem en zero-dimension-randen.
`ChartColor` — RGB-scaling, hex-parsing, palette, stroke/fill-operators	Verified	`pro/tests/Unit/Chart/ChartColorTest.php`	high	0–255- naar 0–1-scaling, `#`-geprefixte en kale hex, gemengde casing, palette-wrap-around na 12 entries.
Cross-renderer-regressiehardening	Verified	`pro/tests/Unit/Chart/ChartCoverageTest.php`	high	Gedeelde regressiesuite over de drie renderers plus value-formatting-rekenwerk.
Chart-types buiten bar/line/pie (area, scatter, stacked, donut, etc.)	Not supported	—	high	Er wordt geen renderer geleverd. Het module-oppervlak is precies bar, line, pie. Eerlijk gesteld: dit is niet “elk chart-type”.

Eerlijke telling: Verified 6 rijen, Claimed 0, Not supported 1 (elk chart-type anders dan bar, line, pie).

Randgevallen en faalmodi

Geen renderer werpt op data. Gedegenereerde invoer degradeert naar een lege string: lege bar- of line-data, een lege series-lijst en een pie-totaal op of onder nul retourneren allemaal ''.
Een line-series met minder dan twee punten tekent geen path en geen markers; assen en labels worden nog steeds gerenderd.
Negatieve bar-waarden worden niet afgewezen; de bar-rechthoek strekt zich uit onder de X-as.
Label- en waarde-aantallen worden niet onderling gevalideerd. De aanroeper levert lijsten van overeenkomende lengte aan.
Een ChartBox met nul of negatieve dimensies wordt geaccepteerd en produceert gedegenereerde uitvoer; aanroepers moeten de box dimensioneren.
Renderers clippen niet. Een te grote chart, zijn categorielabels onder de plot of een lange legend kunnen over de bedoelde paginaregio heen lopen.
Een pagina zonder font onder de chart-font-resourcenaam laat text-operatoren achter die naar een ongedefinieerde resource verwijzen; het viewer-gedrag is dan ongedefinieerd.
ChartColor::hex() voert geen validatie uit; invoer korter dan zes cijfers decodeert ontbrekende componenten als nul. ChartColor::palette() faalt met TypeError bij een negatieve index, omdat PHP’s negatieve modulo geen palette-key oplost.
De module voert geen cryptografie uit; de FIPS-modus heeft geen chart-specifiek gedrag.

Conformiteit

De Chart-module zendt PDF-content-stream-operatoren uit. Geen externe chart-, symbologie- of cryptografische standaard regelt de uitvoer, dus het enige conformiteitsoppervlak is de uitgezonden operator-stream.

Claim	Standaard	Clausule
Uitgezonden graphics volgen het content-stream-operatormodel; de uitvoer nestelt binnen een opgeslagen en herstelde graphics-state.	ISO 32000-2	§8.1
Bars, lines, sectoren en markers zijn path-objecten: de constructie begint met `m` of `re` en eindigt met een path-painting-operator.	ISO 32000-2	§8.5.2
Labels worden gerenderd als text-objecten: de positie wordt vastgesteld na `BT`, en glyphs worden geschilderd met de `Tj`-text-showing-operator.	ISO 32000-2	§9.2.2, §9.4.3

Alle clausules zijn geparafraseerd; deze pagina reproduceert geen normatieve tekst. Dit zijn capability-verklaringen, geen certificeringen; NextPDF houdt geen certificering en verleent er geen. Correcte rendering van de stream hangt ook af van een welgevormd omvattend document, wat de verantwoordelijkheid van de document-schrijver is.

Ontwikkelingsnotities

Alle vijf classes dragen @since 1.9.0 en zijn actueel in nextpdf/pro 3.1.0.
De module is zelfstandig: renderers zijn alleen afhankelijk van ChartBox en ChartColor, zonder Core-koppeling.
Deterministische uitvoer houdt charted documenten reproduceerbaar, diff-stabiel en veilig om te signen of te archiveren.
Registreer eenmaal per pagina die charts host een font onder de chart-font-resourcenaam.
Hergebruik een geconfigureerde renderer vrij over boxes; render() voert geen state-mutatie uit.
Testbewijs leeft onder pro/tests/Unit/Chart/; de support-matrix verankert elke Verified-rij aan zijn suite.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helper-classes, mechanisme-tabellen, runbook-bestandsnamen en ticket-prefixen vallen buiten scope.

Zie ook

Chart (capability) — taakgericht overzicht, installatie en codevoorbeelden.
Barcode — Diepe referentie — het verwante Pro-drawing-oppervlak met zijn eigen evidence-backed support-matrix.