Pro édition

Graphique

En bref

NextPDF Pro rend des graphiques en barres, en courbes et en secteurs directement dans une page PDF sous forme d’opérateurs de contenu vectoriels. Il n’y a aucune étape de rastérisation ni aucune dépendance à un navigateur sans interface, si bien que la sortie est déterministe et reproductible.

Installation

composer require nextpdf/pro:^3

Aperçu conceptuel

Le module Chart fournit trois moteurs de rendu de graphiques natifs. Chacun est une primitive de dessin autonome : il rend à l’intérieur d’une boîte rectangulaire fixe que tu fournis, sans réagencement, sans conscience du conteneur et sans négociation de mise en page. Tu positionnes la boîte ; le moteur de rendu la remplit.

Graphique en barres — un graphique en barres verticales avec couleur de barre, couleur d’axe, espacement entre barres et taille de police de libellé configurables.
Graphique en courbes — un graphique en courbes à série unique ou multiple, avec couleur par série, marqueurs de points de données optionnels, grille optionnelle et épaisseur de trait configurable.
Graphique en secteurs — un graphique circulaire avec attribution automatique de palette, libellés de pourcentage optionnels et légende optionnelle.

Chaque moteur de rendu suit la même forme : une fabrique fromData(...), une configuration fluide with*() et un appel render(ChartBox $box): string qui renvoie des opérateurs de flux de contenu PDF. La sortie est déterministe — une entrée et une configuration identiques produisent des opérateurs identiques, ce qui garde les documents à graphiques reproductibles et sûrs à signer ou à archiver.

Comme les moteurs de rendu émettent des opérateurs vectoriels plutôt que des images, les graphiques restent nets à n’importe quel niveau de zoom et n’ajoutent aucune charge raster au document.

Pourquoi ça fonctionne ainsi

La décision structurante consiste à émettre des opérateurs vectoriels PDF natifs plutôt qu’à rastériser une image ou à piloter un navigateur sans interface. Ce choix rend la sortie déterministe : des données et une configuration identiques produisent toujours des opérateurs octet-pour-octet identiques. Des opérateurs déterministes gardent un document à graphiques reproductible, et donc sûr à signer ou à archiver. Éviter un moteur de rendu externe supprime aussi une dépendance de processus, si bien que le débit passe à l’échelle avec les points de données plutôt qu’avec le coût de démarrage d’un navigateur. Chaque moteur de rendu enveloppe ses opérateurs dans une paire d’état graphique q/Q et ne réagence jamais, si bien qu’il se compose de façon prévisible et peu coûteuse.

Contexte de conception : Génération de documents à haut volume.

Surface d’API

composer require nextpdf/pro:^3

La surface publique de Chart compte cinq classes dans 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 — rectangle de placement ; fromUserSpace() convertit un rectangle en espace utilisateur d’origine en haut à gauche vers l’origine PDF en bas à gauche ; inset() pour la marge interne.
ChartColor — rgb(), hex(), palette(), plus des émetteurs d’opérateurs de trait/remplissage.

Exemple de code — Démarrage rapide

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.

Exemple de code — Production

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

Cas limites et pièges

Des données vides renvoient une chaîne vide plutôt que de lever une exception, si bien qu’un jeu de données absent ne rend rien au lieu de casser la page.
Un graphique en secteurs dont le total est nul ou négatif renvoie une chaîne vide.
Une série de courbe avec un seul point ne dessine aucun segment de droite (un point unique n’a pas de tracé).
Un ChartBox aux dimensions nulles ne rend rien d’utile ; dimensionne la boîte avant le rendu.
Les moteurs de rendu ne rognent pas sur la boîte ; fournis une boîte qui tient dans la région de page que tu vises.

Performance

Le rendu se fait en une seule passe et est linéaire par rapport au nombre de points de données. Il n’y a aucune rastérisation, aucun tampon d’image et aucun processus externe. La taille de la chaîne d’opérateurs émise borne le coût en mémoire. Les graphiques en courbes multi-séries passent à l’échelle linéairement avec le nombre total de points sur l’ensemble des séries.

Notes de sécurité

Les moteurs de rendu de graphiques ne consomment que des données numériques et des libellés ; ils n’évaluent ni n’exécutent l’entrée. Les moteurs de rendu émettent les libellés sous forme d’opérateurs de texte PDF et ne les interprètent jamais. Le module ne journalise aucune donnée de graphique ; l’application doit assainir les libellés sensibles avant le rendu du graphique.

Conformité

Les graphiques ne sont régis par aucune norme externe ; la sortie est un flux de contenu PDF rendu dans la page selon la sémantique des flux de contenu d’ISO 32000-2. Ce module ne présente aucune surface de conformité de symbologie ou cryptographique.

Périmètre de publication

Cette page documente uniquement le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espaces de noms internes, les classes utilitaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sont hors périmètre.