Chart

De un vistazo

NextPDF Pro renderiza gráficos de barras, de líneas y circulares directamente en una página PDF como operadores de contenido vectorial. No hay paso de rasterización ni dependencia de un navegador headless, de modo que la salida es determinista y reproducible.

Instalación

composer require nextpdf/pro:^3

Descripción conceptual

El módulo Chart proporciona tres renderizadores de gráficos nativos. Cada uno es una primitiva de dibujo autónoma: renderiza dentro de una caja rectangular fija que se proporciona, sin reflujo, sin conciencia del contenedor y sin negociación de maquetación. Se posiciona la caja; el renderizador la rellena.

• Gráfico de barras — un gráfico de barras vertical con color de barra, color de eje, separación entre barras y tamaño de fuente de etiqueta configurables.
• Gráfico de líneas — un gráfico de líneas de una o varias series con color por serie, marcadores de puntos de datos opcionales, cuadrícula opcional y ancho de línea configurable.
• Gráfico circular — un gráfico circular con asignación automática de paleta, etiquetas de porcentaje opcionales y una leyenda opcional.

Todos los renderizadores siguen la misma forma: una fábrica fromData(...), configuración fluida with*() y una llamada render(ChartBox $box): string que devuelve operadores de flujo de contenido PDF. La salida es determinista: una entrada y una configuración idénticas producen operadores idénticos, lo que mantiene los documentos con gráficos reproducibles y seguros para firmar o archivar.

Como los renderizadores emiten operadores vectoriales en lugar de imágenes, los gráficos se mantienen nítidos a cualquier nivel de zoom y no añaden carga ráster al documento.

Por qué funciona así

La decisión de fondo es emitir operadores vectoriales PDF nativos en lugar de rasterizar una imagen o accionar un navegador headless. Esa elección hace que la salida sea determinista: datos y configuración idénticos siempre producen operadores idénticos a nivel de byte. Los operadores deterministas mantienen reproducible un documento con gráficos y, por tanto, seguro para firmar o archivar. Evitar un renderizador externo también elimina una dependencia de proceso, de modo que el rendimiento escala con los puntos de datos y no con el coste de arranque del navegador. Cada renderizador envuelve sus operadores en un par de estado gráfico q/Q y nunca reflujo, por lo que se compone de forma predecible y económica.

Contexto de diseño: Generación de documentos de alto volumen.

Superficie de la API

composer require nextpdf/pro:^3

La superficie pública de Chart son cinco clases en 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 — rectángulo de colocación; fromUserSpace() convierte un rectángulo de espacio de usuario con origen en la esquina superior izquierda al origen inferior izquierdo de PDF; inset() para el relleno.
• ChartColor — rgb(), hex(), palette(), además de emisores de operadores de trazo/relleno.

Ejemplo de código — Inicio rápido

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.

Ejemplo de código — Producción

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

Casos límite y trampas

• Los datos vacíos devuelven una cadena vacía en lugar de lanzar una excepción, de modo que un conjunto de datos ausente no renderiza nada en vez de romper la página.
• Un gráfico circular con un total cero o negativo devuelve una cadena vacía.
• Una serie de líneas con un único punto no dibuja ningún segmento de línea (un único punto no tiene trazado).
• Un ChartBox con dimensiones cero no renderiza nada significativo; dimensione la caja antes de renderizar.
• Los renderizadores no recortan al contorno de la caja; proporcione una caja que se ajuste a la región de la página que pretende usar.

Rendimiento

El renderizado es de una sola pasada y lineal respecto al número de puntos de datos. No hay rasterización, ni búfer de imagen, ni proceso externo. El tamaño de la cadena de operadores emitida acota el coste de memoria. Los gráficos de líneas de varias series escalan linealmente con el total de puntos entre series.

Notas de seguridad

Los renderizadores de gráficos consumen únicamente datos numéricos y de etiqueta; no evalúan ni ejecutan la entrada. Los renderizadores emiten las etiquetas como operadores de texto PDF y nunca las interpretan. El módulo no registra ningún dato de gráfico; la aplicación debe sanear las etiquetas sensibles antes de graficar.

Conformidad

Los gráficos no se rigen por ningún estándar externo; la salida es un flujo de contenido PDF renderizado en la página según la semántica de flujo de contenido de ISO 32000-2. Este módulo no tiene superficie de conformidad de simbología ni criptográfica.

Límite de publicación

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

Véase también

• Barcode — NextPDF Pro
• Referencia profunda de Chart