Chart — Referência Profunda

Visão geral

Esta página é a referência em nível de contrato do módulo Chart do NextPDF Pro. A superfície são cinco classes públicas em NextPDF\Pro\Chart: os renderizadores BarChart, LineChart e PieChart, o retângulo de posicionamento ChartBox e o objeto de valor ChartColor. Cada renderizador é uma primitiva de desenho. Uma fábrica estática o cria, chamadas fluentes with*() o configuram e render(ChartBox $box): string retorna operadores de content-stream PDF para o retângulo fornecido. A saída é apenas vetorial e determinística: entrada e configuração idênticas produzem bytes idênticos. Entradas degeneradas retornam uma string vazia em vez de lançar exceção, então um gráfico nunca quebra a página ao redor. A visão orientada a tarefas fica na página de capacidade.

Disponibilidade e licenciamento

Esta capacidade é fornecida no NextPDF Pro (nextpdf/pro) e é ativada com um envelope de licença de nível Pro. Uma implantação sem esse direito não carrega as classes da capacidade. Compare as edições e obtenha uma licença.

Os renderizadores de gráficos são licenciados por capacidade sob a família de capacidades chart.*. Quando a capacidade não está licenciada, os renderizadores de gráficos não ficam disponíveis.

Superfície pública da API

composer require nextpdf/pro:^3

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
BarChart::fromData()	list<string> $labels, list<int|float> $values	Valores são convertidos para float	self	Não lança	Único caminho de construção; o construtor é privado
BarChart::withBarColor()	ChartColor $color	Preenchimento da barra; padrão é a entrada 0 da paleta	self	Não lança	Fluente; muta o receptor
BarChart::withAxisColor()	ChartColor $color	Traço do eixo; padrão #333333	self	Não lança	—
BarChart::withBarGap()	float $gap	Espaçamento como fração da largura do slot; padrão 0.2	self	Não lança	Limitado a 0.0–0.9; entrada fora do intervalo é limitada, não rejeitada
BarChart::withFontSize()	float $size	Tamanho da fonte do rótulo em pontos; padrão 7.0	self	Não lança	—
BarChart::render()	ChartBox $box	Eixos, barras, rótulos de categoria, cinco ticks de valor	operadores string	Não lança; dados vazios retornam ''	Um máximo não positivo escala contra 1.0
LineChart::create()	list<string> $labels	Gráfico sem série	self	Não lança	O construtor é privado
LineChart::fromData()	list<string> $labels, list<int|float> $values	Adiciona uma série sem nome	self	Não lança	Conveniência de série única
LineChart::addSeries()	string $name, list<int|float> $values, ?ChartColor $color = null	Uma cor null é atribuída automaticamente da paleta pelo índice da série	self	Não lança	O nome da série é reservado para uso na legenda
LineChart::withAxisColor()	ChartColor $color	Traço do eixo; padrão #333333	self	Não lança	—
LineChart::withLineWidth()	float $width	Largura do traço da série; padrão 1.5	self	Não lança	—
LineChart::withFontSize()	float $size	Tamanho da fonte do rótulo; padrão 7.0	self	Não lança	—
LineChart::withDots()	bool $show, float $radius = 2.5	Marcadores de ponto de dados; ligados por padrão	self	Não lança	Marcadores desenhados como círculos aproximados por Bézier
LineChart::withGrid()	bool $show	Grade horizontal por quartis; ligada por padrão	self	Não lança	—
LineChart::render()	ChartBox $box	Grade, eixos, um caminho por série, rótulos	operadores string	Não lança; sem série retorna ''	Uma série com menos de dois pontos não desenha caminho
PieChart::fromData()	list<string> $labels, list<int|float> $values	Proporções calculadas a partir da soma dos valores	self	Não lança	O construtor é privado
PieChart::withColors()	list<ChartColor> $colors	Uma cor por fatia, em ordem	self	Não lança	Entradas ausentes recorrem à paleta
PieChart::withStrokeColor()	ChartColor $color	Contorno da fatia; padrão branco	self	Não lança	—
PieChart::withFontSize()	float $size	Tamanho da fonte do rótulo; padrão 7.0	self	Não lança	—
PieChart::withPercentages()	bool $show	Rótulos de percentual; ligados por padrão	self	Não lança	Rótulos são renderizados apenas em fatias que varrem mais de 15 graus
PieChart::withLegend()	bool $show	Legenda à direita; ligada por padrão	self	Não lança	A legenda reserva 80 pontos da largura da caixa
PieChart::render()	ChartBox $box	Setores, rótulos opcionais, legenda opcional	operadores string	Não lança; dados vazios ou um total igual ou abaixo de zero retornam ''	Arcos divididos em segmentos de Bézier de no máximo 90 graus
ChartBox::__construct()	float $x, float $y, float $width, float $height	Origem no canto inferior esquerdo do PDF, em pontos	—	Não lança	final readonly; dimensões não são validadas
ChartBox::fromUserSpace()	float $x, float $y, float $width, float $height, float $pageHeight	Inverte um retângulo de origem superior esquerda para coordenadas PDF	self	Não lança	—
ChartBox::right()	nenhum	x + width	float	Não lança	Método, não propriedade
ChartBox::top()	nenhum	y + height	float	Não lança	Método, não propriedade
ChartBox::inset()	float $left, float $bottom, float $right, float $top	Sub-caixa encolhida pelos insets dados	self	Não lança	Insets grandes demais produzem dimensões negativas; não validadas
ChartColor::__construct()	float $r, float $g, float $b, cada 0.0–1.0	—	—	Não lança	final readonly; componentes não são limitados
ChartColor::rgb()	int $r, int $g, int $b, cada 0–255	Escala componentes para 0.0–1.0	self	Não lança	—
ChartColor::hex()	string $hex	Aceita hex de seis dígitos com prefixo # ou sem	self	Não lança	Dígitos finais ausentes decodificam como zero
ChartColor::palette()	int $index	Paleta interna de 12 cores	self	TypeError em índice negativo	Índices não negativos dão a volta com módulo 12
ChartColor::strokeOperator()	nenhum	Operador de cor de traço (RG), três decimais	string	Não lança	Método, não propriedade
ChartColor::fillOperator()	nenhum	Operador de cor de preenchimento (rg), três decimais	string	Não lança	Método, não propriedade

