Grafico

In breve

NextPDF Pro disegna grafici a barre, a linee e a torta direttamente in una pagina PDF come operatori di contenuto vettoriali. Non vi è alcuna fase di rasterizzazione né alcuna dipendenza da un browser headless, quindi l’output è deterministico e riproducibile.

Installazione

composer require nextpdf/pro:^3

Panoramica concettuale

Il modulo Chart fornisce tre renderer nativi di grafici. Ciascuno è una primitiva di disegno autonoma: disegna entro un riquadro rettangolare fisso fornito dall’utente, senza riflusso, senza consapevolezza del contenitore e senza negoziazione del layout. L’utente posiziona il riquadro; il renderer lo riempie.

• Grafico a barre — un grafico a barre verticali con colore delle barre, colore degli assi, spaziatura tra le barre e dimensione del font delle etichette configurabili.
• Grafico a linee — un grafico a linee a una o più serie, con colore per serie, marcatori dei punti dati opzionali, griglia opzionale e larghezza della linea configurabile.
• Grafico a torta — un grafico circolare con assegnazione automatica della palette, etichette percentuali opzionali e una legenda opzionale.

Ogni renderer segue la stessa forma: un metodo factory fromData(...), una configurazione fluente with*() e una chiamata render(ChartBox $box): string che restituisce gli operatori del content stream PDF. L’output è deterministico — un input e una configurazione identici producono operatori identici, il che mantiene i documenti con grafici riproducibili e sicuri da firmare o archiviare.

Poiché i renderer emettono operatori vettoriali anziché immagini, i grafici restano nitidi a qualsiasi ingrandimento e non aggiungono alcun payload raster al documento.

Perché funziona così

La decisione portante è quella di emettere operatori vettoriali PDF nativi anziché rasterizzare un’immagine o pilotare un browser headless. Questa scelta rende l’output deterministico: dati e configurazione identici producono sempre operatori identici byte per byte. Operatori deterministici mantengono un documento con grafici riproducibile e, di conseguenza, sicuro da firmare o archiviare. Evitare un renderer esterno elimina inoltre una dipendenza di processo, quindi il throughput scala con i punti dati anziché con il costo di avvio del browser. Ogni renderer racchiude i propri operatori in una coppia di stato grafico q/Q e non esegue mai un riflusso, così da comporsi in modo prevedibile ed economico.

Contesto di progettazione: Generazione di documenti ad alto volume.

Superficie API

composer require nextpdf/pro:^3

La superficie pubblica di Chart è composta da cinque classi 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 — rettangolo di posizionamento; fromUserSpace() converte un rettangolo in spazio utente con origine in alto a sinistra all’origine in basso a sinistra del PDF; inset() per il padding.
• ChartColor — rgb(), hex(), palette(), oltre agli emettitori di operatori di tratto/riempimento.

Esempio di codice — Avvio rapido

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.

Esempio di codice — Produzione

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

Casi limite e insidie

• Dati vuoti restituiscono una stringa vuota anziché sollevare un’eccezione, quindi un dataset assente non disegna nulla invece di compromettere la pagina.
• Un grafico a torta con un totale pari a zero o negativo restituisce una stringa vuota.
• Una serie a linee con un solo punto non disegna alcun segmento di linea (un singolo punto non ha un tracciato).
• Un ChartBox con dimensioni nulle non disegna nulla di significativo; dimensionare il riquadro prima del disegno.
• I renderer non ritagliano al riquadro; fornire un riquadro che si adatti alla regione di pagina prevista.

Prestazioni

Il disegno avviene in un’unica passata ed è lineare rispetto al numero di punti dati. Non vi è rasterizzazione, né buffer di immagine, né processo esterno. La dimensione della stringa di operatori emessa delimita il costo in memoria. I grafici a linee multi-serie scalano linearmente con il totale dei punti tra tutte le serie.

Note sulla sicurezza

I renderer dei grafici consumano solo dati numerici e di etichetta; non valutano né eseguono l’input. I renderer emettono le etichette come operatori di testo PDF e non le interpretano mai. Il modulo non registra alcun dato dei grafici; l’applicazione deve sanificare le etichette sensibili prima di disegnarle.

Conformità

I grafici non sono governati da uno standard esterno; l’output è un content stream PDF disegnato nella pagina secondo la semantica dei content stream di ISO 32000-2. Per questo modulo non esiste alcuna superficie di conformità di simbologia o crittografica.

Ambito di pubblicazione

Questa pagina documenta unicamente il comportamento osservabile dall’esterno e la superficie API pubblica supportata. I percorsi di namespace interni, le classi helper, le tabelle dei meccanismi, i nomi dei file di runbook e i prefissi dei ticket sono fuori ambito.

Vedi anche

• Barcode — NextPDF Pro
• Riferimento approfondito su Chart