Pro edizione

Chart — Riferimento approfondito

In sintesi

Questa pagina è il riferimento a livello di contratto per il modulo Chart di NextPDF Pro. La superficie è costituita da cinque classi pubbliche in NextPDF\Pro\Chart: i renderer BarChart, LineChart e PieChart, il rettangolo di posizionamento ChartBox e il value object ChartColor. Ogni renderer è una primitiva di disegno. Una factory statica lo crea, chiamate fluenti with*() lo configurano e render(ChartBox $box): string restituisce gli operatori di content stream PDF per il rettangolo fornito. L’output è solo vettoriale e deterministico: input e configurazione identici producono byte identici. Gli input degeneri restituiscono una stringa vuota anziché sollevare un’eccezione, così che un grafico non comprometta mai la pagina circostante. La vista orientata ai compiti risiede nella pagina delle funzionalità.

Disponibilità e licenza

Questa funzionalità è inclusa in NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di livello Pro. Un deployment privo di quel diritto non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

I renderer di grafici sono licenziati per capability sotto la famiglia di capability chart.*. Quando la capability non è licenziata, i renderer di grafici non sono disponibili.

Superficie API pubblica

composer require nextpdf/pro:^3

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
`BarChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	I valori sono convertiti a float	`self`	Non solleva eccezioni	Unica via di costruzione; il costruttore è privato
`BarChart::withBarColor()`	`ChartColor $color`	Riempimento delle barre; predefinito è la voce 0 della palette	`self`	Non solleva eccezioni	Fluente; muta il ricevitore
`BarChart::withAxisColor()`	`ChartColor $color`	Tratto degli assi; predefinito `#333333`	`self`	Non solleva eccezioni	—
`BarChart::withBarGap()`	`float $gap`	Spaziatura come frazione della larghezza dello slot; predefinito `0.2`	`self`	Non solleva eccezioni	Limitato a `0.0`–`0.9`; l’input fuori intervallo è limitato, non respinto
`BarChart::withFontSize()`	`float $size`	Corpo del carattere delle etichette in punti; predefinito `7.0`	`self`	Non solleva eccezioni	—
`BarChart::render()`	`ChartBox $box`	Assi, barre, etichette di categoria, cinque tacche di valore	operatori `string`	Non solleva eccezioni; dati vuoti restituiscono `''`	Un massimo non positivo scala rispetto a `1.0`
`LineChart::create()`	`list<string> $labels`	Grafico senza serie	`self`	Non solleva eccezioni	Il costruttore è privato
`LineChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Aggiunge una serie senza nome	`self`	Non solleva eccezioni	Comodità a serie singola
`LineChart::addSeries()`	`string $name`, `list<int\|float> $values`, `?ChartColor $color = null`	Un colore `null` si assegna automaticamente dalla palette per indice della serie	`self`	Non solleva eccezioni	Il nome della serie è riservato all’uso nella legenda
`LineChart::withAxisColor()`	`ChartColor $color`	Tratto degli assi; predefinito `#333333`	`self`	Non solleva eccezioni	—
`LineChart::withLineWidth()`	`float $width`	Larghezza del tratto delle serie; predefinita `1.5`	`self`	Non solleva eccezioni	—
`LineChart::withFontSize()`	`float $size`	Corpo del carattere delle etichette; predefinito `7.0`	`self`	Non solleva eccezioni	—
`LineChart::withDots()`	`bool $show`, `float $radius = 2.5`	Marcatori dei punti dati; attivi per impostazione predefinita	`self`	Non solleva eccezioni	I marcatori si disegnano come cerchi approssimati con curve di Bézier
`LineChart::withGrid()`	`bool $show`	Griglia orizzontale a quartili; attiva per impostazione predefinita	`self`	Non solleva eccezioni	—
`LineChart::render()`	`ChartBox $box`	Griglia, assi, un percorso per serie, etichette	operatori `string`	Non solleva eccezioni; nessuna serie restituisce `''`	Una serie più corta di due punti non disegna alcun percorso
`PieChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Proporzioni calcolate dalla somma dei valori	`self`	Non solleva eccezioni	Il costruttore è privato
`PieChart::withColors()`	`list<ChartColor> $colors`	Un colore per fetta, in ordine	`self`	Non solleva eccezioni	Le voci mancanti ricadono sulla palette
`PieChart::withStrokeColor()`	`ChartColor $color`	Contorno delle fette; predefinito bianco	`self`	Non solleva eccezioni	—
`PieChart::withFontSize()`	`float $size`	Corpo del carattere delle etichette; predefinito `7.0`	`self`	Non solleva eccezioni	—
`PieChart::withPercentages()`	`bool $show`	Etichette di percentuale; attive per impostazione predefinita	`self`	Non solleva eccezioni	Le etichette si disegnano solo sulle fette che spazzano più di 15 gradi
`PieChart::withLegend()`	`bool $show`	Legenda a destra; attiva per impostazione predefinita	`self`	Non solleva eccezioni	La legenda riserva 80 punti di larghezza del box
`PieChart::render()`	`ChartBox $box`	Settori, etichette opzionali, legenda opzionale	operatori `string`	Non solleva eccezioni; dati vuoti o un totale pari o inferiore a zero restituiscono `''`	Gli archi si suddividono in segmenti di Bézier di al massimo 90 gradi
`ChartBox::__construct()`	`float $x`, `float $y`, `float $width`, `float $height`	Origine PDF in basso a sinistra, in punti	—	Non solleva eccezioni	`final readonly`; le dimensioni non sono validate
`ChartBox::fromUserSpace()`	`float $x`, `float $y`, `float $width`, `float $height`, `float $pageHeight`	Ribalta un rettangolo con origine in alto a sinistra in coordinate PDF	`self`	Non solleva eccezioni	—
`ChartBox::right()`	nessuno	`x + width`	`float`	Non solleva eccezioni	Metodo, non proprietà
`ChartBox::top()`	nessuno	`y + height`	`float`	Non solleva eccezioni	Metodo, non proprietà
`ChartBox::inset()`	`float $left`, `float $bottom`, `float $right`, `float $top`	Sotto-box ridotto dei margini indicati	`self`	Non solleva eccezioni	Margini eccessivi producono dimensioni negative; non validato
`ChartColor::__construct()`	`float $r`, `float $g`, `float $b`, ciascuno `0.0`–`1.0`	—	—	Non solleva eccezioni	`final readonly`; i componenti non sono limitati
`ChartColor::rgb()`	`int $r`, `int $g`, `int $b`, ciascuno `0`–`255`	Scala i componenti a `0.0`–`1.0`	`self`	Non solleva eccezioni	—
`ChartColor::hex()`	`string $hex`	Accetta esadecimali a sei cifre con prefisso `#` o nudi	`self`	Non solleva eccezioni	Le cifre finali assenti si decodificano come zero
`ChartColor::palette()`	`int $index`	Palette integrata a 12 colori	`self`	`TypeError` su un indice negativo	Gli indici non negativi si avvolgono modulo 12
`ChartColor::strokeOperator()`	nessuno	Operatore di colore del tratto (`RG`), tre decimali	`string`	Non solleva eccezioni	Metodo, non proprietà
`ChartColor::fillOperator()`	nessuno	Operatore di colore di riempimento (`rg`), tre decimali	`string`	Non solleva eccezioni	Metodo, non proprietà

