Pro edição

Chart

Visão geral

O NextPDF Pro renderiza gráficos de barras, linhas e pizza diretamente em uma página PDF como operadores de conteúdo vetorial. Não há etapa de rasterização nem dependência de navegador headless, então a saída é determinística e reproduzível.

Instalação

composer require nextpdf/pro:^3

Visão conceitual

O módulo Chart fornece três renderizadores nativos de gráficos. Cada um é uma primitiva de desenho autocontida: ele renderiza dentro de uma caixa retangular fixa que você fornece, sem reflow, sem percepção do contêiner e sem negociação de layout. Você posiciona a caixa; o renderizador a preenche.

Gráfico de barras — um gráfico de barras verticais com cor da barra, cor do eixo, espaçamento entre barras e tamanho da fonte do rótulo configuráveis.
Gráfico de linhas — um gráfico de linhas de série única ou múltipla com cor por série, marcadores de pontos de dados opcionais, grade opcional e largura de linha configurável.
Gráfico de pizza — um gráfico circular com atribuição automática de paleta, rótulos de porcentagem opcionais e uma legenda opcional.

Todo renderizador segue o mesmo formato: uma fábrica fromData(...), configuração fluente with*() e uma chamada render(ChartBox $box): string que retorna operadores de content stream PDF. A saída é determinística — entradas e configurações idênticas produzem operadores idênticos, o que mantém os documentos com gráficos reproduzíveis e seguros para assinar ou arquivar.

Como os renderizadores emitem operadores vetoriais em vez de imagens, os gráficos permanecem nítidos em qualquer zoom e não acrescentam nenhuma carga raster ao documento.

Por que funciona assim

A decisão estrutural é emitir operadores vetoriais nativos do PDF em vez de rasterizar uma imagem ou acionar um navegador headless. Essa escolha torna a saída determinística: dados e configuração idênticos sempre produzem operadores byte a byte idênticos. Operadores determinísticos mantêm um documento com gráficos reproduzível e, portanto, seguro para assinar ou arquivar. Evitar um renderizador externo também remove uma dependência de processo, de modo que a taxa de transferência escala com os pontos de dados em vez do custo de inicialização do navegador. Cada renderizador envolve seus operadores em um par de estado gráfico q/Q e nunca faz reflow, então compõe de forma previsível e barata.

Contexto de projeto: Geração de documentos em alto volume.

Superfície da API

composer require nextpdf/pro:^3

A superfície pública do Chart são cinco classes em 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 — retângulo de posicionamento; fromUserSpace() converte um retângulo do espaço do usuário com origem no canto superior esquerdo para a origem no canto inferior esquerdo do PDF; inset() para preenchimento.
ChartColor — rgb(), hex(), palette(), mais emissores de operadores de traço/preenchimento.

Exemplo de código — Início 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.

Exemplo de código — Produção

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 extremos e armadilhas

Dados vazios retornam uma string vazia em vez de lançar uma exceção, então um conjunto de dados ausente não renderiza nada em vez de quebrar a página.
Um gráfico de pizza com total zero ou negativo retorna uma string vazia.
Uma série de linha com um único ponto não desenha nenhum segmento de linha (um único ponto não tem caminho).
Um ChartBox com dimensões zero não renderiza nada útil; dimensione a caixa antes de renderizar.
Os renderizadores não recortam ao limite da caixa; forneça uma caixa que se ajuste à região da página que você pretende usar.

Desempenho

A renderização é de passagem única e linear no número de pontos de dados. Não há rasterização, nem buffer de imagem, nem processo externo. O tamanho da string de operadores emitida limita o custo de memória. Gráficos de linhas de múltiplas séries escalam linearmente com o total de pontos em todas as séries.

Notas de segurança

Os renderizadores de gráficos consomem apenas dados numéricos e de rótulo; eles não avaliam nem executam a entrada. Os renderizadores emitem rótulos como operadores de texto PDF e nunca os interpretam. O módulo não registra dados de gráfico; a aplicação deve higienizar os rótulos sensíveis antes de gerar o gráfico.

Conformidade

Os gráficos não são regidos por nenhum padrão externo; a saída é um content stream PDF renderizado na página de acordo com a semântica de content stream da ISO 32000-2. Não há superfície de conformidade de simbologia ou criptográfica para este módulo.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície pública de API suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de ticket estão fora do escopo.