Download the PHP package andrewdyer/metrics without Composer

Metrics

A metrics library for Eloquent applications that calculates strongly typed aggregates over a configurable date range.

Introduction

This library provides Eloquent-based metric calculations, returning strongly typed result objects for scalar aggregates, time-grouped trends with zero-filled gaps, and categorical breakdowns, all with JSON serialisation support. It works in any PHP application with an Eloquent connection, including outside Laravel via the Capsule manager.

Prerequisites

• PHP: Version 8.3 or higher is required.
• Composer: Dependency management tool for PHP.
• Eloquent ORM: An configured Eloquent connection is required.

Installation

Getting Started

1. Set up Eloquent

This library requires an Eloquent connection. In a Laravel application this is configured automatically. Outside of Laravel, bootstrap Eloquent using the Capsule manager:

2. Create a metric

Extend Value and implement calculate() to define the query, and getStartDate() / getEndDate() to define the date range:

Usage

Calculating a metric

Call calculate() on any metric instance to run the query and return a typed result:

JSON serialisation

All result objects implement JsonSerializable:

Customising the metric name and description

Override getName() and getDescription() on any metric to provide a human-readable label:

Rounding

Override getRoundingPrecision() and getRoundingMode() to control how aggregate values are rounded:

Metric Types

Value

A Value metric calculates a single aggregate over a date range. When the model uses timestamps, the date filter defaults to created_at. When the model does not use timestamps, no date filter is applied unless an explicit $dateColumn is passed.

Count

Returns the number of records within the date range:

To filter by a specific date column, pass it explicitly:

On models without timestamps, no date filter is applied unless an explicit column is given:

Sum

Totals the values of a column across all matching records:

Average

Calculates the mean value of a column across all matching records:

Minimum

Returns the smallest value of a column within the date range:

Maximum

Returns the largest value of a column within the date range:

Trend

A Trend metric calculates an aggregate grouped over time at a given frequency. Missing dates within the range are automatically filled with zero values.

When the model uses timestamps, the date column defaults to created_at. When the model does not use timestamps, an explicit $dateColumn must be passed or an InvalidArgumentException is thrown.

Extend Trend and implement calculate(), getStartDate(), getEndDate(), and getFrequency():

Calculating the metric returns a keyed array of labels to aggregate values:

Supported frequencies

Count

Tracks how many records fall within each period of the date range:

Sum

Totals a column's values for each period across the date range:

Average

Calculates the mean value of a column for each period in the range:

Minimum

Returns the lowest value of a column recorded within each period:

Maximum

Returns the highest value of a column recorded within each period:

Partition

A Partition metric calculates an aggregate grouped by a categorical column, returning a key-value breakdown. Results are filtered to the configured date range.

When the model uses timestamps, the date filter defaults to created_at. When the model does not use timestamps, no date filter is applied unless an explicit $dateColumn is passed.

Extend Partition and implement calculate(), getStartDate(), and getEndDate():

Calculating the metric returns a keyed array of group labels to aggregate values:

Count

Groups records by a column and counts how many fall into each category:

To filter by a specific date column, pass it explicitly:

Sum

Groups records by a column and totals a second column within each group:

Average

Groups records by a column and calculates the mean of a second column per group:

Database Support

The following database drivers are supported:

License

Licensed under the MIT licence and is free for private or commercial projects.