Firme dei punti di ingresso

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

Contratto di comportamento

Forma comune dei renderer

Tutti e tre i renderer seguono un unico ciclo di vita: una factory statica, la configurazione fluente, una chiamata render(). I metodi di configurazione mutano il ricevitore e lo restituiscono; i renderer non sono value object immutabili. render() legge la configurazione senza mutarla, così che un renderer configurato possa disegnare in più box. Ogni render racchiude il proprio output in una coppia salva/ripristina dello stato grafico, così che lo stato del grafico non trapeli mai nella pagina. Le coordinate sono emesse con due decimali e i componenti di colore con tre, il che mantiene l’output stabile a livello di byte. Il testo è reso attraverso il nome di risorsa font /ChartFont al corpo configurato; il chiamante registra un font con quel nome nel dizionario delle risorse della pagina di destinazione. Le stringhe delle etichette effettuano l’escape di backslash e parentesi prima di entrare negli operandi stringa. I renderer non eseguono alcun reflow, alcun clipping né alcuna negoziazione del contenitore: il posizionamento spetta al chiamante.

Scala e layout

I grafici a barre e a linee riservano un margine di plot fisso all’interno del box: 40 punti a sinistra, 20 in basso, 10 a destra, 10 in alto. L’area di plot rimanente scala i valori linearmente rispetto al massimo della serie. Un massimo pari a zero o inferiore scala invece rispetto a 1.0, così che dati tutti a zero producano assi con contenuto piatto anziché una divisione per zero. Entrambi disegnano gli assi X e Y con larghezza 0,5 punti e cinque tacche di valore alle posizioni dei quartili. I grafici a barre formattano i valori delle tacche con suffissi K e M sopra il migliaio e il milione; i grafici a linee stampano numeri semplici.

