Laravel Dashboard Chart Tile Laravel Package

Getting Started

This tile plugs a server-rendered chart into a laravel/dashboard (dmason30's fork of the spatie dashboard). It is a data-source + cache tile, not a "query the DB in the Blade view" tile — understand that split first, because it dictates almost every design decision you'll make with it.

Minimal path:

1. composer require fidum/laravel-dashboard-chart-tile
2. Publish the package config/views (check the readme for the exact --tag values; typically chart-tile-config and chart-tile-views) and, if you haven't already, the host dashboard config.
3. Confirm your scheduler runs the dashboard fetch command every minute — php artisan dashboard:fetch-data (or the package's own fetch command if one is registered; check vendor/fidum/laravel-dashboard-chart-tile/src and php artisan list | grep -i chart). Without a running scheduler the tile renders stale or empty data and you'll waste an hour blaming the chart library.
4. Generate a tile with the package's artisan generator (php artisan make:chart-tile / dashboard:make-chart-tile — verify exact signature with php artisan list), or hand-write a class extending the package's base chart tile and a class implementing its data-source contract.
5. Register the tile in config/dashboard.php with a data_position and a refresh_interval_in_seconds.
6. Hit /dashboard and verify the payload is cached (check the cache store, not just the browser).

First real use case: a "revenue last 30 days" line chart backed by an Eloquent aggregate. It exercises the whole loop — data source → cache → tile → refresh — in about 20 lines, and is the right thing to build before touching anything custom.

Implementation Patterns

Data source owns the query, the tile owns the presentation. Keep every DB::raw, groupBy, and date-boundary decision inside the data-source class. The tile class should be nearly declarative: chart type, labels, dataset mapping, options. This is what makes the tile testable — you can unit-test the data source against a factory-seeded DB without booting Livewire.

Treat the data source as a cache-warmer, not a request handler. Because the payload is produced by the scheduled fetch command, a data source that takes 8 seconds is fine; a data source that takes 8 seconds per browser refresh is not, and that only happens if you bypass the cache. Resist the urge to call the source directly in a Blade partial "just for now".

Pattern: parameterised tiles. If you need the same chart for several entities (per-tenant, per-project, per-currency), don't clone classes. Give the tile constructor/mount() a discriminator, use it in the cache key derivation, and register multiple entries in config/dashboard.php pointing at the same class with different constructor args. This is the single biggest maintainability win in a multi-tenant dashboard.

Pattern: composed chart payloads. When one chart needs several series with different grains (daily bars + 7-day moving average line), compute both in the data source and return a shape the tile maps one-to-one onto the chart series. Do not compute the moving average in Blade or in JS — it drifts from the cached payload and you lose the ability to assert on it.

Integration with the rest of the dashboard: the tile is a Livewire component under the hood, so wire:model-style live filters generally do not work the way people expect — a filter change requires a cache re-fetch, not a reactive re-render. If you need interactive filters, model them as separate registered tiles (or a small non-tile Livewire component) rather than trying to bolt reactivity onto a cached chart.

Local development: set refresh_interval_in_seconds low and run the scheduler in a separate terminal (php artisan schedule:work) while iterating, otherwise every data-source change needs a manual dashboard:fetch-data and a hard refresh.

Gotchas and Tips

• 6.3.0 is a constraint-only release. It adds Laravel 13.x support; there are no API, config, or view changes. No migration steps, no deprecations. The only action item is composer update fidum/laravel-dashboard-chart-tile and, if you pin laravel/framework or illuminate/* in a monorepo, confirming your own constraints allow 13.x. Laravel 11/12 users are unaffected.
• Stale cache after deploys. The cached payload survives php artisan optimize:clear only if your cache store is cleared too. If a deploy changes a data-source shape (new key, renamed label), old cached payloads will render broken charts until the next fetch. Clear the relevant cache keys — or bump a version segment in your cache key — as part of the deploy.
• Timezones. The fetch command runs in the app timezone; user-facing charts often need another. Decide once whether date bucketing happens in SQL (DATE(), DATE_TRUNC) or in PHP, and be consistent — mixing them produces off-by-one-day series that look like chart bugs.
• Empty series are not zero series. Return explicit zero-filled buckets from the data source. Most chart renderers will happily draw a misleading line straight through a gap otherwise, and "no data" silently looking like "flat growth" is the classic dashboard footgun.
• Cache key collisions. If the package derives the key from the tile class, two registered instances of the same class with different constructor args will fight over one cache entry. Verify the key includes your discriminator; if it doesn't, override the key method — that's the intended extension point.
• Publishing views is a fork, not a config toggle. Only publish the views if you genuinely need markup changes; otherwise you inherit manual merges on the next minor release. Prefer chart options (passed through to the JS library) over Blade edits for styling.
• Front-end assets. Charts are drawn client-side. If you publish/override the view, keep the package's asset includes intact, and remember Livewire navigation can re-mount the tile without re-running library init — a chart that renders on first load and blanks on wire:navigate is an asset-init problem, not a data problem.
• Debugging order of operations: (1) is the payload in cache and correct? (2) does the tile map it correctly? (3) does the JS render it? Jumping straight to (3) is the usual mistake.
• Watch the constraint window. This package tracks Laravel majors proactively (as 6.3.0 shows), so keeping Laravel current is low-risk; but the release cadence means you should pin a caret range and let minor bumps ride rather than freeze.