Pro edición

Chart — Referencia detallada

De un vistazo

Esta página es la referencia a nivel de contrato del módulo Chart de NextPDF Pro. La superficie son cinco clases públicas en NextPDF\Pro\Chart: los renderizadores BarChart, LineChart y PieChart, el rectángulo de posicionamiento ChartBox y el objeto de valor ChartColor. Cada renderizador es una primitiva de dibujo. Una fábrica estática lo crea, las llamadas fluidas with*() lo configuran, y render(ChartBox $box): string devuelve operadores del flujo de contenido PDF para el rectángulo suministrado. La salida es solo vectorial y determinista: una entrada y una configuración idénticas producen bytes idénticos. Las entradas degeneradas devuelven una cadena vacía en lugar de lanzar una excepción, de modo que un gráfico nunca rompe la página que lo rodea. La vista orientada a tareas se encuentra en la página de capacidad.

Disponibilidad y licencias

Esta capacidad se incluye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin esa habilitación no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

Los renderizadores de gráficos tienen licencia por capacidad dentro de la familia de capacidades chart.*. Cuando la capacidad no está licenciada, los renderizadores de gráficos no están disponibles.

Superficie de la API pública

composer require nextpdf/pro:^3

Símbolo	Parámetros	Comportamiento por defecto	Devuelve	Lanza o falla con	Notas
`BarChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Los valores se convierten a float	`self`	No lanza excepción	Única vía de construcción; el constructor es privado
`BarChart::withBarColor()`	`ChartColor $color`	Relleno de barra; por defecto la entrada 0 de la paleta	`self`	No lanza excepción	Fluido; muta el receptor
`BarChart::withAxisColor()`	`ChartColor $color`	Trazo del eje; por defecto `#333333`	`self`	No lanza excepción	—
`BarChart::withBarGap()`	`float $gap`	Separación como fracción del ancho de ranura; por defecto `0.2`	`self`	No lanza excepción	Acotado a `0.0`–`0.9`; la entrada fuera de rango se acota, no se rechaza
`BarChart::withFontSize()`	`float $size`	Tamaño de fuente de las etiquetas en puntos; por defecto `7.0`	`self`	No lanza excepción	—
`BarChart::render()`	`ChartBox $box`	Ejes, barras, etiquetas de categoría, cinco marcas de valor	operadores `string`	No lanza excepción; con datos vacíos devuelve `''`	Un máximo no positivo se escala frente a `1.0`
`LineChart::create()`	`list<string> $labels`	Gráfico sin series	`self`	No lanza excepción	El constructor es privado
`LineChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Añade una serie sin nombre	`self`	No lanza excepción	Conveniencia de serie única
`LineChart::addSeries()`	`string $name`, `list<int\|float> $values`, `?ChartColor $color = null`	Un color `null` se autoasigna desde la paleta según el índice de serie	`self`	No lanza excepción	El nombre de la serie se reserva para uso en la leyenda
`LineChart::withAxisColor()`	`ChartColor $color`	Trazo del eje; por defecto `#333333`	`self`	No lanza excepción	—
`LineChart::withLineWidth()`	`float $width`	Ancho de trazo de la serie; por defecto `1.5`	`self`	No lanza excepción	—
`LineChart::withFontSize()`	`float $size`	Tamaño de fuente de las etiquetas; por defecto `7.0`	`self`	No lanza excepción	—
`LineChart::withDots()`	`bool $show`, `float $radius = 2.5`	Marcadores de puntos de datos; activados por defecto	`self`	No lanza excepción	Los marcadores se dibujan como círculos aproximados con Bézier
`LineChart::withGrid()`	`bool $show`	Cuadrícula horizontal por cuartiles; activada por defecto	`self`	No lanza excepción	—
`LineChart::render()`	`ChartBox $box`	Cuadrícula, ejes, un trazado por serie, etiquetas	operadores `string`	No lanza excepción; sin series devuelve `''`	Una serie con menos de dos puntos no dibuja ningún trazado
`PieChart::fromData()`	`list<string> $labels`, `list<int\|float> $values`	Proporciones calculadas a partir de la suma de valores	`self`	No lanza excepción	El constructor es privado
`PieChart::withColors()`	`list<ChartColor> $colors`	Un color por sector, en orden	`self`	No lanza excepción	Las entradas faltantes recurren a la paleta
`PieChart::withStrokeColor()`	`ChartColor $color`	Contorno del sector; por defecto blanco	`self`	No lanza excepción	—
`PieChart::withFontSize()`	`float $size`	Tamaño de fuente de las etiquetas; por defecto `7.0`	`self`	No lanza excepción	—
`PieChart::withPercentages()`	`bool $show`	Etiquetas de porcentaje; activadas por defecto	`self`	No lanza excepción	Las etiquetas se renderizan solo en sectores que barren más de 15 grados
`PieChart::withLegend()`	`bool $show`	Leyenda a la derecha; activada por defecto	`self`	No lanza excepción	La leyenda reserva 80 puntos del ancho de la caja
`PieChart::render()`	`ChartBox $box`	Sectores, etiquetas opcionales, leyenda opcional	operadores `string`	No lanza excepción; con datos vacíos o un total igual o inferior a cero devuelve `''`	Los arcos se dividen en segmentos de Bézier de como máximo 90 grados
`ChartBox::__construct()`	`float $x`, `float $y`, `float $width`, `float $height`	Origen inferior izquierdo de PDF, en puntos	—	No lanza excepción	`final readonly`; las dimensiones no se validan
`ChartBox::fromUserSpace()`	`float $x`, `float $y`, `float $width`, `float $height`, `float $pageHeight`	Voltea un rectángulo de origen superior izquierdo a coordenadas PDF	`self`	No lanza excepción	—
`ChartBox::right()`	ninguno	`x + width`	`float`	No lanza excepción	Método, no propiedad
`ChartBox::top()`	ninguno	`y + height`	`float`	No lanza excepción	Método, no propiedad
`ChartBox::inset()`	`float $left`, `float $bottom`, `float $right`, `float $top`	Subcaja reducida por los márgenes indicados	`self`	No lanza excepción	Los márgenes excesivos producen dimensiones negativas; no se validan
`ChartColor::__construct()`	`float $r`, `float $g`, `float $b`, cada uno `0.0`–`1.0`	—	—	No lanza excepción	`final readonly`; los componentes no se acotan
`ChartColor::rgb()`	`int $r`, `int $g`, `int $b`, cada uno `0`–`255`	Escala los componentes a `0.0`–`1.0`	`self`	No lanza excepción	—
`ChartColor::hex()`	`string $hex`	Acepta hexadecimal de seis dígitos con prefijo `#` o sin él	`self`	No lanza excepción	Los dígitos finales ausentes se decodifican como cero
`ChartColor::palette()`	`int $index`	Paleta integrada de 12 colores	`self`	`TypeError` con un índice negativo	Los índices no negativos se envuelven módulo 12
`ChartColor::strokeOperator()`	ninguno	Operador de color de trazo (`RG`), tres decimales	`string`	No lanza excepción	Método, no propiedad
`ChartColor::fillOperator()`	ninguno	Operador de color de relleno (`rg`), tres decimales	`string`	No lanza excepción	Método, no propiedad

