Chart

At a glance

NextPDF Pro renders bar, line, and pie charts directly into a PDF page as vector content operators. There is no rasterization step and no headless-browser dependency, so output is deterministic and reproducible.

Install

composer require nextpdf/pro:^3

Conceptual overview

The Chart module provides three native chart renderers. Each is a self-contained drawing primitive: it renders within a fixed rectangular box you supply, with no reflow, no container awareness, and no layout negotiation. You position the box; the renderer fills it.

• Bar chart — a vertical bar chart with configurable bar colour, axis colour, bar gap, and label font size.
• Line chart — a single- or multi-series line chart with per-series colour, optional data-point markers, optional grid, and configurable line width.
• Pie chart — a circular chart with automatic palette assignment, optional percentage labels, and an optional legend.

Every renderer follows the same shape: a fromData(...) factory, fluent with*() configuration, and a render(ChartBox $box): string call that returns PDF content-stream operators. Output is deterministic — identical input and configuration produce identical operators, which keeps charted documents reproducible and safe to sign or archive.

Because the renderers emit vector operators rather than images, charts remain crisp at any zoom and add no raster payload to the document.

Why it works this way

The load-bearing decision is to emit native PDF vector operators rather than rasterize an image or drive a headless browser. That choice makes output deterministic: identical data and configuration always produce byte-identical operators. Deterministic operators keep a charted document reproducible, and therefore safe to sign or archive. Avoiding an external renderer also removes a process dependency, so throughput scales with data points rather than browser startup cost. Each renderer wraps its operators in a q/Q graphics-state pair and never reflows, so it composes predictably and cheaply.

Design background: High-volume document generation.

API surface

composer require nextpdf/pro:^3

The Chart public surface is five classes in 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 — placement rectangle; fromUserSpace() converts a top-left-origin user-space rectangle to the PDF bottom-left origin; inset() for padding.
• ChartColor — rgb(), hex(), palette(), plus stroke/fill operator emitters.

Code sample — Quick start

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.

Code sample — Production

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

Edge cases & gotchas

• Empty data returns an empty string rather than throwing, so an absent dataset renders nothing instead of breaking the page.
• A pie chart with a zero or negative total returns an empty string.
• A line series with a single point draws no line segment (a single point has no path).
• A ChartBox with zero dimensions renders nothing meaningful; size the box before rendering.
• Renderers do not clip to the box; supply a box that fits the page region you intend.

Performance

Rendering is single-pass and linear in the number of data points. There is no rasterization, no image buffer, and no external process. The size of the emitted operator string bounds memory cost. Multi-series line charts scale linearly with total points across series.

Security notes

Chart renderers consume numeric and label data only; they do not evaluate or execute input. The renderers emit labels as PDF text operators and never interpret them. The module logs no chart data; the application must sanitise sensitive labels before charting.

Conformance

Charts are not governed by an external standard; output is a PDF content stream rendered into the page per ISO 32000-2 content-stream semantics. There is no symbology or cryptographic conformance surface for this module.

Publication boundary

This page documents externally observable behavior and the supported public API surface only. Internal namespace paths, helper classes, mechanism tables, runbook filenames, and ticket prefixes are out of scope.

See also

• Barcode — NextPDF Pro
• Chart deep reference