Assinaturas dos pontos 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 comportamento

Forma comum dos renderizadores

Os três renderizadores seguem um ciclo de vida: uma fábrica estática, configuração fluente, uma chamada render(). Os métodos de configuração mutam o receptor e o retornam; renderizadores não são objetos de valor imutáveis. render() lê a configuração sem mutá-la, então um renderizador configurado pode renderizar em várias caixas. Cada render encapsula sua saída em um par salvar/restaurar de graphics-state, então o estado do gráfico nunca vaza para a página. Coordenadas são emitidas com duas casas decimais e componentes de cor com três, o que mantém a saída estável em bytes. Texto é renderizado através do nome de recurso de fonte /ChartFont no tamanho configurado; o chamador registra uma fonte sob esse nome no dicionário de recursos da página de destino. Strings de rótulo escapam barra invertida e parênteses antes de entrar nos operandos de string. Os renderizadores não realizam reflow, nem recorte, nem negociação de contêiner: o posicionamento pertence ao chamador.

Escalonamento e layout

Gráficos de barras e de linhas reservam um inset de plotagem fixo dentro da caixa: 40 pontos à esquerda, 20 abaixo, 10 à direita, 10 acima. A área de plotagem restante escala os valores linearmente contra o máximo da série. Um máximo igual ou abaixo de zero escala contra 1.0 em vez disso, então dados todos zero renderizam eixos com conteúdo plano em vez de dividir por zero. Ambos desenham os eixos X e Y com 0,5 ponto de largura e cinco ticks de valor nas posições de quartil. Gráficos de barras formatam valores de tick com sufixos K e M acima de mil e de um milhão; gráficos de linhas imprimem números simples.

Gráfico de barras

Cada valor ocupa um slot igual ao longo da largura da plotagem. A barra preenche o slot menos a fração de espaçamento configurada e é centralizada no slot. Rótulos de categoria são desenhados 12 pontos abaixo da área de plotagem.