Firmas de los puntos de entrada

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

Contrato de comportamiento

Forma común de los renderizadores

Los tres renderizadores siguen un mismo ciclo de vida: una fábrica estática, configuración fluida, una llamada a render(). Los métodos de configuración mutan el receptor y lo devuelven; los renderizadores no son objetos de valor inmutables. render() lee la configuración sin mutarla, de modo que un renderizador configurado puede renderizarse en varias cajas. Cada renderizado envuelve su salida en un par de guardado/restauración del estado gráfico, de modo que el estado del gráfico nunca se filtra a la página. Las coordenadas se emiten con dos decimales y los componentes de color con tres, lo que mantiene la salida estable a nivel de bytes. El texto se renderiza a través del nombre de recurso de fuente /ChartFont en el tamaño configurado; quien invoca registra una fuente bajo ese nombre en el diccionario de recursos de la página de destino. Las cadenas de etiqueta escapan la barra invertida y los paréntesis antes de entrar en los operandos de cadena. Los renderizadores no realizan reflujo, ni recorte, ni negociación de contenedor: quien invoca es responsable del posicionamiento.

Escalado y disposición

Los gráficos de barras y de líneas reservan un margen de trazado fijo dentro de la caja: 40 puntos a la izquierda, 20 abajo, 10 a la derecha, 10 arriba. El área de trazado restante escala los valores linealmente frente al máximo de la serie. Un máximo de cero o inferior se escala frente a 1.0 en su lugar, de modo que los datos totalmente en cero renderizan ejes con contenido plano en lugar de dividir por cero. Ambos dibujan los ejes X e Y con 0,5 puntos de ancho y cinco marcas de valor en las posiciones de cuartil. Los gráficos de barras formatean los valores de las marcas con sufijos K y M por encima de mil y de un millón; los gráficos de líneas imprimen números simples.