Grafico a barre

Ciascun valore occupa uno slot uguale lungo la larghezza del plot. La barra riempie lo slot meno la frazione di spaziatura configurata ed è centrata nello slot. Le etichette di categoria si disegnano 12 punti sotto l’area di plot.

Grafico a linee

La griglia, quando abilitata, disegna quattro linee orizzontali ai quartili in grigio chiaro (0.85 0.85 0.85 RG) sotto gli assi e le serie. Ciascuna serie disegna una polilinea attraverso i propri punti, estendendosi per l’intera larghezza del plot. I marcatori opzionali si disegnano come cerchi di Bézier a quattro segmenti a ciascun punto dati. I colori delle serie assumono per impostazione predefinita voci consecutive della palette nell’ordine di inserimento.

Grafico a torta

Le fette si dispongono nell’ordine dei dati, partendo dall’asse X positivo e spazzando in senso antiorario. Ciascun percorso di settore si chiude e si dipinge con riempimento e tratto combinati (h B); gli archi si suddividono in segmenti di Bézier di al massimo 90 gradi. Le etichette di percentuale si arrotondano al punto percentuale intero e si disegnano solo sulle fette che spazzano più di 15 gradi. La legenda, quando abilitata, riserva 80 punti di larghezza del box a destra e rende un campione di 8 punti per voce a un’interlinea di 12 punti. Il raggio è la metà del minore tra la larghezza rimanente e l’altezza del box, meno un margine di 10 punti.

Value object di posizionamento e colore

ChartBox è un rettangolo immutabile in unità utente PDF (punti) con origine in basso a sinistra. ChartBox::fromUserSpace() converte un rettangolo con origine in alto a sinistra ribaltandolo rispetto all’altezza di pagina fornita. inset() restituisce un box nuovo e più piccolo; right() e top() sono metodi di accesso. ChartColor è autonomo e non dipende dalle classi di colore di Core. La sua palette a 12 voci assegna i colori a serie e fette quando il chiamante non ne fornisce alcuno.

Matrice di supporto (con prove a sostegno)

