Pro édition

Chart — Référence approfondie

En un coup d’œil

Cette page est la référence au niveau du contrat pour le module Chart de NextPDF Pro. La surface se compose de cinq classes publiques dans NextPDF\Pro\Chart : les moteurs de rendu BarChart, LineChart et PieChart, le rectangle de placement ChartBox et l’objet-valeur ChartColor. Chaque moteur de rendu est une primitive de dessin. Une fabrique statique le crée, des appels fluides with*() le configurent, et render(ChartBox $box): string renvoie les opérateurs de flux de contenu PDF pour le rectangle fourni. La sortie est purement vectorielle et déterministe : une entrée et une configuration identiques produisent des octets identiques. Les entrées dégénérées renvoient une chaîne vide au lieu de lever une exception, si bien qu’un graphique ne casse jamais la page environnante. La vue orientée tâches se trouve sur la page de capacité.

Disponibilité et licence

Cette capacité est livrée dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de niveau Pro. Un déploiement dépourvu de ce droit ne charge pas les classes de la capacité. Comparer les éditions et obtenir une licence.

Les moteurs de rendu de graphiques sont soumis à une licence de capacité sous la famille de capacités chart.*. Lorsque la capacité n’est pas licenciée, les moteurs de rendu de graphiques ne sont pas disponibles.

Surface d’API publique

composer require nextpdf/pro:^3

Symbole	Paramètres	Comportement par défaut	Renvoie	Lève ou échoue avec	Notes
`BarChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Les valeurs sont converties en float	`self`	Ne lève pas	Seule voie de construction ; le constructeur est privé
`BarChart::withBarColor()`	`ChartColor $color`	Remplissage de barre ; par défaut, l’entrée 0 de la palette	`self`	Ne lève pas	Fluide ; mute le receveur
`BarChart::withAxisColor()`	`ChartColor $color`	Trait d’axe ; par défaut `#333333`	`self`	Ne lève pas	—
`BarChart::withBarGap()`	`float $gap`	Espacement en fraction de la largeur d’emplacement ; par défaut `0.2`	`self`	Ne lève pas	Borné à `0.0`–`0.9` ; une entrée hors plage est bornée, non rejetée
`BarChart::withFontSize()`	`float $size`	Taille de police des étiquettes en points ; par défaut `7.0`	`self`	Ne lève pas	—
`BarChart::render()`	`ChartBox $box`	Axes, barres, étiquettes de catégorie, cinq graduations de valeur	opérateurs `string`	Ne lève pas ; des données vides renvoient `''`	Un maximum non positif est mis à l’échelle par rapport à `1.0`
`LineChart::create()`	`list<string> $labels`	Graphique sans série	`self`	Ne lève pas	Le constructeur est privé
`LineChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Ajoute une série sans nom	`self`	Ne lève pas	Commodité pour série unique
`LineChart::addSeries()`	`string $name`, `list<int\|float> $values`, `?ChartColor $color = null`	Une couleur `null` est attribuée automatiquement depuis la palette selon l’index de série	`self`	Ne lève pas	Le nom de série est réservé à l’usage de la légende
`LineChart::withAxisColor()`	`ChartColor $color`	Trait d’axe ; par défaut `#333333`	`self`	Ne lève pas	—
`LineChart::withLineWidth()`	`float $width`	Largeur de trait de série ; par défaut `1.5`	`self`	Ne lève pas	—
`LineChart::withFontSize()`	`float $size`	Taille de police des étiquettes ; par défaut `7.0`	`self`	Ne lève pas	—
`LineChart::withDots()`	`bool $show`, `float $radius = 2.5`	Marqueurs de points de données ; activés par défaut	`self`	Ne lève pas	Les marqueurs sont dessinés comme des cercles approximés par Bézier
`LineChart::withGrid()`	`bool $show`	Grille horizontale par quartiles ; activée par défaut	`self`	Ne lève pas	—
`LineChart::render()`	`ChartBox $box`	Grille, axes, un tracé par série, étiquettes	opérateurs `string`	Ne lève pas ; en l’absence de série, renvoie `''`	Une série de moins de deux points ne dessine aucun tracé
`PieChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Proportions calculées à partir de la somme des valeurs	`self`	Ne lève pas	Le constructeur est privé
`PieChart::withColors()`	`list<ChartColor> $colors`	Une couleur par secteur, dans l’ordre	`self`	Ne lève pas	Les entrées manquantes se rabattent sur la palette
`PieChart::withStrokeColor()`	`ChartColor $color`	Contour de secteur ; blanc par défaut	`self`	Ne lève pas	—
`PieChart::withFontSize()`	`float $size`	Taille de police des étiquettes ; par défaut `7.0`	`self`	Ne lève pas	—
`PieChart::withPercentages()`	`bool $show`	Étiquettes de pourcentage ; activées par défaut	`self`	Ne lève pas	Les étiquettes ne sont rendues que sur les secteurs balayant plus de 15 degrés
`PieChart::withLegend()`	`bool $show`	Légende à droite ; activée par défaut	`self`	Ne lève pas	La légende réserve 80 points de la largeur de la boîte
`PieChart::render()`	`ChartBox $box`	Secteurs, étiquettes optionnelles, légende optionnelle	opérateurs `string`	Ne lève pas ; des données vides ou un total inférieur ou égal à zéro renvoient `''`	Les arcs sont divisés en segments de Bézier d’au plus 90 degrés
`ChartBox::__construct()`	`float $x`, `float $y`, `float $width`, `float $height`	Origine PDF en bas à gauche, en points	—	Ne lève pas	`final readonly` ; les dimensions ne sont pas validées
`ChartBox::fromUserSpace()`	`float $x`, `float $y`, `float $width`, `float $height`, `float $pageHeight`	Bascule un rectangle d’origine en haut à gauche vers les coordonnées PDF	`self`	Ne lève pas	—
`ChartBox::right()`	aucun	`x + width`	`float`	Ne lève pas	Méthode, pas une propriété
`ChartBox::top()`	aucun	`y + height`	`float`	Ne lève pas	Méthode, pas une propriété
`ChartBox::inset()`	`float $left`, `float $bottom`, `float $right`, `float $top`	Sous-boîte réduite par les retraits donnés	`self`	Ne lève pas	Des retraits surdimensionnés produisent des dimensions négatives ; non validé
`ChartColor::__construct()`	`float $r`, `float $g`, `float $b`, chacun `0.0`–`1.0`	—	—	Ne lève pas	`final readonly` ; les composantes ne sont pas bornées
`ChartColor::rgb()`	`int $r`, `int $g`, `int $b`, chacun `0`–`255`	Met les composantes à l’échelle `0.0`–`1.0`	`self`	Ne lève pas	—
`ChartColor::hex()`	`string $hex`	Accepte l’hexadécimal à six chiffres préfixé par `#` ou nu	`self`	Ne lève pas	Les chiffres de fin absents se décodent comme zéro
`ChartColor::palette()`	`int $index`	Palette intégrée de 12 couleurs	`self`	`TypeError` sur un index négatif	Les index non négatifs bouclent modulo 12
`ChartColor::strokeOperator()`	aucun	Opérateur de couleur de trait (`RG`), trois décimales	`string`	Ne lève pas	Méthode, pas une propriété
`ChartColor::fillOperator()`	aucun	Opérateur de couleur de remplissage (`rg`), trois décimales	`string`	Ne lève pas	Méthode, pas une propriété

