Amcharts Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — there is no AmChartsServiceProvider, no auto-discovery, and no Blade directives. Treat it as a reference implementation first and a dependency second.

1. Inspect before installing. Clone or browse the repo and look at:
   • src/KalamurdaAmChartsBundle.php (or similar *Bundle class) — shows the DI extension entry point.
   • src/DependencyInjection/ — the service definitions and config tree you'd need to replicate in a Laravel provider.
   • src/Resources/views/ — the Twig templates that actually emit chart markup/JS.
   • src/Resources/config/services.* — which services are public and what they depend on.
2. Composer install is possible but will pull Symfony components (symfony/http-kernel, symfony/dependency-injection, symfony/twig-bridge). Check the composer.json constraints against your PHP version — anything published in 2021 typically targets PHP 7.x/8.0 and Symfony 4/5.
3. First use case: pick the smallest chart (a bar or line chart) and drive it entirely from raw amCharts config JSON in a Blade component. Only reach for the bundle's classes if they give you a builder/serializer you can instantiate standalone (i.e., without the container).

Realistic first step in Laravel:

// app/Support/AmCharts.php — a thin wrapper, not the bundle's container wiring
$chart = [
    'type' => 'xy',
    'data' => $rows,
    'series' => [/* ... */],
];
return view('charts.bar', ['config' => $chart]);

{{-- resources/views/charts/bar.blade.php --}}
<div id="chart" style="width:100%;height:400px"></div>
<script src="https://cdn.amcharts.com/lib/5/index.js"></script>
<script>
  am5.ready(function () {
    const root = am5.Root.new("chart");
    // hydrate from @json($config)
  });
</script>

If the repo's builder classes are cleanly decoupled, you can new them directly from a Laravel service — that's the only sensible "leverage" path.

Implementation Patterns

Pattern 1 — Config builder, not renderer. Use the bundle's PHP chart objects as DTOs to shape config server-side, then hand JSON to the client. This matches the package's likely design (Symfony bundles of this era typically build chart arrays in PHP and render via Twig). Map it to a Laravel ChartData value object:

class ChartData implements JsonSerializable
{
    public function __construct(
        public array $data,
        public array $series = [],
        public array $axes = [],
    ) {}

    public function jsonSerialize(): array
    {
        return ['data' => $this->data, 'series' => $this->series, 'axes' => $this->axes];
    }
}

Bind it in a service provider:

$this->app->singleton(ChartFactory::class, fn ($app) => new ChartFactory(
    config('charts.default_theme', 'light')
));

Pattern 2 — API endpoint + JS fetch. The most portable workflow: a controller returns chart config, the browser renders it. Avoids Blade/Twig coupling entirely and works with Inertia, Livewire, or Alpine.

Route::get('/charts/revenue', fn () => response()->json(
    ChartFactory::revenue()->jsonSerialize()
));

Pattern 3 — Blade component wrapper. If you port the Twig template, turn it into <x-amchart :config="$config" />. Keep the JS init in a single resources/js/amcharts.js module so Vite can bundle the amCharts npm package instead of a CDN script.

Pattern 4 — Livewire dynamic charts. Emit dispatch('chart-updated', config: @js($config)), listen in JS, and call chart.data.setAll(newData) or series.data.setAll(...). Don't re-init the chart root on every update — amCharts leaks instances otherwise.

Integration tips

• Publish/host amCharts assets via Vite (npm i @amcharts/amcharts5) rather than the bundle's Resources/public assets, which won't be exposed by Laravel.
• Put the chart config behind a ChartPresenter so controllers stay thin.
• If you need Twig templates from the bundle, use twigbridge only as a last resort; porting a 30-line template is cheaper than a cross-framework shim.
• Version-pin amCharts and record it in config — the bundle's assumed API may be amCharts 4, while amCharts 5 changed the instantiation model (am5.Root, am5xy.XYChart) substantially.

Gotchas and Tips

• Framework mismatch is the main pitfall. Expect Class 'Symfony\Component\HttpKernel\Bundle\Bundle' not found unless Symfony components are installed, and even then the bundle won't auto-register in Laravel. You must manually translate Extension::load() into a ServiceProvider.
• No maintainer activity since 2021. Four stars, zero dependents, last release Oct 2021. Assume PHP 8.2+ deprecation notices, missing symfony/* ^6/^7 support, and amCharts 5 incompatibility. Budget time for a fork.
• Twig extension in a Blade app. The bundle's rendering helpers (likely {{ amchart(...) }}) are unavailable. Anything that returns Twig\Markup or relies on Twig\Environment will fail — refactor to plain arrays/strings.
• Asset publishing. Symfony's assets:install has no Laravel equivalent; Resources/public is invisible to public/. Copy manually or, better, use npm.
• Config quirks. Symfony's Configuration tree uses ->children()->... semantics; Laravel's config() merging is flat and will not validate types. If you port the tree, validate with a config/charts.php + a small schema check, or you'll get silent empty-series charts.
• Container compilation errors are opaque in Laravel. If you try to bridge services, wrap registration in a try/catch during boot and Log::debug the failing service id; check for public: false services the bundle expects to inject.
• Debugging charts. 90% of blank-chart issues are invalid config, not PHP. dd(json_encode($config)), paste into an amCharts codepen, and diff against the version's docs. Log the payload size — large datasets silently stall rendering.
• Extension points if you must keep it. Decorate/replace the chart builder service rather than editing vendor code; keep a ChartRendererInterface in your app so you can swap the bundle out later.
• Recommendation for a Laravel team: skip the dependency. Read its source for structure, then implement a ~150-line ChartFactory + Blade component. The package's value here is as a spec for chart config shape, not as a runtime dependency.