Pro Edition

Chart — Ausführliche Referenz

Auf einen Blick

Diese Seite ist die Referenz auf Vertragsebene für das NextPDF Pro Chart-Modul. Die Oberfläche besteht aus fünf öffentlichen Klassen in NextPDF\Pro\Chart: den Renderern BarChart, LineChart und PieChart, dem Platzierungsrechteck ChartBox und dem Wertobjekt ChartColor. Jeder Renderer ist ein Zeichenprimitiv. Eine statische Factory erzeugt ihn, fluente with*()-Aufrufe konfigurieren ihn, und render(ChartBox $box): string liefert PDF-Content-Stream-Operatoren für das übergebene Rechteck zurück. Die Ausgabe ist rein vektorbasiert und deterministisch: identische Eingabe und Konfiguration erzeugen identische Bytes. Degenerierte Eingaben liefern eine leere Zeichenkette zurück, statt eine Ausnahme auszulösen, sodass ein Chart die umgebende Seite nie beschädigt. Die aufgabenorientierte Sicht finden Sie auf der Capability-Seite.

Verfügbarkeit & Lizenzierung

Diese Capability ist in NextPDF Pro (nextpdf/pro) enthalten und wird mit einem Lizenz-Envelope der Pro-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Capability nicht. Editionen vergleichen und eine Lizenz erwerben.

Die Chart-Renderer sind capability-lizenziert unter der Capability-Familie chart.*. Wenn die Capability nicht lizenziert ist, sind die Chart-Renderer nicht verfügbar.

Öffentliche API-Oberfläche

composer require nextpdf/pro:^3