Signatures des points d’entrée

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

Contrat de comportement

Forme commune des moteurs de rendu

Les trois moteurs de rendu suivent un même cycle de vie : une fabrique statique, une configuration fluide, un seul appel à render(). Les méthodes de configuration mutent le receveur et le renvoient ; les moteurs de rendu ne sont pas des objets-valeurs immuables. render() lit la configuration sans la muter, si bien qu’un moteur de rendu configuré peut être rendu dans plusieurs boîtes. Chaque rendu enveloppe sa sortie dans une paire de sauvegarde/restauration de l’état graphique, si bien que l’état du graphique ne fuit jamais dans la page. Les coordonnées sont émises à deux décimales et les composantes de couleur à trois, ce qui maintient une sortie stable au niveau des octets. Le texte est rendu via le nom de ressource de police /ChartFont à la taille configurée ; l’appelant enregistre une police sous ce nom dans le dictionnaire de ressources de la page cible. Les chaînes d’étiquettes échappent la barre oblique inverse et les parenthèses avant d’entrer dans les opérandes de chaîne. Les moteurs de rendu n’effectuent aucun reflux, aucun détourage et aucune négociation de conteneur : l’appelant maîtrise le placement.

Mise à l’échelle et disposition

Les graphiques en barres et en courbes réservent un retrait de tracé fixe à l’intérieur de la boîte : 40 points à gauche, 20 en bas, 10 à droite, 10 en haut. L’aire de tracé restante met les valeurs à l’échelle linéairement par rapport au maximum de la série. Un maximum nul ou inférieur est mis à l’échelle par rapport à 1.0 à la place, si bien que des données entièrement nulles rendent les axes avec un contenu plat plutôt que de diviser par zéro. Les deux dessinent les axes X et Y à une largeur de 0.5 point et cinq graduations de valeur aux positions de quartile. Les graphiques en barres formatent les valeurs de graduation avec des suffixes K et M au-delà de mille et d’un million ; les graphiques en courbes impriment des nombres simples.