Gráfico de barras

Cada valor ocupa una ranura igual a lo ancho del trazado. La barra rellena la ranura menos la fracción de separación configurada y se centra en la ranura. Las etiquetas de categoría se dibujan 12 puntos por debajo del área de trazado.

Gráfico de líneas

La cuadrícula, cuando está habilitada, dibuja cuatro líneas horizontales por cuartiles en gris claro (0.85 0.85 0.85 RG) debajo de los ejes y las series. Cada serie dibuja una polilínea a través de sus puntos, abarcando todo el ancho del trazado. Los marcadores opcionales se dibujan como círculos de Bézier de cuatro segmentos en cada punto de datos. Los colores de las series toman por defecto entradas consecutivas de la paleta en orden de inserción.

Gráfico circular

Los sectores se disponen en orden de datos, comenzando en el eje X positivo y barriendo en sentido antihorario. Cada trazado de sector se cierra y se pinta con relleno y trazo combinados (h B); los arcos se dividen en segmentos de Bézier de como máximo 90 grados. Las etiquetas de porcentaje se redondean al porcentaje entero y se renderizan solo en sectores que barren más de 15 grados. La leyenda, cuando está habilitada, reserva 80 puntos del ancho de la caja a la derecha y renderiza una muestra de 8 puntos por entrada con una altura de línea de 12 puntos. El radio es la mitad del menor entre el ancho restante y la altura de la caja, menos un margen de 10 puntos.

Objetos de valor de posicionamiento y color

ChartBox es un rectángulo inmutable en unidades de usuario de PDF (puntos) con origen inferior izquierdo. ChartBox::fromUserSpace() convierte un rectángulo de origen superior izquierdo volteándolo frente a la altura de página suministrada. inset() devuelve una caja nueva y más pequeña; right() y top() son métodos de acceso. ChartColor es autónomo y no depende de las clases de color de Core. Su paleta de 12 entradas asigna colores a series y sectores cuando quien invoca no suministra ninguno.

Matriz de soporte (respaldada por evidencia)

