Download the PHP package finller/laravel-kpi without Composer
On this page you can find all versions of the php package finller/laravel-kpi. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download finller/laravel-kpi
More information about finller/laravel-kpi
Files in finller/laravel-kpi
Package laravel-kpi
Short Description This is my package laravel-kpi
License MIT
Homepage https://github.com/finller/laravel-kpi
Informations about the package laravel-kpi
Store, analyse and retrieve KPI over time in your Laravel App
[!IMPORTANT] This package has been completely rethought and rewritten. The new and improved version is now available at this repository.
This package provides a way to store kpis from your app in your database and then retreive them easily in different ways. It is espacially usefull to tracks things related to your models like:
- the number of users
- the number of subscribed users
- the total revenue
- ...
It's a perfect tool for building dashboard ans display stats/charts.
Installation
You can install the package via composer:
You have to publish and run the migrations with:
Usage
This package is not a query builder, it's based on a kpi table where you will store all your kpis. With this approach, your kpis from the past (like the number of users you had a year ago) will not be altered if you permanently delete a model.
Retreiving kpis will also be much more efficient when asking for computed values that often require join like "users who have purchased last week" for example.
Step 1: Store kpis in you database
As said above, you will have to store the kpis you need in the database. Kpis are grouped by keys
and support different kind of values:
- number (float) under
number_value
column - string under
string_value
column - json or array under
json_value
column - money under
money_value
andmoney_currency
column
In most cases, you would store numbers, like the number of users for example. You are free to choose the key but you could do it like that:
Define KPIs for each model
Generally kpis are related to models, that's why we provid a trait HasKpi
with a standardized way to name your kpi key {namespace}:{key}
. For the User model, it would store your key in the users
namespace like users:{key}
.
By default the trait only define 1 KPI: Model::count()
You can define your own KPIs freely with the method registerKpis
.
Here is an example:
Each item of the collection can either have a key that represent the Kpi key, or define directly the Kpi key.
Notice that, the method accept a $date
parameter. This allow you to take KPIs snapshot "in the past".
This is usefull for already existing project, or simply when you add a new KPI to the list.
Step 2: Capture the Kpis with a command
After registering the kpis you have to save them in the database with the snapshotKpis
method.
A standard way to save your kpi values would be in a command that runs every day.
Here is an example:
Then add it to Kernel
You are free to store as much kpis as needed, even multiple times in a day, so you can get more recent data.
Step 3: Retreive your kpis
You can retreive kpis by using usefull scopes and the native eloquent Builder methods.
For example, if you want to query kpis under users:count
key, you could use:
Query by date
In most cases, you would like to have thoses kpis grouped by date (day, month, year, ...).
For example, to get the number of users grouped by day between 2 dates (usefull to draw a chart), you could do:
As we are grouping by date/period, you could have more than 1 snapshot of the same key for a date/period. In this situation, this package will give you only the most recent snaphot of each date/period.
In the previous example, I would get the most recent count of users for each day. This is also true for other kind of supported intervals.
Supported intervals:
The supported intervals are: perDay, perWeek, perMonth and perYear.
Fill gaps between dates
In some cases, you could have missed a snapshot. Let's say that your snapshot kpi command failed or your server was down.
To fill the gaps let by missing values, you can use the fillGaps
method available on KpiBuilder
or KpiCollection
.
By default the placeholders will be a copy of their previous kpi.
For convenience the KpiBuilder
is the best option as it will give you better typed values and shares parameters between fillGaps
and between
.
Missing Kpis and fill values from the past
Find gaps in Kpis
You can also find gaps in a KpiCollection using findGaps
method.
It can be usefull to snapshot these missing kpi later with something like:
Fill KPIs on a period for existing projects or when adding new KPIs
For existing project or when ading a new KPI, you may want to fill your KPIs with data from the past.
The HasKpi
trait allow you to do it like so:
Transforming Kpi Values
Get relative values
Some Kpis are only relevant when taken relatively to others or to a period.
For example, the number of new registered users by month can be obtained without registering a specific KPIs,
but by taking the relative values of the default User::count()
KPI.
You can easily get your Kpis in a relative format by using different methods:
To go from: | Jan | Feb | Mar |
---|---|---|---|
10 | 100 | 500 |
To:
Jan | Feb | Mar |
---|---|---|
0 | 90 | 400 |
Combine multiple Kpis together
When a KPI is a direct result of a combination of 2 other KPIs, it might not be worth to save it in the database.
You can combine KPIs together to create a new one simply by using the combineWith
method from the KpiCollection
.
Here is an example:
Testing
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Credits
- Quentin Gabriele
- All Contributors
License
The MIT License (MIT). Please see License File for more information.
All versions of laravel-kpi with dependencies
spatie/laravel-package-tools Version ^1.14.0
illuminate/contracts Version ^10.0|^11.0