Graphique en barres

Chaque valeur occupe un emplacement égal sur la largeur du tracé. La barre remplit l’emplacement moins la fraction d’espacement configurée et est centrée dans l’emplacement. Les étiquettes de catégorie sont dessinées 12 points sous l’aire de tracé.

Graphique en courbes

La grille, lorsqu’elle est activée, dessine quatre lignes horizontales de quartile en gris clair (0.85 0.85 0.85 RG) sous les axes et les séries. Chaque série dessine une polyligne à travers ses points, couvrant toute la largeur du tracé. Les marqueurs optionnels sont dessinés comme des cercles de Bézier à quatre segments à chaque point de données. Par défaut, les couleurs de série sont des entrées de palette consécutives dans l’ordre d’insertion.

Graphique en secteurs

Les secteurs sont disposés dans l’ordre des données, en partant de l’axe X positif et en balayant dans le sens antihoraire. Chaque tracé de secteur se ferme et se peint avec un remplissage et un trait combinés (h B) ; les arcs sont divisés en segments de Bézier d’au plus 90 degrés. Les étiquettes de pourcentage sont arrondies au pourcentage entier et ne sont rendues que sur les secteurs balayant plus de 15 degrés. La légende, lorsqu’elle est activée, réserve 80 points de la largeur de la boîte à droite et rend une pastille de 8 points par entrée à une hauteur de ligne de 12 points. Le rayon est la moitié de la plus petite valeur entre la largeur restante et la hauteur de la boîte, moins une marge de 10 points.

Objets-valeurs de placement et de couleur

ChartBox est un rectangle immuable en unités utilisateur PDF (points) avec une origine en bas à gauche. ChartBox::fromUserSpace() convertit un rectangle d’origine en haut à gauche en le basculant par rapport à la hauteur de page fournie. inset() renvoie une nouvelle boîte, plus petite ; right() et top() sont des méthodes d’accès. ChartColor est autonome et ne dépend pas des classes de couleur de Core. Sa palette de 12 entrées attribue les couleurs de série et de secteur lorsque l’appelant n’en fournit aucune.

Matrice de prise en charge (appuyée par des preuves)

