Filament Highcharts Laravel Package

Getting Started

v1.1.1 is a patch release; the provided notes only link to the changelog comparison, so there is no evidence of breaking changes or new features. Treat it as a low-risk upgrade, but review the diff before production if you depend on undocumented internals.

Start by installing the package with Composer, registering its plugin/service provider in the relevant Filament panel, and publishing/rebuilding assets as described in the README. Look first at:

• The package README and any example widget
• config/filament-highcharts.php, if present
• vendor/koassi-akakpo/filament-highcharts
• The package tests/examples for the expected widget base class and options method

First practical use case: replace a simple stat or table widget with a dashboard chart such as “Orders last 30 days.” Subclass the package’s chart widget, return a Highcharts options array, and register the widget on a dashboard or page. Confirm the package’s Filament version compatibility before adopting it across a panel.

Implementation Patterns

Keep chart configuration inside dedicated widget classes. The usual shape is a method that returns a Highcharts options array:

protected function getOptions(): array
{
    return [
        'chart' => ['type' => 'column'],
        'title' => ['text' => 'Orders'],
        'xAxis' => ['categories' => $this->categories()],
        'series' => [
            ['name' => 'Orders', 'data' => $this->series()],
        ],
    ];
}

Use the exact method/class names from the package README; the important pattern is “PHP array in, Highcharts config out.”

Day-to-day patterns:

• Aggregate in SQL, not in PHP. Use groupBy, count, sum, and date buckets so Livewire does not carry large datasets.
• Keep data preparation in private methods or a query/service class. The widget should mainly map query results to Highcharts series.
• Use public widget properties or Filament page filters to drive chart state. When filters change, Livewire re-renders and the options array is rebuilt.
• Prefer one widget per chart. For dashboards with several charts, compose multiple widgets or a container widget with partials rather than one giant options array.
• Format labels, currencies, and dates server-side where possible. Pass plain strings/numbers into the options array.
• Add focused tests around the options/data methods and a Livewire render test for the widget. You usually do not need browser-level tests for static chart config.

Gotchas and Tips

• Highcharts licensing: Highcharts is not free for all commercial uses. Confirm the license before shipping it in a client product.
• Callbacks are not PHP closures: Highcharts formatter/callback functions cannot be serialized through a normal PHP options array. Use server-side formatting, Highcharts string-based options where supported, or custom JS in the widget view.
• Asset loading and CSP: Filament asset publishing and Content Security Policy can affect Highcharts. If charts are blank, check browser console, published assets, php artisan filament:assets, and CSP rules.
• Livewire payload size: Do not load thousands of points into a Livewire component. Aggregate, downsample, or fetch chart data from a dedicated endpoint for large datasets.
• Chart lifecycle: If options change frequently, verify the package updates or reinitializes the chart correctly. For complex real-time behavior, consider a custom Alpine/JS component instead of forcing everything through Livewire re-renders.
• Dates and timezones: Normalize timestamps before passing them to Highcharts. Avoid Carbon objects in the options array; use ISO strings or timestamps intentionally.
• Upgrade path for v1.1.1: Run composer update, clear caches, rebuild Filament assets, and smoke-test dashboards. No migrations or breaking changes are indicated by the release notes, but the changelog diff is the source of truth.
• Extension points: Prefer subclassing the provided widget, publishing/overriding views, and using package config before editing vendor files. If you need custom JS, keep it in your app’s assets and attach it through the widget view.