Laravel Relational Metrics Laravel Package

Technical Evaluation

What it is (as scoped): a thin convenience layer over Eloquent's query builder that produces metric values (counts, aggregates) scoped to a model, to a model's relations, or to a set of conditions. The value proposition is developer ergonomics: turn multi-condition aggregate queries into a fluent, reusable call instead of hand-written selectRaw / withCount chains.

Architecture fit: Reasonable. It appears to be a standard Laravel package — service provider, config publish, likely a trait or facade consumed from model or controller/service code. That means it sits on the read path and doesn't require a schema change, a queue, a new datastore, or a sidecar. It composes with the existing ORM rather than replacing it, so it's low-coupling by construction. It is not an analytics or reporting platform; treat it as sugar over SQL aggregates, appropriate for admin dashboards, KPI cards, gating rules, and per-tenant counters — not for high-cardinality, ad-hoc, or historical reporting.

Integration feasibility: High in isolation — one Composer dependency, one config file, one trait. The real feasibility question is version fit, not effort.

Technical risk (material):

• Abandonment risk. Last release 2022-03-21, 26 stars, effectively a single-maintainer project. It predates Laravel 10/11/12. Eloquent's internals around relations, aggregates, and query grammar have moved; unverified compatibility is the dominant risk, not code quality.
• Correctness risk over availability risk. Metric libraries fail silently — wrong numbers, not exceptions. Global scopes, soft deletes, tenant scoping, and polymorphic relations are the classic sources of scope leakage that inflate or deflate counts without any error surfacing.
• Injection surface. Any package that accepts column/relation names as strings to build SQL needs to whitelist them. If we ever pass user-influenced identifiers, that's a review gate.
• Build-vs-adopt. Laravel now ships withCount, withSum/withAvg/withMax, whereRelation, and whereHas natively. A large share of this package's stated surface may be reproducible in ~30 lines of in-house query-object code we own outright. That reframes the decision from "integrate a dependency" to "avoid a dependency."

Key questions to answer before commitment:

1. Which Laravel and PHP versions are actually supported — does it install and run clean on our target (Laravel 10/11+)? Is composer require blocked by constraints?
2. Does a metric compile to a single SQL statement, or does it fan out into N queries per relation?
3. How does it handle soft deletes, global scopes, and multi-tenancy — inherited or bypassed?
4. Which relation types are supported (BelongsToMany with pivot conditions, HasManyThrough, MorphMany)?
5. Is there a test suite and CI we can use as a regression harness?
6. License terms and whether a fork is permitted.
7. Is there any caching, TTL, or invalidation, or is caching entirely our responsibility?

Integration Approach

Stack fit: Native Laravel/PHP, Composer-installed, no runtime (no Node, no queue worker, no new service). Fits our stack profile with essentially zero platform work — the friction is entirely version compatibility and ownership.

Migration path: None required. This is additive: adopt on one surface, and removal is a composer remove plus rewriting call sites, provided we isolate it behind our own boundary.

Compatibility: Pin an exact version, do not use a floating constraint. Run the install as a spike against our actual Laravel version and PHP version before any design work. If constraints conflict, decide immediately between (a) fork-and-patch, (b) vendor the handful of useful methods, or (c) abandon and use native Eloquent — do not burn time on constraint gymnastics for a 26-star package.

Sequencing:

1. Spike (1–2 days). Fresh branch, install, reproduce 3–5 representative metrics from our real roadmap against a staging-sized dataset. Capture the generated SQL for each (toSql/query log) and review for full scans and scope leakage.
2. Decision gate. If the spike is clean, proceed; if not, fall back to native Eloquent query objects. Write the comparison down — this is the artifact that justifies the dependency.
3. Wrap, don't scatter. Put all usage behind an internal interface (e.g., a MetricsRepository / query-object layer) so no controller, Blade template, or Livewire component calls the package directly. This is the single most important step: it converts an abandoned package from an outage risk into a reimplementation task.
4. Pilot on one non-critical dashboard. Instrument it: query count, p95 latency, and a manual reconciliation against a known-good selectRaw baseline.
5. Expand by demand. Only after the pilot proves numbers match. Do not standardize the team on it while it's unproven.
6. Exit plan on file. Document the 3–5 call sites and their native-Eloquent equivalents so removal is a known-cost task, not an archaeology project.

Compatibility guardrail: add the package to a dependency-watch list and run composer audit in CI; a stale package with no security policy is a quiet liability.

Operational Impact

Maintenance: Effectively zero upstream maintenance. We inherit the code. Budget an owner (one backend engineer, part-time) with a standing expectation of a fork — patching a Laravel-version incompatibility or a scope bug ourselves is a plausible, not hypothetical, event. That's cheap for 500 lines of query sugar; it would be disqualifying for an auth or payments library.

Support: No vendor, no SLA, no security contact. Support model is "read the source." Acceptable for an internal read-path convenience; unacceptable anywhere it gates money movement, billing, entitlements, or compliance reporting unless we own the fork and the tests.

Scaling: The performance ceiling is the underlying SQL, not the package. Watch for:

• Aggregates over large tables without supporting composite indexes — the library won't add them;
• Per-row metric calls inside loops (classic N+1), which will look fine in dev and collapse in production;
• Conditional metrics generating wide CASE WHEN expressions or multiple subqueries per page load;
• Repeated identical aggregates across a dashboard — needs a caching layer (Redis, short TTL) that the package almost certainly doesn't provide. If a dashboard needs more than a handful of these per request, denormalize into a summary/counter table rather than scaling the query layer.

Failure modes (ranked by likelihood × damage):

1. Silently wrong numbers from ignored global scopes, soft deletes, or tenant filters — highest damage because it erodes trust in dashboards and can leak cross-tenant counts. Mitigation: reconciliation tests against a known-good baseline in CI.
2. Breakage on Laravel upgrade — install-time constraint conflict (loud, cheap) or runtime behavior change (quiet, expensive). Mitigation: pinned version, upgrade-gated integration tests.
3. Query-performance regression as data grows — no error, just a dashboard that goes from 200ms to 8s. Mitigation: p95 alerting on the pilot surface.
4. SQL identifier injection if relation/column names are ever user-supplied. Mitigation: whitelist at the wrapper boundary.
5. Date/timezone edge-case bugs in conditional metrics ("last 7 days" boundaries). Mitigation: explicit timezone handling in the wrapper, not the call site.

Ramp-up: Low. A mid-level Laravel developer is productive in a few hours — the API is idiomatic Eloquent. The real ramp-up cost is not learning the package but debugging it: teaching the team to dump generated SQL and reconcile totals. Include that in the pilot's documentation, not a slide deck.

TPM recommendation: Adopt conditionally and narrowly — pilot on one non-critical, read-only dashboard, behind an internal wrapper, pinned and watchlisted, with a documented native-Eloquent fallback. Given Laravel's native aggregate support and the package's staleness, treat "we reimplemented the 40 lines we actually needed" as a fully acceptable outcome, and be prepared to make that call at the spike gate rather than after the dependency has spread.