ChartJs

Pair framework: ChartJs

Pair\Helpers\ChartJs builds Chart.js config from PHP, registers the script in Application, and returns the <canvas> element.

Constructor

new ChartJs(string $type, ?string $elementId = null)

Supported chart types: line, bar, radar, doughnut, pie, polarArea, bubble, scatter.

Validation:

• invalid type throws AppException
• invalid elementId throws AppException
• if elementId is omitted, Pair generates one (chart-...)

Default options set in constructor:

• responsive = true
• resizeDelay = 250

Main API

Data and datasets:

• labels(array $labels): self
• dataset(ChartJsDataset $dataset): self
• rangeLabels(DateTimeInterface $start, DateTimeInterface $end, string $interval, ?string $pattern = null): self

Layout and interaction:

• animation(int $duration, string $easing = 'linear', ?string $onProgress = null, ?string $onComplete = null): self
• aspectRatio(float $ratio): self
• maintainAspectRatio(bool $maintainAspectRatio): self
• responsive(bool $responsive): self
• resizeDelay(int $milliseconds): self
• horizontal(): self
• hover(string $mode, bool $intersect, int $animationDuration): self
• interaction(string $mode, bool $intersect, string $axis): self
• stacked(bool $xStacked, bool $yStacked): self
• padding(array|int $padding): self
• margins(int $top, int $right, int $bottom, int $left): self
• normalized(bool $normalized): self
• parsing(bool $parsing): self
• option(string $name, array|string|bool $value): self

Elements and plugins:

• elementsArc(string $backgroundColor, string $borderColor, int $borderWidth): self
• elementsPoint(int $radius, string $backgroundColor, string $borderColor, int $borderWidth): self
• elementsRectangle(string $backgroundColor, string $borderColor, int $borderWidth): self
• legend(string $position, string $align, array $config = []): self
• hideLegend(): self
• title(string $text, array $config = []): self
• subtitle(string $text, array $config = []): self
• plugin(string $pluginName, array $pluginOptions): self
• datalabels(array $pluginOptions): self

Performance for large line charts:

• decimation(string $algorithm, int $samples, int $threshold): self

Rendering:

• render(): string
• renderConfig(): string
• __toString(): string

CDN loaders:

• ChartJs::load(string $version = ''): void
• ChartJs::loadDatalabels(string $version = ''): void
• ChartJs::loadGeo(): void

Important notes

• decimation(...) is allowed only for line charts and validates algorithm/samples/threshold.
• rangeLabels(...) requires current user and session (User::current() and Session::current()) and throws AppException otherwise.
• render() adds JS to Application::addScript(...); include Chart.js before page output.
• renderConfig() returns pure JSON config, useful for debugging or custom JS handling.

Examples

Minimal line chart:

use Pair\Helpers\ChartJs;
use Pair\Helpers\ChartJsDataset;

ChartJs::load('4.4.1');

$chart = (new ChartJs('line', 'salesChart'))
    ->labels(['Jan', 'Feb', 'Mar', 'Apr'])
    ->dataset(
        (new ChartJsDataset([120, 135, 128, 162], 'Sales'))
            ->borderColor('#2f80ed')
            ->borderWidth(2)
            ->fill(false)
            ->pointRadius(3)
            ->interpolation('monotone')
    )
    ->title('Monthly sales')
    ->subtitle('FY 2026')
    ->legend('top', 'center')
    ->interaction('index', false, 'x');

echo $chart->render();

Bar chart with stacked axes and datalabels plugin:

ChartJs::load();
ChartJs::loadDatalabels();

$chart = (new ChartJs('bar', 'channelsChart'))
    ->labels(['Organic', 'Paid', 'Referral'])
    ->dataset((new ChartJsDataset([320, 210, 95], 'Leads'))->backgroundColors(['#57A0E5', '#ED6E85', '#F1A454']))
    ->stacked(false, false)
    ->datalabels([
        'anchor' => 'end',
        'align' => 'top',
        'color' => '#333'
    ])
    ->hideLegend();

Decimation on large line series:

$chart = (new ChartJs('line', 'telemetryChart'))
    ->parsing(false)
    ->normalized(true)
    ->decimation('lttb', 300, 1000)
    ->resizeDelay(150);

Dataset companion

Use ChartJsDataset to configure series-level options (type, backgroundColors, colorFunction, interpolation, fill, etc.) before adding datasets via dataset(...).

See also: ChartJsDataset, Application, View.