Laravel Highcharts Laravel Package

Getting Started

composer require apility/laravel-highcharts
php artisan vendor:publish --provider="Apility\\LaravelHighcharts\\HighchartsServiceProvider"

Then work through these three files before writing any chart code:

1. config/highcharts.php — the published defaults (global chart options, script/asset settings). This is where 90% of "why does my chart look wrong" questions are answered.
2. src/ — the package is small at v0.3.x; read the service provider and the main chart/options class end-to-end in ten minutes. You will spend more time guessing than reading.
3. README.md + the tagged diff (https://github.com/apility/laravel-highcharts/compare/v0.2.0...v0.3.0) — see the Gotchas section, the v0.3.0 release notes contain no changelog body, so the diff is your only source of truth for what moved.

First use case — a single chart in a Blade view:

// app/Http/Controllers/DashboardController.php
public function index()
{
    return view('dashboard', [
        'chart' => [
            'chart' => ['type' => 'line'],
            'title' => ['text' => 'Signups'],
            'xAxis' => ['categories' => ['Jan', 'Feb', 'Mar']],
            'series' => [['name' => 'Signups', 'data' => [3, 7, 12]]],
        ],
    ]);
}

Render it, confirm the container element and the Highcharts script both appear in the DOM, then iterate on the options array. Get one chart fully working before wiring up a second — the package's value is in option assembly and asset wiring, not in abstraction, so validate the raw Highcharts option shape early.

Implementation Patterns

Keep option arrays out of Blade. Build them in a dedicated class (app/Charts/*.php) or a controller method that returns an array, and hand the array to the view. Highcharts options are deeply nested; inlining them in templates makes them untestable and unreadable. A plain PHP class with a toArray(): array method plus a feature test asserting key structure is the cheapest thing that scales.

Use config defaults for house style, not per-chart styling. Put colours, chart.backgroundColor, credits, lang, and export-button defaults in config/highcharts.php. Per-chart arrays should then only carry data plus genuinely chart-specific overrides. This keeps every chart in the app visually consistent and gives you one place to change when design asks for it.

Merge, don't duplicate. If the package exposes an options/merge helper, use it to layer: package defaults → config defaults → chart-specific array. If it doesn't, a small array_replace_recursive wrapper in your own code is fine — but be aware recursive merge is wrong for lists (series, colours), where you want replacement, not index-wise merging.

Dynamic data via a JSON endpoint. For dashboards that filter or reload, expose a route returning response()->json($chartOptions) and instantiate/update the chart client-side with that payload. This avoids re-rendering the whole Blade view and is the pattern that survives contact with real dashboards.

Testing. Assert on the option array, not the rendered HTML: data lengths, series names, category ordering, and any computed aggregations. A single smoke test that the view renders a container with the expected id catches most integration breakage on package upgrades.

Blade integration. If the package ships a component or directive for rendering, prefer it over hand-writing the container plus script tag — it keeps the container id and the JS init call in sync, which is the single most common source of "chart doesn't appear" bugs.

Gotchas and Tips

v0.3.0 ships with an empty release-notes body. The notes are just a compare link, so there is no stated list of breaking changes. Treat every 0.x bump as breaking: pin the exact version ("apility/laravel-highcharts": "0.3.0"), read the tag diff before upgrading, and cover your chart output with the array-shape tests above so an upgrade failure surfaces in CI rather than in a dashboard.

0.x semver means no backwards-compatibility promise. Config keys, class namespaces, and method signatures can move between minor versions. Isolate the package behind your own thin wrapper (one class that builds options and one Blade partial that renders) so a rename in the package touches two files instead of forty.

Highcharts licensing is your problem, not the package's. Highcharts is free for personal/non-commercial use and requires a commercial licence otherwise. This is a legal obligation that no Laravel wrapper can abstract away — confirm the licence position before shipping to a client, and note that the licence is per-seat, not per-application.

Asset source matters. Whether the Highcharts JS comes from a CDN or published local assets is a config decision with real consequences: CDN is faster to set up but is a runtime dependency and may conflict with CSP or offline/air-gapped environments; local assets need vendor:publish re-run on upgrade and are easy to leave stale. Check which the config selects and make it explicit per environment.

php artisan config:cache after touching the config file. Laravel caches config in production; edits to config/highcharts.php silently do nothing until the cache is cleared. Also re-run config:clear when switching branches locally.

Escaping when injecting options into a script tag. If you are serialising the array yourself, use json_encode($options, JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT) (or @json in Blade). Raw json_encode on user-supplied labels is an XSS vector via </script>.

Debug in the browser, not the PHP side. When a chart renders blank: console.log the options object, then paste it into the Highcharts demo/API docs to confirm it is a valid option tree. Nine times out of ten the PHP is fine and the issue is a missing container id, a script loaded after init, or a null data series.

No server-side rendering. If you need charts in PDFs or emails, plan for a separate renderer (headless browser or Highcharts Export Server). Do not assume this package covers it.

Extension point to watch. The config file is the intended customisation surface. If you find yourself subclassing package internals, that is a signal to file an issue upstream rather than fork — at 0.x the maintainers are likely still receptive, and internal classes are the most likely thing to be renamed in 0.4.