PHPackages                             beacon-hq/metrics - 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. [Admin Panels](/categories/admin)
4. /
5. beacon-hq/metrics

ActiveLibrary[Admin Panels](/categories/admin)

beacon-hq/metrics
=================

Simple metrics and trends data for Laravel

1.0.1(8mo ago)68481[6 PRs](https://github.com/beacon-hq/metrics/pulls)MITPHPPHP ^8.2CI passing

Since Apr 18Pushed 7mo ago1 watchersCompare

[ Source](https://github.com/beacon-hq/metrics)[ Packagist](https://packagist.org/packages/beacon-hq/metrics)[ Docs](https://github.com/beacon-hq/metrics)[ RSS](/packages/beacon-hq-metrics/feed)WikiDiscussions main Synced today

READMEChangelog (2)Dependencies (16)Versions (17)Used By (0)

 [![Beacon Metrics](./docs/public/assets/images/social.png)](./docs/public/assets/images/social.png)

 [ ![Coverage](https://camo.githubusercontent.com/7199805439bab08610581e0cc579975a1fae2d9e67dbcab5cb130bfe33acb03d/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d626561636f6e2d68715f6d657472696373266d65747269633d636f766572616765) ](https://sonarcloud.io/summary/new_code?id=beacon-hq_metrics) [ ![Quality Gate Status](https://camo.githubusercontent.com/8ab87a73836e069037da47db04d0c2ffaad09f3d880ceb78a6463a32a634d498/68747470733a2f2f736f6e6172636c6f75642e696f2f6170692f70726f6a6563745f6261646765732f6d6561737572653f70726f6a6563743d626561636f6e2d68715f6d657472696373266d65747269633d616c6572745f737461747573) ](https://sonarcloud.io/summary/new_code?id=beacon-hq_metrics)

Beacon Metrics
==============

[](#beacon-metrics)

Simple metrics and trends for Laravel

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

[](#installation)

```
composer require beacon-hq/metrics
```

Features
--------

[](#features)

- PostgreSQL, MySQL, and SQLite support
- Simple value metrics (e.g. count for a month)
- Previous period comparison (e.g. count for this month and last month)
- Trends data (e.g. count per day)
- Grouping

### Supported Aggregates

[](#supported-aggregates)

- count
- sum
- average
- min
- max

### Supported Intervals

[](#supported-intervals)

- Second
- Minute
- Hour
- Day
- Week
- Month
- Year

Usage
-----

[](#usage)

### Value Metrics

[](#value-metrics)

Value metrics are simple single aggregate values and will typically result in a single value.

Value metrics can be calcuted using `Metrics->value()`.

```
use Carbon\Carbon;
use Beacon\Metrics\Metrics;

$value = Metrics::query(MyModel::query())
    ->count()
    ->between(now()->subMonth(1), now())
    ->value(); // 123
```

You can also get value metrics by group which will result in a Laravel Collection of values keys using the group value.

To enable grouping, use `Metrics->byGroup()`, passing in a column name or a SQL expression (i.e. `DB::raw()`):

```
use Carbon\Carbon;
use Beacon\Metrics\Metrics;

$value = Metrics::query(MyModel::query())
    ->count()
    ->groupBy('category')
    ->between(now()->subMonth(1), now())
    ->value(); // ['category1' => 123, 'category2' => 456]
```

#### With Previous

[](#with-previous)

A common need is to get the metrics for the current period (e.g. today, this week) and the previous period (e.g. yesterday, last week), this can be achieved using the `Metric->valueWithPrevious()` method. This will return a Laravel collection.

```
use Carbon\Carbon;
use Beacon\Metrics\Metrics;

$value = Metrics::query(MyModel::query())
    ->count()
    ->between(now()->subMonth(1), now())
    ->valueWithPrevious();
    /*
     * [
     *   'value' => 100,
     *   'previous' => [
     *       'type' => 'increase',
     *       'value' => 80,
     *       'difference' => 20,
     *       'percentage' => 20,
     *   ],
     * ]
     */
```

### Trend Metrics

[](#trend-metrics)

Trends metrics allow you to get metrics for intervals of a time period, e.g. every day, every month, or multiples of an interval, e.g. every third day, every second month.

To set the period, use `Metrics->by*($count)`, e.g. every third day would use `$metrics->byDay(3)`.

Trends will always return a collection, with three keys:

- `labels`: the sorted list of labels, using the formatted date as the label value
- `data`: the corresponding list of values
- `total`: the aggregate total for the entire result set

```
use Carbon\Carbon;
use Beacon\Metrics\Metrics;

$value = Metrics::query(MyModel::query())
    ->count()
    ->byDay()
    ->between(now()->subWeek(), now())
    ->trends();
    /*
     * [
     *  'labels' => [
     *      '2025-04-07',
     *      '2025-04-08',
     *      '2025-04-10'
     *  ],
     *  'data' => [
     *      3,
     *      6,
     *      9
     *  ],
     *  'total' => 18
     * ]
     */
```

#### Fill Missing Values

[](#fill-missing-values)

By default, only dates with results will be returned. To fill in missing values, use `Metrics->fillMissing()`:

```
use Carbon\Carbon;
use Beacon\Metrics\Metrics;

$value = Metrics::query(MyModel::query())
    ->count()
    ->byDay()
    ->between(now()->subWeek(), now())
    ->trends();
    /*
     * [
     *  'labels' => [
     *      '2025-04-05',
     *      '2025-04-06',
     *      '2025-04-07',
     *      '2025-04-08',
     *      '2025-04-09',
     *      '2025-04-10',
     *      '2025-04-11',
     *  ],
     *  'data' => [
     *      0,
     *      0,
     *      3,
     *      6,
     *      0,
     *      9,
     *      0
     *  ],
     *  'total' => 18
     * ]
     */
```

#### Percentage Values

[](#percentage-values)

To get results in percentages rather than absolute values, set the `$inPercent` argument to true when calling `Metrics->trends()`.

Percentages are returned as a float with up to 2 decimal places.

### Custom Queries

[](#custom-queries)

If you want metrics for a sub-set of data (e.g. a single category), you can simply add a `where` clause to the query passed to the `Metrics::query()` method.

```
use Beacon\Metrics\Metrics;
use App\Models\MyModel;

$query = MyModel::query()->where('category', 'Category Name');;

$value = Metrics::query($builder)
    ->count()
    ->between(now()->subMonth(1), now())
    ->value(); // 123
```

### Indexes

[](#indexes)

For performance, you need to have appropriate indexes on your tables. The following are recommendations based on testing, but you should always test with your own data to confirm.

If you are querying *without* a where clause, for MySQL/MariaDB and SQLite you should have an index on the **date** column (e.g. `created_at`):

```
Schema::table('your_table', function (Blueprint $table) {
    $table->index('created_at');
});
```

For PostgreSQL, you should have an index on the **date** column (e.g. `created_at`) *and* the **value** column:

```
Schema::table('your_table', function (Blueprint $table) {
    $table->index(['created_at', 'value']);
});
```

If you are querying *with* a where clause, you should also include the **where** column:

Warning

The ordering in the column matters! Your `where` column should be first.

```
Schema::table('your_table', function (Blueprint $table) {
    $table->index(['your_column', 'created_at']); // MySQL/MariaDB and SQLite
    $table->index(['your_column', 'created_at', 'value']); // PostgreSQL
});
```

### Defaults

[](#defaults)

#### Aggregate

[](#aggregate)

By default, the package will use the `count` aggregate. If you want to use a different aggregate, you can use the appropriate aggregate method:

- `Metrics->count()`
- `Metrics->sum()`
- `Metrics->average()`
- `Metrics->min()`
- `Metrics->max()`

### Interval

[](#interval)

By default, the package will use a one day interval. If you want to use a different interval, you can use the `Metrics->by*()` methods to set the interval:

- `Metrics->bySecond($count)`
- `Metrics->byMinute($count)`
- `Metrics->byHour($count)`
- `Metrics->byDay($count)`
- `Metrics->byWeek($count)`
- `Metrics->byMonth($count)`
- `Metrics->byYear($count)`

#### Date Column

[](#date-column)

By default, the package will use the `created_at` column for the date column. If you want to use a different column, you can use the `Metrics->dateColumn()` method to set the column name.

```
use Carbon\Carbon;
use Beacon\Metrics\Metrics;

$value = Metrics::query(MyModel::query())
    ->dateColumn('updated_at')
    ->count()
    ->between(now()->subMonth(1), now())
    ->value(); // 123
```

#### Date Range

[](#date-range)

By default, the package will use the previous month as the date range. If you want to use a different date range, you can use the `Metrics->between()`, `Metrics->from()`, or any of the `Metrics->for*()` methods to set the date range.

###  Health Score

41

—

FairBetter than 87% of packages

Maintenance61

Regular maintenance activity

Popularity22

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 96% 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.

###  Release Activity

Cadence

Every ~72 days

Total

2

Last Release

243d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/950c044ac0c43c20172483e6cd7c13afed5976380e86dad6308cc4a667329b27?d=identicon)[dshafik](/maintainers/dshafik)

---

Top Contributors

[![dshafik](https://avatars.githubusercontent.com/u/58074?v=4)](https://github.com/dshafik "dshafik (24 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")

---

Tags

laravellaravel-packageMetricsdashboardchartstrends

###  Code Quality

TestsPest

Static AnalysisPHPStan, Rector

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/beacon-hq-metrics/health.svg)

```
[![Health](https://phpackages.com/badges/beacon-hq-metrics/health.svg)](https://phpackages.com/packages/beacon-hq-metrics)
```

###  Alternatives

[laravel/cashier

Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services.

2.6k29.9M147](/packages/laravel-cashier)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k15.1M132](/packages/laravel-pulse)[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[laravel/horizon

Dashboard and code-driven configuration for Laravel queues.

4.2k95.4M306](/packages/laravel-horizon)[eliseekn/laravel-metrics

Generate easily metrics and trends data of your models for your dashboards.

1347.7k](/packages/eliseekn-laravel-metrics)[yajra/laravel-oci8

Oracle DB driver for Laravel via OCI8

8793.2M25](/packages/yajra-laravel-oci8)

PHPackages © 2026

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