Gráfico de linhas

A grade, quando habilitada, desenha quatro linhas horizontais de quartil em cinza claro (0.85 0.85 0.85 RG) abaixo dos eixos e das séries. Cada série desenha uma polilinha através de seus pontos, abrangendo toda a largura da plotagem. Marcadores opcionais são desenhados como círculos de Bézier de quatro segmentos em cada ponto de dados. As cores das séries usam por padrão entradas consecutivas da paleta na ordem de inserção.

Gráfico de pizza

As fatias são dispostas na ordem dos dados, começando no eixo X positivo e varrendo no sentido anti-horário. Cada caminho de setor fecha e pinta com preenchimento e traço combinados (h B); arcos se dividem em segmentos de Bézier de no máximo 90 graus. Rótulos de percentual arredondam para o percentual inteiro e são renderizados apenas em fatias que varrem mais de 15 graus. A legenda, quando habilitada, reserva 80 pontos da largura da caixa à direita e renderiza uma amostra de 8 pontos por entrada com altura de linha de 12 pontos. O raio é metade do menor entre a largura restante e a altura da caixa, menos uma margem de 10 pontos.

Objetos de valor de posicionamento e cor

ChartBox é um retângulo imutável em unidades de usuário do PDF (pontos) com origem no canto inferior esquerdo. ChartBox::fromUserSpace() converte um retângulo de origem superior esquerda invertendo-o contra a altura de página fornecida. inset() retorna uma nova caixa menor; right() e top() são métodos acessores. ChartColor é autossuficiente e não depende das classes de cor do Core. Sua paleta de 12 entradas atribui cores de série e de fatia quando o chamador não fornece nenhuma.

Matriz de suporte (respaldada por evidências)

