Weave Code
Laravel Relational Metrics Laravel Package
syrian-open-source/laravel-relational-metrics
A Laravel package for calculating relational metrics from Eloquent models, letting you define and query counts, sums, averages, and other aggregates for dashboards, reports, and insights with clean, reusable code.
This package will help you to make your metrics easier, You could get metrics about your Models, Models depending on their relations, or even metrics about your models depending on multiple conditions!!
Frequently asked questions about Laravel Relational Metrics
- Does laravel-relational-metrics support Laravel 10, 11 and 12?
- The package's last tagged release was in March 2022, which predates Laravel 10, 11 and 12, so native compatibility with current framework versions is unverified. Eloquent internals around relations, aggregates and query grammar have changed since then. Pin an exact Composer version and run a short spike install against your actual Laravel and PHP versions before committing to any design work. If the constraints conflict, choose quickly between forking, vendoring the useful methods, or using native Eloquent instead.
- How do I install syrian-open-source/laravel-relational-metrics?
- It is a standard Composer package installed with composer require syrian-open-source/laravel-relational-metrics, with a service provider and a publishable config file following normal Laravel package conventions. Avoid a floating version constraint and pin the exact release you tested. If Composer reports a dependency conflict on your Laravel version, treat that as a decision point rather than something to work around. The integration itself is additive: no schema change, no queue, no extra service.
- How is this different from Laravel's built-in withCount and withSum?
- Modern Laravel already ships withCount, withSum, withAvg, withMax, whereRelation and whereHas, which cover a large part of this package's surface. The package's value is developer ergonomics: it turns multi-condition aggregate queries into reusable, named metric definitions instead of hand-written selectRaw or withCount chains scattered through controllers. That matters most when the same metric is needed in several places, such as dashboards, KPI cards, gating rules and per-tenant counters. If you only need one or two aggregates, roughly thirty lines of in-house query-object code may be the better trade.
- Can I define a metric based on multiple conditions?
- Yes, that is the core of the package's pitch: metrics scoped to a model, to a model's relations, or to a set of conditions. You define the metric once and reuse it, rather than rewriting the same conditional aggregate in several places. That reuse is the main reason to accept a dependency here, so validate it against your real roadmap metrics during the spike. Capture the generated SQL for each one so you can see exactly what conditions end up in the where clause.
- Does it run one SQL query per metric or does it cause N+1 queries?
- Whether a metric compiles to a single aggregate statement or fans out into additional queries per relation is something you must verify on your own data, not assume. Log the query count and inspect toSql output for three to five representative metrics from your real roadmap against a staging-sized dataset. Watch for full table scans and for relation aggregates that fire once per row. Those results also double as a regression harness you can compare against hand-written SQL.
- How does it handle soft deletes, global scopes and multi-tenancy?
- This is the highest-risk area and must be tested explicitly, because metric libraries fail silently with wrong numbers rather than 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. Run the same metric through the package and through a hand-written query in a tenant-scoped and soft-deleted dataset, and confirm the numbers match. If scopes are bypassed rather than inherited, isolate the package behind your own boundary or drop it.
- Which relation types are supported, such as BelongsToMany or MorphMany?
- The package advertises metrics on models depending on their relations, but the exact coverage of BelongsToMany with pivot conditions, HasManyThrough and MorphMany is not something to take on faith. Test each relation type you actually use, including pivot constraints and nullable foreign keys. Where support is missing or behaves oddly, that usually means falling back to native whereHas and whereRelation. Document the supported set so your team does not reach for a relation type the package handles incorrectly.
- Is it safe to pass user-supplied column or relation names into a metric?
- Treat any package that accepts column and relation names as strings to build SQL as needing an identifier whitelist. Parameter binding protects values, not identifiers, so a user-influenced column or relation name is a review gate. Map user input to a fixed set of allowed metric definitions and never interpolate raw request data into a metric call. If you cannot guarantee that mapping, keep the package away from any user-facing input path.
- Is laravel-relational-metrics still maintained, and can I fork it?
- The project is effectively a single-maintainer package with around 26 stars and no release since March 2022, so abandonment risk is real and should be priced in. Check the license terms and confirm that a fork is permitted before you depend on it in production. Isolate every call site behind your own boundary so removal is a composer remove plus rewriting a handful of classes. Realistically, the choice is fork-and-patch, vendor the handful of useful methods, or use native Eloquent.
- Does it cache metric results, or do I need my own caching layer?
- Assume caching, TTL and invalidation are entirely your responsibility unless the source proves otherwise. Metrics over the read path will hit the database on every call, which is fine for an admin dashboard and not fine for a hot loop. Wrap expensive metrics in your own cache with explicit invalidation tied to the underlying model events. Keep the cache boundary in your code so swapping out the package later does not require rewriting cache logic.
Weaver
How can I help you explore Laravel packages today?