lulzshadowwalker/laravel-metrics

Simple metrics for Laravel applications

v1.0.2 2026-07-07 09:30 UTC

Requires

• php: ^8.4
• illuminate/database: ^13.18
• illuminate/support: ^13.18

Requires (Dev)

• captainhook/captainhook: ^5.29
• captainhook/plugin-composer: ^5.3
• laravel/pint: ^1.29
• orchestra/testbench: ^11.1
• phpunit/phpunit: ^12.5

MIT

• lulzshadowwalker

Published on Packagist.org on 2026-07-07 09:30 UTC

README

A minimal, no-frills way to record and query historical events on your Eloquent models. Inspired by aarondfrancis/eventable, which does a lot more than this package does. If you need something more full-featured, use that instead.

Installation

composer require lulzshadowwalker/laravel-metrics

Then publish the migration and config, and migrate:

php artisan vendor:publish --tag=metrics-migrations
php artisan vendor:publish --tag=metrics-config
php artisan migrate

Usage

Add the HasMetrics trait to any model you want to record events against:

use Metrics\Traits\HasMetrics;

class Tenant extends Model
{
    use HasMetrics;
}

Define your own enum for the events you want to track. This package doesn't ship one, since every app's events are different:

enum Metric: string
{
    case SignedUp = 'signed_up';
    case OrderPlaced = 'order_placed';
    case HumanEscalated = 'human_escalated';
}

Record events:

$tenant->record(Metric::OrderPlaced, ['channel' => 'web']);

// meta is optional
$tenant->record(Metric::HumanEscalated);

record() also accepts a plain string if you don't want to use an enum.

Query events:

$tenant->metrics()->type(Metric::OrderPlaced)->today()->count();

$tenant->metrics()
    ->type(Metric::HumanEscalated)
    ->period(now()->subDays(30), now())
    ->count();

Available scopes

• type(string|BackedEnum $type) — filter by event type
• today() — events created today
• period(Carbon $from, Carbon $to) — events created within an inclusive date range

Extending the Event model

If you need extra columns (a tenant_id, for example), extend the base model:

namespace App\Models;

use Metrics\Models\Event as BaseEvent;

class Event extends BaseEvent
{
    //
}

Add whatever columns you need via a new migration, then point the package at your model in config/metrics.php:

return [
    'model' => \App\Models\Event::class,
];

Every model using HasMetrics will now use App\Models\Event instead of the package's default. This is a single, app-wide setting, not something you configure per model.

Testing

composer test

License

MIT.