Metrics For Laravel Laravel Package

Getting Started

• Install with composer require and publish the package's config (php artisan vendor:publish) if you need to change the default range, timezone, or dashboard route. Register metrics from a service provider so they're available to every request/dashboard render.

• Look first at the abstract Metric class and the traits that hold the fluent setters (range(), timezone(), name(), description(), prefix(), suffix(), precision(), the unit setters like daily(), compareTo(), withChangeAgainstPreviousPeriod(), target(), shouldBeAvoided()). Those traits are the real API surface — everything else is a thin wrapper around them.

• The fastest first use case is a single trend metric on a dashboard:

  Metrics::trend()
      ->name('Revenue')
      ->range('7d')
      ->daily()
      ->withChangeAgainstPreviousPeriod();
  

  Build the chain in a service provider or a dedicated Metrics registration class, then render it. Confirm the chain resolves to the concrete type (Trend, Value, Progress) in your IDE before wiring up the view — as of 1.1.2 it will.

Implementation Patterns

• Chain construction. Treat the fluent chain as the primary configuration mechanism. Setters live on traits, so the order is flexible, but the convention name/description → range → timezone → unit (daily()/weekly()/…) → comparison/target reads best and matches the docs.

• Registration in a provider. Use Metrics::register($metric) (or the config-driven equivalent) in a service provider. Pair with Metrics::unregister() for feature flags or per-tenant dashboards where metrics appear/disappear dynamically.

• Comparison and targets. Use compareTo() or withChangeAgainstPreviousPeriod() for period-over-period deltas, and target() / shouldBeAvoided() for threshold-based UI states. These compose: a Trend with a target and a previous-period comparison is the standard "KPI card" shape.

• Custom metric classes. Extend Metric / Trend / Value / Progress and build domain-specific presets:

  final class RevenueTrend extends Trend
  {
      public function __construct()
      {
          $this->name('Revenue')->range('30d')->daily()->compareTo('previous_period');
      }
  }
  

  Because setters now return static, a helper method that returns the result of ->name() keeps your subclass type and chains cleanly.

• Testing. Use Metrics::fake() and assert on registration rather than rendering. register() / unregister() return the fake itself now, so Metrics::fake()->register(...)->assertRegistered(...) works without intermediate variables or @var hints.

Gotchas and Tips

• 1.1.2 is a return-type change — audit your subclasses. All fluent setters previously returned self, which (because the setters live in traits on the abstract bases) meant the abstract base type, not your concrete class. Any class of yours that overrides range(), timezone(), name(), description(), prefix(), suffix(), precision(), a unit setter, compareTo(), withChangeAgainstPreviousPeriod(), target(), or shouldBeAvoided() with a : self return type must change it to : static. Leaving : self produces a return-type incompatibility (fatal error) when the class is loaded, not a deprecation notice.
• Same applies to the manager's register() / unregister() — if you subclassed or wrapped the manager with : self returns, update to : static. This is what keeps Metrics::fake()->register(...) a MetricsFake instead of degrading to the base manager.
• Remove old static-analysis workarounds. If you added @var Trend $metric docblocks, assert() calls, or PHPStan/Psalm baseline entries to silence "undefined method Metric::daily()", delete them — the chain now type-checks correctly and the stale annotations will mask real issues.
• Traits, not inheritance, define the setters. When overriding, you're overriding a trait method on the abstract class. Keep the static return type and, if you override construction-time defaults, do it in the constructor rather than by re-chaining inside a setter.
• Timezone vs. range. timezone() is metric-level and overrides the app default; setting a range in one timezone and rendering in another can shift a "today" bucket. Set timezone() before range() in chains you build programmatically so the boundaries are computed consistently.
• Precision/prefix/suffix are presentation-only. They don't affect stored values or comparisons — don't rely on them to round numbers used in target() logic.
• When a chain misbehaves, dump() mid-chain: each setter returns the same instance, so you can inspect the partially built metric and confirm the unit/range actually applied before the metric reaches the dashboard.