Un tipo de gráfico o característica obtiene Verificado solo cuando un fixture de pro/tests/** lo ejercita. Ningún estándar externo rige los gráficos, por lo que la evidencia es cobertura de comportamiento a nivel unitario.

Tipo de gráfico / característica	Estado	Evidencia (ruta de prueba)	Confianza	Notas
Gráfico de barras — renderizado, ejes, rectángulos de barra, acotado de separación, datos vacíos/todo-cero, formateo de valores K/M	Verificado	`pro/tests/Unit/Chart/BarChartTest.php`; `BarChartArithmeticCoverageTest.php`; `BarChartBoundaryCoverageTest.php`	alta	Se afirman el envoltorio del estado gráfico, las líneas de eje, las proporciones de altura de barra, el conteo de marcas y los límites de formateo.
Gráfico de líneas — serie única y múltiple, trazado de línea, ejes, puntos, cuadrícula, punto único	Verificado	`pro/tests/Unit/Chart/LineChartTest.php`; `LineChartCoverageTest.php`; `LineChartArithmeticCoverageTest.php`; `LineChartTypeCastCoverageTest.php`	alta	Se cubren series múltiples, sin línea en punto único, serie vacía, y los trazados de cuadrícula y de puntos.
Gráfico circular — sectores, segmentación de Bézier, porcentajes, leyenda, total cero/negativo	Verificado	`pro/tests/Unit/Chart/PieChartTest.php`; `PieChartArithmeticCoverageTest.php`; `PieChartBoundaryCoverageTest.php`	alta	Se cubren los trazados de sector, los conteos de segmentos por barrido, el umbral de etiqueta de 15 grados, la geometría de la leyenda y el comportamiento de cadena vacía.
`ChartBox` — conversión de coordenadas (espacio de usuario a PDF), parte superior/inferior de página, dimensiones cero, inset	Verificado	`pro/tests/Unit/Chart/ChartBoxTest.php`	alta	Conversión de origen superior izquierdo a inferior izquierdo en los bordes superior, inferior y de dimensión cero de la página.
`ChartColor` — escalado RGB, análisis hexadecimal, paleta, operadores de trazo/relleno	Verificado	`pro/tests/Unit/Chart/ChartColorTest.php`	alta	Escalado de 0–255 a 0–1, hexadecimal con prefijo `#` y sin él, mayúsculas/minúsculas mixtas, envoltura de paleta tras 12 entradas.
Endurecimiento de regresión entre renderizadores	Verificado	`pro/tests/Unit/Chart/ChartCoverageTest.php`	alta	Suite de regresión compartida entre los tres renderizadores más la aritmética de formateo de valores.
Tipos de gráfico más allá de barras/líneas/circular (área, dispersión, apilado, dona, etc.)	No soportado	—	alta	No se incluye ningún renderizador. La superficie del módulo es exactamente barras, líneas y circular. Dicho con honestidad: esto no es «todos los tipos de gráfico».

Recuento honesto: 6 filas Verificado, 0 Reclamado, 1 No soportado (cualquier tipo de gráfico distinto de barras, líneas o circular).

Casos límite y modos de fallo

Ningún renderizador lanza excepción sobre los datos. La entrada degenerada se degrada a una cadena vacía: los datos de barras o líneas vacíos, una lista de series vacía y un total circular igual o inferior a cero devuelven todos ''.
Una serie de líneas con menos de dos puntos no dibuja ningún trazado ni marcadores; los ejes y las etiquetas sí se renderizan.
Los valores de barra negativos no se rechazan; el rectángulo de la barra se extiende por debajo del eje X.
Los recuentos de etiquetas y de valores no se validan de forma cruzada. Quien invoca suministra listas de longitud coincidente.
Un ChartBox con dimensiones cero o negativas se acepta y produce una salida degenerada; quien invoca debe dimensionar la caja.
Los renderizadores no recortan. Un gráfico sobredimensionado, sus etiquetas de categoría por debajo del trazado o una leyenda larga pueden desbordar la región de página prevista.
Una página que carece de una fuente bajo el nombre de recurso de fuente del gráfico deja los operadores de texto refiriendo un recurso no definido; el comportamiento del visor queda entonces indefinido.
ChartColor::hex() no realiza validación; una entrada de menos de seis dígitos decodifica los componentes ausentes como cero. ChartColor::palette() falla con TypeError en un índice negativo, porque el módulo negativo de PHP no resuelve ninguna clave de paleta.
El módulo no realiza criptografía; el modo FIPS no tiene comportamiento específico de gráficos.

Conformidad

El módulo Chart emite operadores del flujo de contenido PDF. Ningún estándar externo de gráficos, simbología o criptografía rige su salida, por lo que la única superficie de conformidad es el flujo de operadores emitido.

Afirmación	Estándar	Cláusula
Los gráficos emitidos siguen el modelo de operadores del flujo de contenido; la salida se anida dentro de un estado gráfico guardado y restaurado.	ISO 32000-2	§8.1
Las barras, líneas, sectores y marcadores son objetos de trazado: la construcción comienza con `m` o `re` y concluye con un operador de pintado de trazado.	ISO 32000-2	§8.5.2
Las etiquetas se renderizan como objetos de texto: la posición se establece tras `BT`, y los glifos se pintan con el operador de mostrado de texto `Tj`.	ISO 32000-2	§9.2.2, §9.4.3

Todas las cláusulas están parafraseadas; esta página no reproduce ningún texto normativo. Son declaraciones de capacidad, no certificaciones; NextPDF no posee ninguna certificación ni la otorga. El renderizado correcto del flujo también depende de que el documento contenedor esté bien formado, lo cual es responsabilidad de quien escribe el documento.

Notas de desarrollo

Las cinco clases llevan @since 1.9.0 y están vigentes en nextpdf/pro 3.1.0.
El módulo es autónomo: los renderizadores dependen únicamente de ChartBox y ChartColor, sin acoplamiento con Core.
La salida determinista mantiene los documentos con gráficos reproducibles, estables ante diferencias y seguros para firmar o archivar.
Registrar una fuente bajo el nombre de recurso de fuente del gráfico una vez por cada página que aloje gráficos.
Reutilizar libremente un renderizador configurado entre cajas; render() no realiza mutación de estado.
La evidencia de pruebas se encuentra bajo pro/tests/Unit/Chart/; la matriz de soporte ancla cada fila Verificado a su suite.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie de la API pública soportada. Las rutas de espacio de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivos de runbook y los prefijos de tickets quedan fuera de alcance.

Véase también

Chart (capacidad) — descripción orientada a tareas, instalación y ejemplos de código.
Barcode — Referencia detallada — la superficie de dibujo Pro hermana con su propia matriz de soporte respaldada por evidencia.