Chartjs Builder Laravel Package

Getting Started

Install with Composer:

composer require mukadi/chartjs-builder

The package sits on top of Chart.js — you hand it a SQL query and it turns the result set into a Chart.js config object you can render server-side or return as JSON. Start by reading the ChartBuilder class and the README examples; the public surface is only a handful of classes, so it's readable in one sitting.

Minimal flow in plain PHP:

use Mukadi\Chart\ChartBuilder;

$builder = new ChartBuilder($pdo);
$chart   = $builder->build("SELECT status AS label, COUNT(*) AS value FROM orders GROUP BY status");

echo $chart->render();      // inline <canvas> + script
// or $chart->toArray()     // Chart.js config for JSON responses

Your first real use case: any GROUP BY that returns a category plus a count (status breakdowns, signups per month, top products). Alias the columns to the label/value pair the builder expects and it's a one-liner.

In Laravel the service provider and facade are auto-discovered; the published config is where you point it at a non-default DB connection.

Implementation Patterns

• Label/value reports — any aggregate returning category + count works directly. Order in SQL, not after — the builder preserves row order and that becomes your axis order.
• Multiple datasets — run several queries and attach each as a dataset (e.g. this month vs. last month). Keep labels aligned between queries so the axis mapping doesn't drift.
• Front-end JSON — if your app already ships Chart.js via npm, return $chart->toArray() from a controller and instantiate new Chart(ctx, config) client-side. This is the cleanest integration and avoids server-rendered script tags entirely.
• Blade embedding — render the <canvas> yourself, then push the config with @push('scripts') and @json($config). You keep layout control and avoid output-order surprises.
• Options pass-through — type, colours, legend, and scales are set via a plain options array. You're configuring Chart.js directly, not a package DSL, so keep the Chart.js version docs open.
• Parameter binding — bind ? placeholders in the raw SQL; the builder executes it verbatim, so interpolating user input is an injection vector.
• Wrap it — put the builder call behind a service or repository method so caching, tests, and future replacement live in one place.

Gotchas and Tips

• Very low adoption (4 stars, 0 dependents) — pin the exact version and read the source before relying on edge behavior. Don't assume semver; check the commit history before upgrading.
• Result shape is strict — the builder maps columns positionally or by alias. Inconsistent result shapes across queries (a NULL alias, a driver that returns strings instead of ints) render as blank canvases rather than errors. Assert on toArray() in tests.
• DB dialect matters — date bucketing for time series differs between MySQL (MONTH()), Postgres (DATE_TRUNC()), and SQLite (strftime()). Nothing is normalized for you; the query is yours.
• Chart.js version skew — config shape changed significantly between v2 and v3/v4 (scales, tooltips, dataset options). Verify which version the examples target before copying them into your project.
• Escaping when embedding — always @json() the config in Blade. Hand-json_encode-ing inside a <script> tag produces quoting bugs that are painful to debug.
• Performance — the chart building is cheap; the query isn't. These run per request, so cache aggregate results for dashboard pages rather than regenerating them on every hit.
• Testing — assert against the returned config array (data.labels, data.datasets) instead of snapshotting HTML. It survives package upgrades far better.
• Extension point — the surface is small enough that composing (subclass or wrap ChartBuilder) beats forking if you need a custom dataset format.