Symbol	Parameter	Standardverhalten	Rückgabe	Löst aus oder scheitert mit	Hinweise
`BarChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Werte werden zu float gecastet	`self`	Löst keine Ausnahme aus	Einziger Konstruktionsweg; der Konstruktor ist privat
`BarChart::withBarColor()`	`ChartColor $color`	Balkenfüllung; Standard ist Paletteneintrag 0	`self`	Löst keine Ausnahme aus	Fluent; verändert den Empfänger
`BarChart::withAxisColor()`	`ChartColor $color`	Achsenkontur; Standard `#333333`	`self`	Löst keine Ausnahme aus	—
`BarChart::withBarGap()`	`float $gap`	Abstand als Anteil der Slotbreite; Standard `0.2`	`self`	Löst keine Ausnahme aus	Auf `0.0`–`0.9` begrenzt; Eingaben außerhalb des Bereichs werden begrenzt, nicht abgelehnt
`BarChart::withFontSize()`	`float $size`	Schriftgröße der Beschriftung in Punkt; Standard `7.0`	`self`	Löst keine Ausnahme aus	—
`BarChart::render()`	`ChartBox $box`	Achsen, Balken, Kategoriebeschriftungen, fünf Werteskalenmarkierungen	`string`-Operatoren	Löst keine Ausnahme aus; leere Daten liefern `''` zurück	Ein nicht positives Maximum wird gegen `1.0` skaliert
`LineChart::create()`	`list<string> $labels`	Chart ohne Serien	`self`	Löst keine Ausnahme aus	Der Konstruktor ist privat
`LineChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Fügt eine unbenannte Serie hinzu	`self`	Löst keine Ausnahme aus	Komfortmethode für eine einzelne Serie
`LineChart::addSeries()`	`string $name`, `list<int\|float> $values`, `?ChartColor $color = null`	Eine `null`-Farbe wird automatisch anhand des Serienindex aus der Palette zugewiesen	`self`	Löst keine Ausnahme aus	Der Serienname ist für die Verwendung in der Legende reserviert
`LineChart::withAxisColor()`	`ChartColor $color`	Achsenkontur; Standard `#333333`	`self`	Löst keine Ausnahme aus	—
`LineChart::withLineWidth()`	`float $width`	Konturbreite der Serie; Standard `1.5`	`self`	Löst keine Ausnahme aus	—
`LineChart::withFontSize()`	`float $size`	Schriftgröße der Beschriftung; Standard `7.0`	`self`	Löst keine Ausnahme aus	—
`LineChart::withDots()`	`bool $show`, `float $radius = 2.5`	Datenpunktmarker; standardmäßig aktiviert	`self`	Löst keine Ausnahme aus	Marker werden als Bézier-approximierte Kreise gezeichnet
`LineChart::withGrid()`	`bool $show`	Horizontales Quartilraster; standardmäßig aktiviert	`self`	Löst keine Ausnahme aus	—
`LineChart::render()`	`ChartBox $box`	Raster, Achsen, ein Pfad je Serie, Beschriftungen	`string`-Operatoren	Löst keine Ausnahme aus; ohne Serien wird `''` zurückgegeben	Eine Serie mit weniger als zwei Punkten zeichnet keinen Pfad
`PieChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Anteile werden aus der Wertesumme berechnet	`self`	Löst keine Ausnahme aus	Der Konstruktor ist privat
`PieChart::withColors()`	`list<ChartColor> $colors`	Eine Farbe je Segment, in Reihenfolge	`self`	Löst keine Ausnahme aus	Fehlende Einträge greifen auf die Palette zurück
`PieChart::withStrokeColor()`	`ChartColor $color`	Segmentkontur; Standard Weiß	`self`	Löst keine Ausnahme aus	—
`PieChart::withFontSize()`	`float $size`	Schriftgröße der Beschriftung; Standard `7.0`	`self`	Löst keine Ausnahme aus	—
`PieChart::withPercentages()`	`bool $show`	Prozentbeschriftungen; standardmäßig aktiviert	`self`	Löst keine Ausnahme aus	Beschriftungen werden nur auf Segmenten dargestellt, die mehr als 15 Grad überstreichen
`PieChart::withLegend()`	`bool $show`	Legende auf der rechten Seite; standardmäßig aktiviert	`self`	Löst keine Ausnahme aus	Die Legende reserviert 80 Punkt Boxbreite
`PieChart::render()`	`ChartBox $box`	Sektoren, optionale Beschriftungen, optionale Legende	`string`-Operatoren	Löst keine Ausnahme aus; leere Daten oder eine Summe von null oder darunter liefern `''` zurück	Bögen werden in Bézier-Segmente von höchstens 90 Grad aufgeteilt
`ChartBox::__construct()`	`float $x`, `float $y`, `float $width`, `float $height`	PDF-Ursprung unten links, in Punkt	—	Löst keine Ausnahme aus	`final readonly`; Abmessungen werden nicht validiert
`ChartBox::fromUserSpace()`	`float $x`, `float $y`, `float $width`, `float $height`, `float $pageHeight`	Spiegelt ein Rechteck mit Ursprung oben links in PDF-Koordinaten	`self`	Löst keine Ausnahme aus	—
`ChartBox::right()`	keine	`x + width`	`float`	Löst keine Ausnahme aus	Methode, keine Eigenschaft
`ChartBox::top()`	keine	`y + height`	`float`	Löst keine Ausnahme aus	Methode, keine Eigenschaft
`ChartBox::inset()`	`float $left`, `float $bottom`, `float $right`, `float $top`	Teilbox, um die angegebenen Insets verkleinert	`self`	Löst keine Ausnahme aus	Übergroße Insets ergeben negative Abmessungen; nicht validiert
`ChartColor::__construct()`	`float $r`, `float $g`, `float $b`, jeweils `0.0`–`1.0`	—	—	Löst keine Ausnahme aus	`final readonly`; Komponenten werden nicht begrenzt
`ChartColor::rgb()`	`int $r`, `int $g`, `int $b`, jeweils `0`–`255`	Skaliert Komponenten auf `0.0`–`1.0`	`self`	Löst keine Ausnahme aus	—
`ChartColor::hex()`	`string $hex`	Akzeptiert Hex mit `#`-Präfix oder bloße sechsstellige Hex-Werte	`self`	Löst keine Ausnahme aus	Fehlende nachfolgende Ziffern werden als Null decodiert
`ChartColor::palette()`	`int $index`	Integrierte 12-Farben-Palette	`self`	`TypeError` bei negativem Index	Nicht negative Indizes laufen modulo 12 um
`ChartColor::strokeOperator()`	keine	Konturfarboperator (`RG`), drei Nachkommastellen	`string`	Löst keine Ausnahme aus	Methode, keine Eigenschaft
`ChartColor::fillOperator()`	keine	Füllfarboperator (`rg`), drei Nachkommastellen	`string`	Löst keine Ausnahme aus	Methode, keine Eigenschaft