Un tipo o una funzionalità di grafico ottiene Verificato solo quando una fixture pro/tests/** lo esercita. Nessuno standard esterno governa i grafici, quindi le prove sono copertura comportamentale a livello di unit.

Tipo / funzionalità di grafico	Stato	Prova (percorso di test)	Confidenza	Note
Grafico a barre — render, assi, rettangoli delle barre, limitazione della spaziatura, dati vuoti/tutti a zero, formattazione dei valori K/M	Verificato	`pro/tests/Unit/Chart/BarChartTest.php`; `BarChartArithmeticCoverageTest.php`; `BarChartBoundaryCoverageTest.php`	alta	Wrap dello stato grafico, linee degli assi, proporzioni delle altezze delle barre, conteggio delle tacche e confini di formattazione asseriti.
Grafico a linee — serie singola e multipla, percorso della linea, assi, punti, griglia, punto singolo	Verificato	`pro/tests/Unit/Chart/LineChartTest.php`; `LineChartCoverageTest.php`; `LineChartArithmeticCoverageTest.php`; `LineChartTypeCastCoverageTest.php`	alta	Serie multiple, punto singolo senza linea, serie vuota, percorsi di griglia e punti coperti.
Grafico a torta — settori, segmentazione di Bézier, percentuali, legenda, totale zero/negativo	Verificato	`pro/tests/Unit/Chart/PieChartTest.php`; `PieChartArithmeticCoverageTest.php`; `PieChartBoundaryCoverageTest.php`	alta	Percorsi dei settori, conteggi dei segmenti per spazzata, la soglia di etichetta di 15 gradi, la geometria della legenda e il comportamento a stringa vuota coperti.
`ChartBox` — conversione di coordinate (spazio utente → PDF), top/bottom della pagina, dimensioni zero, inset	Verificato	`pro/tests/Unit/Chart/ChartBoxTest.php`	alta	Conversione da origine in alto a sinistra a origine in basso a sinistra al top, al bottom e ai bordi a dimensione zero della pagina.
`ChartColor` — scala RGB, parsing esadecimale, palette, operatori di stroke/fill	Verificato	`pro/tests/Unit/Chart/ChartColorTest.php`	alta	Scala 0–255 → 0–1, esadecimale con prefisso `#` e nudo, maiuscole/minuscole miste, avvolgimento della palette dopo 12 voci.
Rafforzamento di regressione tra i renderer	Verificato	`pro/tests/Unit/Chart/ChartCoverageTest.php`	alta	Suite di regressione condivisa sui tre renderer più l’aritmetica di formattazione dei valori.
Tipi di grafico oltre a barre/linee/torta (area, scatter, stacked, donut, ecc.)	Non supportato	—	alta	Nessun renderer incluso. La superficie del modulo è esattamente barre, linee, torta. Dichiarato onestamente: questo non è «ogni tipo di grafico».

Conteggio onesto: Verificato 6 righe, Dichiarato 0, Non supportato 1 (qualsiasi tipo di grafico diverso da barre, linee, torta).

Casi limite e modalità di errore

Nessun renderer solleva eccezioni sui dati. Gli input degeneri degradano a una stringa vuota: dati vuoti a barre o a linee, un elenco di serie vuoto e un totale della torta pari o inferiore a zero restituiscono tutti ''.
Una serie a linee con meno di due punti non disegna alcun percorso né alcun marcatore; assi ed etichette si rendono comunque.
I valori negativi delle barre non sono respinti; il rettangolo della barra si estende sotto l’asse X.
I conteggi di etichette e valori non sono controllati incrociatamente. Il chiamante fornisce elenchi di lunghezza corrispondente.
Un ChartBox con dimensioni pari o inferiori a zero è accettato e produce output degenere; i chiamanti devono dimensionare il box.
I renderer non eseguono clipping. Un grafico sovradimensionato, le sue etichette di categoria sotto il plot o una legenda lunga possono debordare oltre la regione di pagina prevista.
Una pagina priva di un font sotto il nome di risorsa font del grafico lascia gli operatori di testo che fanno riferimento a una risorsa non definita; il comportamento del visualizzatore è quindi indefinito.
ChartColor::hex() non esegue alcuna validazione; un input più corto di sei cifre decodifica i componenti assenti come zero. ChartColor::palette() fallisce con TypeError su un indice negativo, perché il modulo negativo di PHP non risolve alcuna chiave della palette.
Il modulo non esegue alcuna crittografia; la modalità FIPS non ha alcun comportamento specifico per i grafici.

Conformità

Il modulo Chart emette operatori di content stream PDF. Nessuno standard esterno di grafica, simbologia o crittografia governa il suo output, quindi l’unica superficie di conformità è il flusso di operatori emesso.

Affermazione	Standard	Clausola
La grafica emessa segue il modello degli operatori di content stream; l’output si annida all’interno di uno stato grafico salvato e ripristinato.	ISO 32000-2	§8.1
Barre, linee, settori e marcatori sono oggetti percorso: la costruzione inizia con `m` o `re` e si conclude con un operatore di pittura del percorso.	ISO 32000-2	§8.5.2
Le etichette si rendono come oggetti di testo: la posizione è stabilita dopo `BT` e i glifi si dipingono con l’operatore di mostra del testo `Tj`.	ISO 32000-2	§9.2.2, §9.4.3

Tutte le clausole sono parafrasate; questa pagina non riproduce alcun testo normativo. Si tratta di dichiarazioni di funzionalità, non di certificazioni; NextPDF non detiene alcuna certificazione e non ne concede alcuna. La corretta resa del flusso dipende anche dal fatto che il documento circostante sia ben formato, il che è responsabilità di chi scrive il documento.

Note di sviluppo

Tutte e cinque le classi portano @since 1.9.0 e sono attuali in nextpdf/pro 3.1.0.
Il modulo è autonomo: i renderer dipendono solo da ChartBox e ChartColor, senza alcun accoppiamento con Core.
L’output deterministico mantiene i documenti con grafici riproducibili, stabili al diff e sicuri da firmare o archiviare.
Registrare un font sotto il nome di risorsa font del grafico una volta per ogni pagina che ospita grafici.
Riutilizzare liberamente un renderer configurato tra più box; render() non esegue alcuna mutazione di stato.
Le prove di test risiedono sotto pro/tests/Unit/Chart/; la matrice di supporto àncora ciascuna riga Verificato alla propria suite.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile esternamente e la superficie API pubblica supportata. Percorsi di namespace interni, classi helper, tabelle di meccanismo, nomi di file di runbook e prefissi di ticket sono fuori ambito.

Vedere anche

Chart (funzionalità) — panoramica orientata ai compiti, installazione ed esempi di codice.
Barcode — Riferimento approfondito — la superficie di disegno Pro affine con la propria matrice di supporto basata su prove.