Charts Laravel Package

Getting Started

This package is a thin integration layer, not a standalone charting library. It gives you two halves that must be wired together:

• a backend data builder (LaravelEnso\Charts\Classes\Chart) that produces a Chart.js-compatible payload
• a Vue component (<chart>) that consumes it and hands off rendering to Chart.js

Install

1. composer require laravel-enso/charts
2. Confirm the service provider was auto-discovered (LaravelEnso\Charts\ChartsServiceProvider). In Enso apps this is normally already present via the Enso core, so you may only need the composer step.
3. Ensure chart.js is present in your frontend build. It's a peer dependency — the package does not vendor it. In an Enso app it's already in package.json; otherwise npm install chart.js and check the major version (Enso versions map to different Chart.js majors).
4. Publish config only if you need to change defaults: php artisan vendor:publish --tag=charts-config.

Where to look first

• README.md — short, but shows the fluent builder and the component tag.
• src/Classes/Chart.php — the entire backend API surface lives here; read it because the docs won't cover every method.
• resources/js/components/Chart.vue — shows exactly which props are read (data, and typically height/ratio), and which Chart.js options are passed through.
• config/ — global defaults (colors, responsive, legend).

First use case

A dashboard widget. In a controller (Enso SPAs typically return JSON to the Vue page):

use LaravelEnso\Charts\Classes\Chart;

$chart = (new Chart())
    ->type('bar')
    ->title('Monthly Revenue')
    ->labels(['Jan', 'Feb', 'Mar', 'Apr'])
    ->datasets([
        [
            'label' => 'Revenue',
            'data'  => [12_000, 19_000, 15_000, 22_000],
            'backgroundColor' => '#3c8dbc',
        ],
    ])
    ->responsive(true);

return ['chart' => $chart->get()];

On the Vue side:

<chart :data="chart" />

If that renders, you're done — everything else is tuning datasets and options.

Implementation Patterns

The controller-as-builder pattern The dominant workflow is to construct the Chart inline in a controller and return ->get() as part of the JSON payload. Keep the builder in the controller rather than a dedicated class for one-off charts; extract to a class once the same chart shape appears twice.

Extract a base chart class for reuse Because the builder is fluent and mutable, the cleanest reusable pattern is a small subclass or a factory method:

class RevenueChart extends Chart
{
    public function __construct(User $user)
    {
        parent::__construct();

        $rows = $user->sales()->monthlyTotals();

        $this->type('line')
             ->title('My Revenue')
             ->labels($rows->pluck('month')->all())
             ->datasets([[
                 'label' => 'Revenue',
                 'data'  => $rows->pluck('total')->all(),
                 'fill'  => false,
             ]]);
    }
}

Then return ['chart' => (new RevenueChart($user))->get()];. This is the pattern that scales across a dashboard with a dozen widgets.

Multi-dataset comparisons Pass an array of dataset arrays for grouped/stacked charts. Add stack per dataset (Chart.js option, passed through untouched) when you want stacked bars. The builder does not validate dataset shape, so keep it consistent — every dataset must have the same data length as labels.

Async refresh in the SPA Since Enso is an SPA, the common pattern is:

1. Fetch chart payload on mounted() via axios.get('/api/dashboard/revenue').
2. Bind to :data="chart".
3. On filter changes (date range, entity), refetch and reassign chart.

Reassignment works, but only because the component re-renders. See gotchas — you may need a :key bump to force Chart.js to rebuild.

Passing options through Chart.js options that the builder doesn't expose (tooltips, scales, animation) are usually passed by including them in the dataset or in a separate options prop, or by mutating the builder's internal array. Check Chart.vue for the exact prop name your version expects; Enso changes this between majors.

Integration with Enso pages On Enso page components, charts typically live as siblings to <page> and are fed from the page's state. If you're building a full Enso page, the controller returns the chart payload alongside the page data, and the Vue component destructures it — no separate request needed. Prefer this over a second axios call where possible.

Gotchas and Tips

This is an Enso-ecosystem package, not a generic Laravel package. It assumes Enso's Vue app structure (global component registration, Bulma styling, Enso's build pipeline). Dropping it into a stock Laravel + Inertia or a differently-configured Vue app will require manually registering the component and handling the CSS.

Chart.js major version mismatch is the #1 failure. The wrapper passes options straight to Chart.js, and Chart.js v2 vs v3+ differ in scales, responsive, and tooltip config. If your chart silently renders blank or throws, check package.json for the installed Chart.js version against the package's version constraint first.

Collections don't serialize the way you expect. labels() and dataset data must be plain arrays. pluck()->all() is fine; passing a Collection or a query builder result through will produce an object, and Chart.js will render nothing or garbage. Always ->all() / ->toArray().

Call order matters for the builder. Configure type, labels, and datasets before get(). The builder is mutable and get() snapshots state — if you call get(), then add a dataset, you need another get().

Reactive updates may not redraw. Chart.js binds to a canvas imperatively; replacing data doesn't always re-render. Force it with a :key bound to a revision counter, or call chart.destroy() before rebuilding. This is a recurring footgun when a date filter changes but the canvas stays stale.

Default colors are minimal. The builder won't hand you a palette for N datasets. For anything beyond 2–3 series, define backgroundColor/borderColor per dataset explicitly or you'll get Chart.js defaults that clash with Enso's theme.

Debugging: dump the payload, not the chart. When a chart is blank, dd($chart->get()) in the controller and verify the JSON has type, data.labels, and data.datasets[0].data. If that's correct, the issue is on the Vue side (prop name, Chart.js version, canvas sizing). If it's wrong, it's builder configuration. This split saves time.

Extension points. Two clean ones: (1) subclass Chart and pre-configure shared defaults in the constructor; (2) publish and edit the config to change responsive/legend/color defaults globally. Avoid patching the Vue component — it's overwritten on updates.

Low star count / small community. Expect to read source for anything undocumented, and pin the version in composer.json. The package is mature within Enso but not battle-tested outside it, so treat version bumps as potentially breaking and test charts visually rather than relying on feature tests.