Signaturen der Einstiegspunkte

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

Verhaltensvertrag

Gemeinsame Renderer-Struktur

Alle drei Renderer folgen einem Lebenszyklus: eine statische Factory, fluente Konfiguration, ein render()-Aufruf. Konfigurationsmethoden verändern den Empfänger und geben ihn zurück; Renderer sind keine unveränderlichen Wertobjekte. render() liest die Konfiguration, ohne sie zu verändern, sodass ein konfigurierter Renderer in mehrere Boxen rendern kann. Jeder Rendervorgang umschließt seine Ausgabe mit einem Speichern/Wiederherstellen-Paar des Grafikzustands, sodass Chart-Zustand nie in die Seite überläuft. Koordinaten werden mit zwei Nachkommastellen und Farbkomponenten mit drei ausgegeben, was die Ausgabe bytestabil hält. Text wird über den Font-Ressourcennamen /ChartFont in der konfigurierten Größe dargestellt; der Aufrufer registriert einen Font unter diesem Namen im Ressourcen-Dictionary der Zielseite. Beschriftungszeichenketten escapen Backslash und Klammern, bevor sie in String-Operanden eingehen. Renderer führen keinen Umbruch, kein Clipping und keine Container-Aushandlung durch: die Platzierung liegt beim Aufrufer.

Skalierung und Layout

Balken- und Liniendiagramme reservieren einen festen Plot-Inset innerhalb der Box: 40 Punkt links, 20 unten, 10 rechts, 10 oben. Der verbleibende Plot-Bereich skaliert Werte linear gegen das Serienmaximum. Ein Maximum von null oder darunter wird stattdessen gegen 1.0 skaliert, sodass reine Nulldaten Achsen mit flachem Inhalt darstellen, statt durch null zu teilen. Beide zeichnen X- und Y-Achsen mit 0.5 Punkt Breite und fünf Werteskalenmarkierungen an Quartilpositionen. Balkendiagramme formatieren Skalenwerte mit den Suffixen K und M oberhalb von eintausend und einer Million; Liniendiagramme geben schlichte Zahlen aus.

Balkendiagramm

Jeder Wert belegt einen gleich großen Slot über die Plot-Breite. Der Balken füllt den Slot abzüglich des konfigurierten Abstandsanteils und wird im Slot zentriert. Kategoriebeschriftungen werden 12 Punkt unterhalb des Plot-Bereichs gezeichnet.

Liniendiagramm

Das Raster zeichnet, sofern aktiviert, vier horizontale Quartillinien in Hellgrau (0.85 0.85 0.85 RG) unterhalb der Achsen und Serien. Jede Serie zeichnet einen Polygonzug durch ihre Punkte, der die gesamte Plot-Breite überspannt. Optionale Marker werden als Bézier-Kreise aus vier Segmenten an jedem Datenpunkt gezeichnet. Serienfarben verwenden standardmäßig aufeinanderfolgende Paletteneinträge in Einfügereihenfolge.

Kreisdiagramm

Segmente werden in Datenreihenfolge angeordnet, beginnend an der positiven X-Achse und gegen den Uhrzeigersinn verlaufend. Jeder Sektorpfad wird geschlossen und mit kombinierter Füllung und Kontur (h B) gezeichnet; Bögen werden in Bézier-Segmente von höchstens 90 Grad aufgeteilt. Prozentbeschriftungen werden auf ganze Prozent gerundet und nur auf Segmenten dargestellt, die mehr als 15 Grad überstreichen. Die Legende reserviert, sofern aktiviert, 80 Punkt Boxbreite auf der rechten Seite und rendert eine 8-Punkt-Farbfläche je Eintrag bei einer Zeilenhöhe von 12 Punkt. Der Radius ist die Hälfte des kleineren Werts aus verbleibender Breite und Boxhöhe, abzüglich eines Rands von 10 Punkt.

Platzierungs- und Farbwertobjekte

