Chart

Auf einen Blick

NextPDF Pro rendert Balken-, Linien- und Tortendiagramme direkt als Vektor-Content-Operatoren in eine PDF-Seite. Es gibt keinen Rasterisierungsschritt und keine Abhängigkeit von einem Headless-Browser, sodass die Ausgabe deterministisch und reproduzierbar ist.

Installation

composer require nextpdf/pro:^3

Konzeptioneller Überblick

Das Chart-Modul stellt drei native Diagramm-Renderer bereit. Jeder ist ein eigenständiges Zeichen-Primitiv: Er rendert in eine feste rechteckige Box, die Sie vorgeben — ohne Reflow, ohne Container-Bewusstsein und ohne Layout-Aushandlung. Sie positionieren die Box; der Renderer füllt sie.

• Balkendiagramm — ein vertikales Balkendiagramm mit konfigurierbarer Balkenfarbe, Achsenfarbe, Balkenabstand und Beschriftungs-Schriftgröße.
• Liniendiagramm — ein ein- oder mehrreihiges Liniendiagramm mit Farbe je Reihe, optionalen Datenpunkt-Markierungen, optionalem Gitter und konfigurierbarer Linienbreite.
• Tortendiagramm — ein kreisförmiges Diagramm mit automatischer Palettenzuweisung, optionalen Prozentbeschriftungen und einer optionalen Legende.

Jeder Renderer folgt derselben Form: eine fromData(...)-Factory, eine fluente with*()-Konfiguration und ein render(ChartBox $box): string-Aufruf, der PDF-Content-Stream-Operatoren zurückgibt. Die Ausgabe ist deterministisch — identische Eingabe und Konfiguration erzeugen identische Operatoren, wodurch diagrammhaltige Dokumente reproduzierbar und sicher zu signieren oder zu archivieren bleiben.

Da die Renderer Vektor-Operatoren statt Bilder ausgeben, bleiben Diagramme bei jeder Zoomstufe gestochen scharf und fügen dem Dokument keine Raster-Nutzlast hinzu.

Warum es so funktioniert

Die tragende Entscheidung ist, native PDF-Vektor-Operatoren auszugeben, anstatt ein Bild zu rasterisieren oder einen Headless-Browser zu betreiben. Diese Wahl macht die Ausgabe deterministisch: Identische Daten und Konfiguration erzeugen stets byte-identische Operatoren. Deterministische Operatoren halten ein diagrammhaltiges Dokument reproduzierbar und damit sicher zu signieren oder zu archivieren. Der Verzicht auf einen externen Renderer beseitigt zudem eine Prozessabhängigkeit, sodass der Durchsatz mit der Anzahl der Datenpunkte skaliert statt mit den Startkosten eines Browsers. Jeder Renderer umschließt seine Operatoren mit einem q/Q-Grafikzustandspaar und führt niemals einen Reflow durch, sodass er sich vorhersehbar und kostengünstig zusammensetzen lässt.

Designhintergrund: Dokumentenerzeugung in hohem Volumen.

API-Oberfläche

composer require nextpdf/pro:^3

Die öffentliche Chart-Oberfläche besteht aus fünf 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 — Platzierungsrechteck; fromUserSpace() wandelt ein Rechteck im Benutzerkoordinatensystem mit Ursprung oben links in den PDF-Ursprung unten links um; inset() für Innenabstand.
• ChartColor — rgb(), hex(), palette(), dazu Operator-Emitter für Strich und Füllung.

Codebeispiel — Schnellstart

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.

Codebeispiel — Produktion

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);

Randfälle & Fallstricke

• Leere Daten geben einen leeren String zurück, statt eine Ausnahme zu werfen, sodass ein fehlender Datensatz nichts rendert, anstatt die Seite zu beschädigen.
• Ein Tortendiagramm mit einer Summe von null oder negativem Wert gibt einen leeren String zurück.
• Eine Linienreihe mit einem einzigen Punkt zeichnet kein Liniensegment (ein einzelner Punkt hat keinen Pfad).
• Eine ChartBox mit Nulldimensionen rendert nichts Sinnvolles; dimensionieren Sie die Box vor dem Rendern.
• Renderer beschneiden nicht auf die Box; geben Sie eine Box vor, die in den vorgesehenen Seitenbereich passt.

Performance

Das Rendern erfolgt in einem einzigen Durchlauf und ist linear in der Anzahl der Datenpunkte. Es gibt keine Rasterisierung, keinen Bildpuffer und keinen externen Prozess. Die Größe des ausgegebenen Operator-Strings begrenzt die Speicherkosten. Mehrreihige Liniendiagramme skalieren linear mit der Gesamtzahl der Punkte über alle Reihen.

Sicherheitshinweise

Diagramm-Renderer verarbeiten ausschließlich numerische und Beschriftungsdaten; sie werten Eingaben weder aus noch führen sie sie aus. Die Renderer geben Beschriftungen als PDF-Text-Operatoren aus und interpretieren sie niemals. Das Modul protokolliert keine Diagrammdaten; die Anwendung muss sensible Beschriftungen vor dem Diagrammrendern bereinigen.

Konformität

Diagramme unterliegen keinem externen Standard; die Ausgabe ist ein PDF-Content-Stream, der gemäß den Content-Stream-Semantiken von ISO 32000-2 in die Seite gerendert wird. Für dieses Modul gibt es keine Symbologie- oder Krypto-Konformitätsoberfläche.

Veröffentlichungsgrenze

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

Siehe auch

• Barcode — NextPDF Pro
• Chart-Tiefenreferenz