Un type de graphique ou une fonctionnalité obtient Vérifié uniquement lorsqu’un fixture pro/tests/** l’exerce. Aucune norme externe ne régit les graphiques, si bien que la preuve est une couverture comportementale de niveau unitaire.

Type de graphique / fonctionnalité	Statut	Preuve (chemin de test)	Confiance	Notes
Graphique en barres — rendu, axes, rectangles de barres, bornage d’espacement, données vides/toutes-nulles, formatage de valeur K/M	Vérifié	`pro/tests/Unit/Chart/BarChartTest.php`; `BarChartArithmeticCoverageTest.php`; `BarChartBoundaryCoverageTest.php`	élevée	Enveloppe d’état graphique, lignes d’axe, proportions de hauteur de barre, nombre de graduations et bornes de formatage affirmés.
Graphique en courbes — série unique et multi-séries, tracé de ligne, axes, points, grille, point unique	Vérifié	`pro/tests/Unit/Chart/LineChartTest.php`; `LineChartCoverageTest.php`; `LineChartArithmeticCoverageTest.php`; `LineChartTypeCastCoverageTest.php`	élevée	Multi-séries, point unique sans ligne, série vide, chemins de grille et de points couverts.
Graphique en secteurs — secteurs, segmentation de Bézier, pourcentages, légende, total nul/négatif	Vérifié	`pro/tests/Unit/Chart/PieChartTest.php`; `PieChartArithmeticCoverageTest.php`; `PieChartBoundaryCoverageTest.php`	élevée	Chemins de secteurs, nombre de segments par balayage, seuil d’étiquette à 15 degrés, géométrie de légende et comportement chaîne-vide couverts.
`ChartBox` — conversion de coordonnées (espace utilisateur vers PDF), haut/bas de page, dimensions nulles, retrait	Vérifié	`pro/tests/Unit/Chart/ChartBoxTest.php`	élevée	Conversion origine-en-haut-à-gauche vers origine-en-bas-à-gauche en haut, en bas et aux bords à dimension nulle de la page.
`ChartColor` — mise à l’échelle RGB, analyse hexadécimale, palette, opérateurs de trait/remplissage	Vérifié	`pro/tests/Unit/Chart/ChartColorTest.php`	élevée	Mise à l’échelle 0–255 vers 0–1, hexadécimal préfixé par `#` et nu, casse mixte, bouclage de palette après 12 entrées.
Durcissement de régression inter-moteurs de rendu	Vérifié	`pro/tests/Unit/Chart/ChartCoverageTest.php`	élevée	Suite de régression partagée sur les trois moteurs de rendu plus l’arithmétique de formatage de valeur.
Types de graphique au-delà de barres/courbes/secteurs (aires, nuage de points, empilé, anneau, etc.)	Non pris en charge	—	élevée	Aucun moteur de rendu n’est livré. La surface du module est exactement barres, courbes, secteurs. Dit honnêtement : ce n’est pas « tous les types de graphique ».

Compte honnête : Vérifié 6 lignes, Revendiqué 0, Non pris en charge 1 (tout type de graphique autre que barres, courbes, secteurs).

Cas limites et modes de défaillance

Aucun moteur de rendu ne lève sur les données. Une entrée dégénérée se dégrade en chaîne vide : des données de barres ou de courbes vides, une liste de séries vide et un total de secteurs inférieur ou égal à zéro renvoient tous ''.
Une série de courbe de moins de deux points ne dessine aucun tracé ni marqueur ; les axes et les étiquettes sont tout de même rendus.
Les valeurs de barre négatives ne sont pas rejetées ; le rectangle de barre s’étend sous l’axe X.
Le nombre d’étiquettes et de valeurs n’est pas validé de manière croisée. L’appelant fournit des listes de longueur correspondante.
Une ChartBox à dimensions nulles ou négatives est acceptée et produit une sortie dégénérée ; les appelants doivent dimensionner la boîte.
Les moteurs de rendu ne détourent pas. Un graphique surdimensionné, ses étiquettes de catégorie sous le tracé ou une longue légende peuvent déborder de la région de page prévue.
Une page dépourvue de police sous le nom de ressource de police du graphique laisse des opérateurs de texte référençant une ressource non définie ; le comportement du lecteur est alors indéfini.
ChartColor::hex() n’effectue aucune validation ; une entrée de moins de six chiffres décode les composantes absentes comme zéro. ChartColor::palette() échoue avec TypeError sur un index négatif, car le modulo négatif de PHP ne résout aucune clé de palette.
Le module n’effectue aucune cryptographie ; le mode FIPS n’a aucun comportement spécifique aux graphiques.

Conformité

Le module Chart émet des opérateurs de flux de contenu PDF. Aucune norme externe de graphique, de symbologie ou de cryptographie ne régit sa sortie, si bien que la seule surface de conformité est le flux d’opérateurs émis.

Revendication	Norme	Clause
Les graphiques émis suivent le modèle d’opérateurs de flux de contenu ; la sortie s’imbrique dans un état graphique sauvegardé et restauré.	ISO 32000-2	§8.1
Les barres, lignes, secteurs et marqueurs sont des objets de chemin : la construction commence par `m` ou `re` et se conclut par un opérateur de peinture de chemin.	ISO 32000-2	§8.5.2
Les étiquettes sont rendues comme des objets de texte : la position est établie après `BT`, et les glyphes sont peints avec l’opérateur d’affichage de texte `Tj`.	ISO 32000-2	§9.2.2, §9.4.3

Toutes les clauses sont paraphrasées ; cette page ne reproduit aucun texte normatif. Ce sont des déclarations de capacité, non des certifications ; NextPDF ne détient aucune certification et n’en accorde aucune. Le rendu correct du flux dépend aussi du fait que le document englobant soit bien formé, ce qui relève de la responsabilité de l’auteur du document.

Notes de développement

Les cinq classes portent @since 1.9.0 et sont à jour dans nextpdf/pro 3.1.0.
Le module est autonome : les moteurs de rendu ne dépendent que de ChartBox et ChartColor, sans couplage avec Core.
Une sortie déterministe maintient les documents comportant des graphiques reproductibles, stables au diff et sûrs à signer ou à archiver.
Enregistre une police sous le nom de ressource de police du graphique une fois par page hébergeant des graphiques.
Réutilise librement un moteur de rendu configuré sur plusieurs boîtes ; render() n’effectue aucune mutation d’état.
Les preuves de test se trouvent sous pro/tests/Unit/Chart/ ; la matrice de prise en charge ancre chaque ligne Vérifiée à sa suite.

Périmètre de publication

Cette page ne documente que 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 d’assistance, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de ticket sont hors périmètre.

Voir aussi

Chart (capacité) — aperçu orienté tâches, installation et exemples de code.
Barcode — Référence approfondie — la surface de dessin Pro sœur avec sa propre matrice de prise en charge appuyée par des preuves.