ChartBox ist ein unveränderliches Rechteck in PDF-Benutzereinheiten (Punkt) mit Ursprung unten links. ChartBox::fromUserSpace() konvertiert ein Rechteck mit Ursprung oben links, indem es gegen die übergebene Seitenhöhe gespiegelt wird. inset() gibt eine neue, kleinere Box zurück; right() und top() sind Zugriffsmethoden. ChartColor ist eigenständig und hängt nicht von den Farbklassen von Core ab. Seine Palette mit 12 Einträgen weist Serien- und Segmentfarben zu, wenn der Aufrufer keine liefert.

Support-Matrix (belegbasiert)

Ein Chart-Typ oder ein Feature erhält Verifiziert nur dann, wenn eine pro/tests/**-Fixture ihn ausübt. Kein externer Standard regelt Charts, daher ist der Nachweis eine Verhaltensabdeckung auf Unit-Ebene.

Chart-Typ / Feature	Status	Nachweis (Testpfad)	Konfidenz	Hinweise
Balkendiagramm — Rendern, Achsen, Balkenrechtecke, Abstandsbegrenzung, leere/reine Nulldaten, K/M-Werteformatierung	Verifiziert	`pro/tests/Unit/Chart/BarChartTest.php`; `BarChartArithmeticCoverageTest.php`; `BarChartBoundaryCoverageTest.php`	hoch	Grafikzustands-Umschließung, Achsenlinien, Balkenhöhenverhältnisse, Anzahl der Skalenmarkierungen und Formatierungsgrenzen abgesichert.
Liniendiagramm — Einzel- und Mehrfachserien, Linienpfad, Achsen, Punkte, Raster, Einzelpunkt	Verifiziert	`pro/tests/Unit/Chart/LineChartTest.php`; `LineChartCoverageTest.php`; `LineChartArithmeticCoverageTest.php`; `LineChartTypeCastCoverageTest.php`	hoch	Mehrfachserien, Einzelpunkt ohne Linie, leere Serien, Raster- und Punktpfade abgedeckt.
Kreisdiagramm — Sektoren, Bézier-Segmentierung, Prozente, Legende, Summe null/negativ	Verifiziert	`pro/tests/Unit/Chart/PieChartTest.php`; `PieChartArithmeticCoverageTest.php`; `PieChartBoundaryCoverageTest.php`	hoch	Sektorpfade, Segmentanzahl je Überstreichung, die 15-Grad-Beschriftungsschwelle, Legendengeometrie und Leerstring-Verhalten abgedeckt.
`ChartBox` — Koordinatenkonvertierung (Benutzerraum zu PDF), Seite oben/unten, Nullabmessungen, Inset	Verifiziert	`pro/tests/Unit/Chart/ChartBoxTest.php`	hoch	Konvertierung von Ursprung oben links zu unten links an Seitenoberkante, -unterkante und Nullabmessungsrändern.
`ChartColor` — RGB-Skalierung, Hex-Parsing, Palette, Kontur-/Fülloperatoren	Verifiziert	`pro/tests/Unit/Chart/ChartColorTest.php`	hoch	Skalierung von 0–255 auf 0–1, Hex mit `#`-Präfix und bloßes Hex, gemischte Groß-/Kleinschreibung, Paletten-Umlauf nach 12 Einträgen.
Renderer-übergreifende Regressionshärtung	Verifiziert	`pro/tests/Unit/Chart/ChartCoverageTest.php`	hoch	Gemeinsame Regressions-Suite über die drei Renderer plus Werteformatierungs-Arithmetik.
Chart-Typen jenseits von Balken/Linie/Kreis (Fläche, Streuung, gestapelt, Ring usw.)	Nicht unterstützt	—	hoch	Kein Renderer wird ausgeliefert. Die Moduloberfläche ist genau Balken, Linie, Kreis. Ehrlich gesagt: dies ist nicht „jeder Chart-Typ“.

Ehrliche Zählung: Verifiziert 6 Zeilen, Behauptet 0, Nicht unterstützt 1 (jeder Chart-Typ außer Balken, Linie, Kreis).

Grenzfälle & Fehlermodi

Kein Renderer löst bei Daten eine Ausnahme aus. Degenerierte Eingaben verschlechtern sich zu einer leeren Zeichenkette: leere Balken- oder Liniendaten, eine leere Serienliste und eine Kreissumme von null oder darunter liefern allesamt '' zurück.
Eine Linienserie mit weniger als zwei Punkten zeichnet keinen Pfad und keine Marker; Achsen und Beschriftungen werden dennoch dargestellt.
Negative Balkenwerte werden nicht abgelehnt; das Balkenrechteck reicht unter die X-Achse.
Beschriftungs- und Werteanzahlen werden nicht gegeneinander validiert. Der Aufrufer liefert Listen gleicher Länge.
Eine ChartBox mit null oder negativen Abmessungen wird akzeptiert und erzeugt degenerierte Ausgabe; Aufrufer müssen die Box dimensionieren.
Renderer clippen nicht. Ein übergroßes Chart, seine Kategoriebeschriftungen unterhalb des Plots oder eine lange Legende können den vorgesehenen Seitenbereich überlaufen.
Eine Seite ohne einen Font unter dem Chart-Font-Ressourcennamen hinterlässt Text-Operatoren, die auf eine undefinierte Ressource verweisen; das Viewer-Verhalten ist dann undefiniert.
ChartColor::hex() führt keine Validierung durch; bei Eingaben mit weniger als sechs Ziffern werden fehlende Komponenten als Null decodiert. ChartColor::palette() scheitert bei negativem Index mit TypeError, da PHPs negativer Modulo keinen Palettenschlüssel auflöst.
Das Modul führt keine Kryptografie durch; der FIPS-Modus hat kein chart-spezifisches Verhalten.

Konformität

Das Chart-Modul gibt PDF-Content-Stream-Operatoren aus. Kein externer Chart-, Symbologie- oder Kryptografiestandard regelt seine Ausgabe, daher ist die einzige Konformitätsfläche der ausgegebene Operator-Stream.

Aussage	Standard	Klausel
Ausgegebene Grafiken folgen dem Content-Stream-Operatormodell; die Ausgabe ist in einem gespeicherten und wiederhergestellten Grafikzustand verschachtelt.	ISO 32000-2	§8.1
Balken, Linien, Sektoren und Marker sind Pfadobjekte: die Konstruktion beginnt mit `m` oder `re` und endet mit einem Pfadmaloperator.	ISO 32000-2	§8.5.2
Beschriftungen werden als Textobjekte dargestellt: die Position wird nach `BT` festgelegt, und Glyphen werden mit dem Textausgabeoperator `Tj` gezeichnet.	ISO 32000-2	§9.2.2, §9.4.3

Alle Klauseln sind paraphrasiert; diese Seite gibt keinen normativen Text wieder. Dies sind Fähigkeitsaussagen, keine Zertifizierungen; NextPDF hält keine Zertifizierung und gewährt keine. Die korrekte Darstellung des Streams hängt zudem davon ab, dass das umgebende Dokument wohlgeformt ist, was in der Verantwortung des Dokumenterstellers liegt.

Entwicklungshinweise

Alle fünf Klassen tragen @since 1.9.0 und sind in nextpdf/pro 3.1.0 aktuell.
Das Modul ist eigenständig: Renderer hängen nur von ChartBox und ChartColor ab, ohne Core-Kopplung.
Deterministische Ausgabe hält Dokumente mit Charts reproduzierbar, diff-stabil und sicher zum Signieren oder Archivieren.
Registrieren Sie einen Font unter dem Chart-Font-Ressourcennamen einmal pro Seite, die Charts enthält.
Verwenden Sie einen konfigurierten Renderer beliebig über mehrere Boxen hinweg wieder; render() führt keine Zustandsänderung durch.
Testnachweise liegen unter pro/tests/Unit/Chart/; die Support-Matrix verankert jede Verifiziert-Zeile mit ihrer Suite.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Geltungsbereichs.

Siehe auch

Chart (Capability) — aufgabenorientierte Übersicht, Installation und Codebeispiele.
Barcode — Ausführliche Referenz — die verwandte Pro-Zeichenoberfläche mit eigener belegbasierter Support-Matrix.