This package provides an easy way to store KPIs from your application in your database and retrieve them in various formats. It's especially useful for tracking data related to your models, such as:
- Number of users
- Number of subscribed users
- Total revenue
- And more...
It's a perfect tool for building dashboards and displaying stats and charts.
Display your KPIs in a beatiful way with 1 line using our filament plugin: elegantly/filament-kpi
Install the package via Composer:
composer require elegantly/laravel-kpiPublish and run the migrations with:
php artisan vendor:publish --tag="kpi-migrations"
php artisan migratePublish the configuration file with:
php artisan vendor:publish --tag="kpi-config"Here is the content of the published config file:
return [
/*
|--------------------------------------------------------------------------
| Discover Definitions
|--------------------------------------------------------------------------
|
| If 'enabled' is set to true, your KPI definitions will be automatically
| discovered when taking snapshots.
| Set the 'path' to specify the directory where your KPI definitions are stored.
| Definitions will be discovered from this path and its subdirectories.
|
*/
'discover' => [
'enabled' => true,
/**
* This path will be used with the `app_path` helper, like `app_path('Kpis')`.
*/
'path' => 'Kpis',
],
/*
|--------------------------------------------------------------------------
| Registered Definitions
|--------------------------------------------------------------------------
|
| You can manually register your KPI definitions if you are not using
| "discover" or if you want to add additional definitions located elsewhere.
|
*/
'definitions' => [],
];This package is not a query builder. Instead, it is based on a kpis table where all KPIs are stored. This allows historical data (e.g., the number of users a year ago) to remain intact, even if models are permanently deleted.
Retrieving KPIs is also way more efficient when calculating complex values, such as "users who made a purchase last week."
A KPI can be simple or complex. Examples include:
- Number of registered users
- Monthly active users
- Total revenue invoiced to customers
- Number of recurring customers
- Average Order Value
- ...
KPIs can be either "absolute" or "relative":
- An absolute KPI represents a current state, such as the total number of users.
- A relative KPI represents a change, such as the number of new users each day.
Depending on the context, either an absolute or relative KPI may be more relevant. In most cases, relative KPIs can be derived from absolute ones, and vice versa. Therefore, it's often recommended to store KPIs as "absolute" and compute relative values when needed.
A KPI consists of two key components:
- A definition
- Its values
The definition is a class extending KpiDefinition, where you configure the KPI.
Each KPI definition must have a unique name, such as users:count.
The values are stored in the kpis table and represented by the Kpi model.
A KPI value may contain:
- A value (float, string, Money, JSON)
- A description (optional)
- Tags (optional)
- Metadata (optional)
- A timestamp
Each KPI is represented by a single KpiDefinition class. The package offers predefined classes for each data type:
KpiFloatDefinitionKpiStringDefinitionKpiMoneyDefinitionKpiJsonDefinition
You can also extend KpiDefinition if you need custom behavior.
Example:
namespace App\Kpis\Users;
use App\Models\User;
use Elegantly\Kpi\Enums\KpiInterval;
use Elegantly\Kpi\KpiFloatDefinition;
class UsersCountKpi extends KpiFloatDefinition
{
public static function getName(): string
{
return 'users:count';
}
/**
* This KPI is intended to be snapshotted every day.
*/
public static function getSnapshotInterval(): KpiInterval
{
return KpiInterval::Day;
}
public function getValue(): float
{
return (float) User::query()
->when($this->date, fn ($query) => $query->where('created_at', '<=', $this->date))
->toBase()
->count();
}
/**
* Description to store alongside the KPI value
*/
public function getDescription(): ?string
{
return null;
}
/**
* Tags to store alongside the KPI value
*/
public function getTags(): ?array
{
return null;
}
/**
* Metadata to store alongside the KPI value
*/
public function getMetadata(): ?array
{
return null;
}
}As shown, the KpiDefinition class has a date property, representing the snapshot date. When possible, use date in getValue, this will allow you to seed your KPIs with past data.
There are two ways to create KPI snapshots:
- Schedule the
kpis:snapshotcommand - Manually create snapshots
To capture KPI data at regular intervals (e.g., hourly or daily), schedule the kpis:snapshot command in your application's scheduler.
Example:
$schedule->command(SnapshotKpisCommand::class, [
'interval' => KpiInterval::Hour,
])->everyHour();
$schedule->command(SnapshotKpisCommand::class, [
'interval' => KpiInterval::Day,
])->daily();You can manually snapshot a KPI using the snapshot method:
use App\Kpis\Users\UsersCountKpi;
UsersCountKpi::snapshot(
date: now()
);When adding KPIs to an existing project, you may want to seed past data. If your KpiDefinition class supports the date property, you can seed KPIs using the following command:
php artisan kpis:seed "one year ago" "now"You can also seed KPIs manually using the seed method:
use App\Kpis\Users\UsersCountKpi;
UsersCountKpi::seed(
from: now()->subYear(),
to: now(),
interval: KpiInterval::Day
);To visualize KPIs in charts or dashboards, the KpiDefinition class provides several helper methods:
use App\Kpis\Users\UsersCountKpi;
/**
* Retrieve a collection of KPIs for a given period, keyed by date.
*/
UsersCountKpi::getPeriod(
start: now()->subDays(6),
end: now(),
interval: KpiInterval::Day
);
/**
* Retrieve a collection of relative KPIs (i.e., the difference between consecutive snapshots).
*/
UsersCountKpi::getDiffPeriod(
start: now()->subDays(6),
end: now(),
interval: KpiInterval::Day
);You can easily aggregate KPIs using the following methods:
/**
* Retrieve the KPI with the maximum value for each month.
*/
UsersCountKpi::max(
start: now()->subMonths(6),
end: now(),
interval: KpiInterval::Month
);
UsersCountKpi::min(...);
UsersCountKpi::avg(...);
UsersCountKpi::sum(...);
UsersCountKpi::count(...);Run the tests with:
composer testFor recent changes, see the CHANGELOG.
For contribution guidelines, see CONTRIBUTING.
For details on reporting security vulnerabilities, review our security policy.
The MIT License (MIT). Please see License File for more information.