Um tipo ou recurso de gráfico obtém Verified apenas quando uma fixture pro/tests/** o exercita. Nenhum padrão externo governa os gráficos, então a evidência é cobertura comportamental em nível de unidade.

Tipo / recurso de gráfico	Status	Evidência (caminho de teste)	Confiança	Notas
Gráfico de barras — render, eixos, retângulos de barra, limitação de espaçamento, dados vazios/todos zero, formatação de valor K/M	Verified	pro/tests/Unit/Chart/BarChartTest.php; BarChartArithmeticCoverageTest.php; BarChartBoundaryCoverageTest.php	high	Encapsulamento do graphics-state, linhas de eixo, proporções de altura da barra, contagem de ticks e limites de formatação afirmados.
Gráfico de linhas — série única e múltipla, caminho de linha, eixos, pontos, grade, ponto único	Verified	pro/tests/Unit/Chart/LineChartTest.php; LineChartCoverageTest.php; LineChartArithmeticCoverageTest.php; LineChartTypeCastCoverageTest.php	high	Múltiplas séries, sem linha para ponto único, série vazia, caminhos de grade e pontos cobertos.
Gráfico de pizza — setores, segmentação de Bézier, percentuais, legenda, total zero/negativo	Verified	pro/tests/Unit/Chart/PieChartTest.php; PieChartArithmeticCoverageTest.php; PieChartBoundaryCoverageTest.php	high	Caminhos de setor, contagens de segmentos por varredura, o limiar de rótulo de 15 graus, geometria da legenda e comportamento de string vazia cobertos.
ChartBox — conversão de coordenadas (user space para PDF), topo/base da página, dimensões zero, inset	Verified	pro/tests/Unit/Chart/ChartBoxTest.php	high	Conversão de origem superior esquerda para origem inferior esquerda no topo da página, na base e nas bordas de dimensão zero.
ChartColor — escalonamento RGB, parsing de hex, paleta, operadores de stroke/fill	Verified	pro/tests/Unit/Chart/ChartColorTest.php	high	Escalonamento 0–255 para 0–1, hex com prefixo # e sem prefixo, maiúsculas/minúsculas mistas, volta da paleta após 12 entradas.
Reforço de regressão entre renderizadores	Verified	pro/tests/Unit/Chart/ChartCoverageTest.php	high	Conjunto compartilhado de regressão entre os três renderizadores mais a aritmética de formatação de valores.
Tipos de gráfico além de barra/linha/pizza (área, dispersão, empilhado, rosca, etc.)	Not supported	—	high	Nenhum renderizador é fornecido. A superfície do módulo é exatamente barra, linha, pizza. Declarado com honestidade: isto não é “todo tipo de gráfico”.

Contagem honesta: Verified 6 linhas, Claimed 0, Not supported 1 (qualquer tipo de gráfico que não seja barra, linha, pizza).

Casos extremos e modos de falha

• Nenhum renderizador lança exceção sobre os dados. Entrada degenerada degrada para uma string vazia: dados de barra ou linha vazios, uma lista de séries vazia e um total de pizza igual ou abaixo de zero, todos retornam ''.
• Uma série de linha com menos de dois pontos não desenha caminho nem marcadores; eixos e rótulos ainda são renderizados.
• Valores de barra negativos não são rejeitados; o retângulo da barra se estende abaixo do eixo X.
• Contagens de rótulos e valores não são validadas cruzadamente. O chamador fornece listas de comprimento correspondente.
• Um ChartBox com dimensões zero ou negativas é aceito e produz saída degenerada; os chamadores precisam dimensionar a caixa.
• Os renderizadores não recortam. Um gráfico grande demais, seus rótulos de categoria abaixo da plotagem ou uma legenda longa podem transbordar a região de página pretendida.
• Uma página sem uma fonte sob o nome de recurso de fonte do gráfico deixa operadores de texto referenciando um recurso indefinido; o comportamento do visualizador fica então indefinido.
• ChartColor::hex() não realiza validação; uma entrada com menos de seis dígitos decodifica os componentes ausentes como zero. ChartColor::palette() falha com TypeError em um índice negativo, porque o módulo negativo do PHP não resolve nenhuma chave de paleta.
• O módulo não realiza criptografia; o modo FIPS não tem comportamento específico de gráficos.

Conformidade

O módulo Chart emite operadores de content-stream PDF. Nenhum padrão externo de gráfico, simbologia ou criptográfico governa sua saída, então a única superfície de conformidade é o fluxo de operadores emitido.

Afirmação	Norma	Cláusula
Os gráficos emitidos seguem o modelo de operadores de content-stream; a saída se aninha dentro de um graphics state salvo e restaurado.	ISO 32000-2	§8.1
Barras, linhas, setores e marcadores são objetos de caminho: a construção começa com m ou re e conclui com um operador de pintura de caminho.	ISO 32000-2	§8.5.2
Rótulos são renderizados como objetos de texto: a posição é estabelecida após BT, e os glifos são pintados com o operador de exibição de texto Tj.	ISO 32000-2	§9.2.2, §9.4.3

Todas as cláusulas são parafraseadas; esta página não reproduz nenhum texto normativo. Estas são declarações de capacidade, não certificações; o NextPDF não possui certificação e não concede nenhuma. A renderização correta do fluxo também depende de o documento envolvente estar bem formado, o que é responsabilidade de quem escreve o documento.

Notas de desenvolvimento

• Todas as cinco classes carregam @since 1.9.0 e estão atuais no nextpdf/pro 3.1.0.
• O módulo é autossuficiente: os renderizadores dependem apenas de ChartBox e ChartColor, sem acoplamento com o Core.
• A saída determinística mantém documentos com gráficos reprodutíveis, estáveis em diff e seguros para assinar ou arquivar.
• Registre uma fonte sob o nome de recurso de fonte do gráfico uma vez por página que hospeda gráficos.
• Reutilize um renderizador configurado livremente entre caixas; render() não realiza mutação de estado.
• As evidências de teste ficam em pro/tests/Unit/Chart/; a matriz de suporte ancora cada linha Verified ao seu conjunto de testes.

Fronteira de publicação

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

Veja também

• Chart (capacidade) — visão orientada a tarefas, instalação e exemplos de código.
• Barcode — Referência Profunda — a superfície de desenho irmã do Pro com sua própria matriz de suporte respaldada por evidências.