Laravel Metrics Laravel Package

Product Decisions This Supports

• Build vs. buy for the first analytics surface. Most Laravel products need the same v1 dashboard: signups per month, order volume per week, revenue trend, "vs. previous period" deltas. This package collapses that from a 2–4 week engineering task (SQL date bucketing, driver quirks, gap-filling, percent deltas) into a fluent query layer. That is a direct trade of ~$8–15k of build effort for a 30-minute composer install and a spike.
• Roadmap sequencing: dashboards before BI tooling. Because the cost of a credible internal dashboard drops, you can ship customer- or ops-facing metrics in the current cycle instead of deferring to "after we buy a BI tool." It also delays or removes a $500–2,000/month analytics vendor line item for early-stage products.
• Feature scoping for reporting requirements. The API surface maps almost 1:1 to PRD language: aggregate (count, sum, average, max, min) × period (byDay/Week/Month/Year, between, from) × output (trends, metrics, metricsWithVariations in absolute or percent). When a stakeholder asks "can we show change vs. last month?", the answer is a parameter, not a ticket.
• Data-quality decisions. fillMissingData with label auto-discovery forces an explicit product decision we usually forget: what does a zero-activity day look like on the chart — a gap, a zero, or carried-forward? Having it as a named toggle means it gets decided in the PRD rather than discovered in a bug report.
• Segmentation and breakdowns. labelColumn plus groupData(['pending','delivered','cancelled']) supports the "stacked bar by status" requirement without a second round of engineering. This is the difference between a dashboard that ships and one that ships and immediately gets a v2 request.
• Multi-tenant / scoped views cheaply. LaravelMetrics::query(Model::query()->where('team_id', ...)) means per-customer dashboards are scope composition, not new infrastructure — a lever for packaging a "reporting" tier.
• Support-cost and localization decisions. Day/month label translation via config('app.locale') removes a small but recurring class of "our German customers see English months" defects, which matters if you sell into non-English markets.

When to Consider This Package

Adopt when most of these hold:

• The product is a Laravel 11.x or 12.x monolith with metrics living in the same MySQL/PostgreSQL/SQLite database as the operational tables (the 4.x branch is required for Laravel 13 — confirm your upgrade path before committing).
• Metrics are aggregate-over-time questions ("how many", "how much", "trend vs. last period") rather than event-level ones ("which users did X then Y").
• Tables are small-to-moderate and the date/status columns are or can be indexed. No pre-aggregation layer exists or is needed yet.
• The consumers are internal ops, admins, or a modest number of customers — not an analyst who expects to slice by arbitrary dimensions.
• You are willing to wrap it in your own thin service/adapter class so the call sites don't leak the package API into controllers and views.

Look elsewhere when any of these hold:

• Maintainer-risk tolerance is low. 138 stars, zero dependents, and effectively a single maintainer is the dominant risk. A dashboard is a visible, load-bearing feature; a stalled fork is a business problem, not a dependency problem. Treat this as "we may own this code" and price the abstraction layer accordingly.
• You need true product analytics (funnels, retention cohorts, event streams, user-level drilldown) — this is not that tool, and stretching it into one will cost more than adopting a real one.
• Scale is already painful. Every call is a live aggregate query. If a dashboard load touches millions of rows or refreshes on every page view, you need materialized views/pre-aggregation, and this package adds latency without solving it. There is no documented caching story here.
• You need complex joins, window functions, or non-standard grouping. The custom-table and labelColumn escape hatches cover simple cases only; past that you are writing raw SQL anyway.
• Version/branch confusion is unacceptable to your team. The project ships DB/feature parity across 2.x/3.x/4.x branches tied to Laravel versions. That is workable, but it means your composer constraint and your Laravel upgrade are coupled — verify the target branch actually has the features you scoped.
• Compliance or audit requirements demand vetted, supported dependencies with a security SLA. MIT + a personal email for security reports is not that.

How to Pitch It (Stakeholders)

To executives (30 seconds): We need a first dashboard for [customers/ops] and the honest build estimate is 3–4 weeks of engineering. This MIT-licensed Laravel package covers roughly 80% of that — aggregation, time-bucketing, gap-filling, and "vs. previous period" deltas — across MySQL, Postgres, and SQLite. Recommendation: a two-day spike now, and if it holds, we ship the dashboard this cycle and defer the BI tool purchase. Cost is $0 in licensing; the real cost is the half-day we spend wrapping it behind our own interface so we're not locked in.

To engineering (the ask): Prototype the three metrics on our actual schema for one day, then answer two questions: (1) does the generated SQL use our indexes, and (2) is the HasMetrics / LaravelMetrics::query() API clean enough to sit behind a MetricsService we own? If yes, we adopt with a mandatory adapter boundary and a pinned branch matching our Laravel version — no direct package calls from controllers. If the spike shows table scans or fights our query scopes, we stop and build the ~200 lines ourselves.

Risk statement to state out loud: Low adoption, single maintainer, and branch-per-Laravel-version means we should assume we may fork. The adapter boundary and a pinned, tested version are non-negotiable conditions of adoption — not because we expect failure, but because a dashboard silently breaking after a dependency bump is a customer-visible incident.