PHPackages                             whilesmart/eloquent-engagement - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. whilesmart/eloquent-engagement

ActiveLibrary[Database & ORM](/categories/database)

whilesmart/eloquent-engagement
==============================

Host-agnostic engagement and metrics aggregation for Laravel: record usage events and report app metrics from provider classes the host implements.

00PHP

Since Jun 27Pushed todayCompare

[ Source](https://github.com/whilesmartphp/eloquent-engagement)[ Packagist](https://packagist.org/packages/whilesmart/eloquent-engagement)[ RSS](/packages/whilesmart-eloquent-engagement/feed)WikiDiscussions dev Synced today

READMEChangelogDependenciesVersions (2)Used By (0)

Whilesmart Eloquent Engagement
==============================

[](#whilesmart-eloquent-engagement)

Host-agnostic engagement and metrics aggregation for Laravel. Record usage events, and build an admin metrics report from provider classes your own app implements. The package never hard-codes what a "feature" or a "metric" is: your features declare their own.

Installation
------------

[](#installation)

```
composer require whilesmart/eloquent-engagement
```

The service provider and the `Engagement` facade are auto-discovered. Publish and run migrations:

```
php artisan vendor:publish --tag=engagement-migrations
php artisan migrate
```

Recording events
----------------

[](#recording-events)

The event name is your own vocabulary. Record through the facade:

```
use Whilesmart\Engagement\Facades\Engagement;

Engagement::record($user, 'transaction.created', ['amount' => 42]);
Engagement::record(null, 'session.start'); // anonymous/system
```

Or add the subject trait to the model events are attributed to:

```
use Whilesmart\Engagement\Traits\RecordsEngagement;

class User extends Model
{
    use RecordsEngagement;
}

$user->recordEngagement('report.viewed');
```

Declaring metrics
-----------------

[](#declaring-metrics)

A metric source implements `MetricProvider`. Each provider owns a group of metrics; the package collects every registered provider and asks it for figures over a period.

```
use Whilesmart\Engagement\Contracts\MetricProvider;
use Whilesmart\Engagement\Support\Metric;
use Whilesmart\Engagement\Support\Period;

class UsersMetricProvider implements MetricProvider
{
    public function key(): string { return 'users'; }
    public function label(): string { return 'Users'; }

    public function metrics(Period $period): array
    {
        return [
            Metric::count('total_users', 'Total users', User::count()),
            Metric::series('signups', 'New users', /* [{date, value}, ...] */ []),
        ];
    }
}
```

Register providers in `config/engagement.php`:

```
'providers' => [
    \Whilesmart\Engagement\Providers\EventMetricProvider::class, // built-in, over recorded events
    \App\Engagement\UsersMetricProvider::class,
],
```

or at runtime: `Engagement::registerMetricProvider(UsersMetricProvider::class);`

Metric shapes
-------------

[](#metric-shapes)

`Metric` value objects carry a `type` so the client knows how to render them:

- `Metric::count($key, $label, $int)`
- `Metric::sum($key, $label, $float)`
- `Metric::ratio($key, $label, $float)` (0..1)
- `Metric::series($key, $label, [['date' => '2026-06-01', 'value' => 12], ...])`

The report
----------

[](#the-report)

```
use Whilesmart\Engagement\Support\Period;
use Whilesmart\Engagement\Facades\Engagement;

$report = Engagement::report(Period::lastDays(30));
```

A config-gated endpoint exposes the same payload:

```
GET {prefix}/engagement/report?days=30&granularity=day

```

Engagement metrics are app-wide, so secure it for admins. Set the middleware in `config/engagement.php`:

```
'route_middleware' => ['api', 'auth:sanctum', 'role:admin'],
```

Set `'register_routes' => false` to mount your own route instead.

Built-in provider
-----------------

[](#built-in-provider)

`EventMetricProvider` reports total events, distinct active subjects, an active-subjects series, and the top event names from whatever you recorded.

Configuration
-------------

[](#configuration)

`register_routes`, `route_prefix`, `route_middleware`, `events_table`, and `providers` are all configurable in `config/engagement.php`.

License
-------

[](#license)

MIT. WhileSmart LTD.

###  Health Score

21

—

LowBetter than 18% of packages

Maintenance65

Regular maintenance activity

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity13

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/a1ca6f6e01ecbfe6640ff410c4f0321054fb48d05a5f843c2b89887b90369bcd?d=identicon)[whilesmart](/maintainers/whilesmart)

---

Top Contributors

[![nfebe](https://avatars.githubusercontent.com/u/14317775?v=4)](https://github.com/nfebe "nfebe (1 commits)")

### Embed Badge

![Health badge](/badges/whilesmart-eloquent-engagement/health.svg)

```
[![Health](https://phpackages.com/badges/whilesmart-eloquent-engagement/health.svg)](https://phpackages.com/packages/whilesmart-eloquent-engagement)
```

###  Alternatives

[jdorn/sql-formatter

a PHP SQL highlighting library

3.9k116.5M113](/packages/jdorn-sql-formatter)[propel/propel1

Propel is an open-source Object-Relational Mapping (ORM) for PHP5.

8351.6M87](/packages/propel-propel1)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)