Filament Simple Stats Laravel Package

Technical Evaluation

Architecture fit

• Thin, declarative adapter: SimpleStat::make(Model::class) wraps Filament's native Stat widget and an inlined flowframe/laravel-trend engine. No service provider to configure, no migrations, no published config, no routes — it is a view-layer convenience, not an infrastructure dependency.
• Consumed entirely inside a getStats() method on an existing Filament Widget, so it composes with the dashboard architecture already in place rather than introducing a parallel reporting stack.
• "Opinionated" is the defining constraint: fixed period helpers (last30Days()), fixed granularity (dailyCount, dailySum), and auto-computed period-over-period trends. Teams needing weekly/monthly cohorts, multi-series charts, or custom formatting will outgrow it quickly.
• Fits best in internal admin panels and MVP dashboards; poor fit as the basis of a customer-facing analytics product.

Integration feasibility

• composer require spatie/filament-simple-stats and two lines of widget code — the smallest integration surface I have assessed in this category. A working spike is a half-day including review.
• 1.2.1 added Eloquent Builder support plus where() scoping, which is the escape hatch that makes it viable for multi-tenant and per-user views (->where('user_id', auth()->id())).
• withoutTrend() and invertTrendColors() cover the two most common semantic objections (no comparison baseline; metrics where down is good), so the opinionated defaults are negotiable at the widget level.
• Exit cost is near zero: the API is one line per metric, so replacing it with a hand-rolled Stat widget is a contained refactor, not a migration.

Technical risk

• Low code risk, moderate lifecycle risk. 28 stars and 0 dependents means effectively no external validation — you would be an early adopter relying on the Spatie brand, not on community hardening.
• Version coupling is the real hazard: the changelog shows a hard bump of filament/widgets from ^4.0 to ^5.2 and a Laravel 13 track. Filament's package split and major cadence mean your Filament upgrade and this package's upgrade must be sequenced together.
• laravel-trend was inlined in 1.2.0 — good for dependency count, but it also removes your ability to patch trend behavior independently.
• Correctness of the trend math (equal-length prior window, endOfDay handling of "today", timezone/DST boundaries) is asserted by the package, not configurable. Verify against raw SQL before trusting the arrow direction in a demo.
• Query cost is undocumented: each widget implies current-period and prior-period aggregates on page load.

Key questions

• Which Filament major is our target, and does the pinned release support it? (Widget v4 vs v5 is a breaking boundary.)
• What timezone and DST assumptions drive the daily buckets, and does that match our reporting definition of a "day"?
• Is the prior comparison window fixed-length and inclusive of today, matching how we state period-over-period change?
• What indexes exist on created_at plus each filtered column for the models we plan to surface?
• Do we need panel-level authorization or per-tenant scoping beyond where()?
• Who owns the fork if Spatie archives the repo?

Integration Approach

Stack fit

• Requires a Laravel app already running a Filament panel with Eloquent models exposing timestamped rows. No queue, cache, or storage prerequisites. Compatible with the Laravel 12/13 support line declared in the changelog.
• Zero runtime footprint: no bootstrapping, no config publish, no env vars — installs cleanly into an existing CI and deployment pipeline.

Migration path

• Purely additive. No schema change, no backfill, no data movement; rollback is composer remove plus deleting the widget class.
• Recommended fallback path: implement one metric as a native Filament Stat widget with the equivalent query first, then swap in SimpleStat and diff the numbers. This produces the ground-truth baseline for trend validation at almost no cost.

Compatibility

• Pin the package version alongside the Filament major in composer.json and let Dependabot surface bumps as reviewable PRs (the repo already runs this cadence).
• Add a CI matrix entry covering the exact Laravel/Filament pair we ship on; the package's own tests passing does not guarantee our combination renders.
• Treat any major-version PR from this package as a UI regression test trigger, not a routine merge.

Sequencing

1. Spike branch: install, build one dashboard widget with 2–3 stats, confirm rendering and trend arrows in the panel.
2. Validate: compare each figure and percentage against hand-written SQL for the same window; specifically check today's partial day and the boundary at midnight.
3. Index review on the target models before the widget ships to real traffic.
4. Expand to the full metric set, applying where(), withoutTrend(), and invertTrendColors() per metric semantics.
5. Document the metric definitions (window, timezone, direction-of-good) next to the widget — this is the artifact that prevents future "the dashboard is wrong" tickets.

Operational Impact

Maintenance

• Low ownership burden: MIT license, released changelog, automated dependency and code-style workflows, and a codebase small enough to fork and maintain internally if abandoned. Estimate a few hours per year in routine version bumps, concentrated entirely around Filament major upgrades.
• The hidden maintenance cost is definitional, not technical: every metric needs a documented window and polarity, or the same number will be argued about quarterly.

Support

• Community-only: GitHub issues, no SLA, no vendor contract. With 28 stars, expect unanswered edge-case questions and self-service debugging.
• Assign one backend developer fluent in Filament as owner. Ramp-up for that person is measured in hours; for anyone else, the README is a single page and sufficient for reading, not for diagnosing trend discrepancies.

Scaling

• Each widget issues aggregate queries per render — expect roughly two per widget (current + prior period). A six-widget dashboard is a dozen aggregates per page load; fine at thousands of rows, visibly slow at tens of millions.
• Mitigations, in order of cost: composite indexes on (filter_column, created_at); narrow the window; cache widget output; move heavy metrics to a scheduled snapshot table. Note the package offers no built-in caching, so any of these is custom work.
• Per-user dashboards with row-level where() scoping multiply query count by concurrency; watch the database before the panel, not the PHP layer.

Failure modes

• Missing index → dashboard latency spikes or timeouts under concurrent admin usage; degrades the whole panel, not just one card.
• Timezone mismatch → "daily" buckets shifted by hours, producing stable-but-wrong counts and misleading trend arrows.
• Zero or near-zero prior period → percentage change undefined or absurd (e.g., "+∞%"); needs a defined fallback.
• Un-inverted polarity → error rate and cost metrics render green when rising; a silent, credibility-damaging error.
• Silent breakage on a Filament major bump → widget renders blank or unstyled with no exception, so it passes a smoke test.
• Orphaning → no security advisories from a dormant repo; mitigated by the small, forkable surface.
• Net assessment: low-risk, low-ceiling dependency. Adopt for internal dashboards where the metric set matches its opinionated defaults; do not adopt where reporting is a customer-facing product requirement.