sakanjo/laravel-easy-metrics

Generate metrics with ease and precision.

🔥 Easy metrics

Easily create metrics for your application.

✨ Help support the maintenance of this package by sponsoring me.

Designed to work with Laravel, Filament, Easy enum, and more.

🚀 Supported metrics

• Bar metric
• Doughnut metric
• Line metric
• Pie metric
• Polar metric
• Trend metric
• Value metric

Table of contents

• Install
• Usage
  • Value metric
  • Doughnut metric
  • Trend metric
  • Other metrics
• Ranges
  • Available custom ranges
• Growth rates
  • Using value metric
  • Using trend metric
  • Using doughnut metric
  • Available growth rate types
• Tips
  • using getLabel
• Practical examples
  • Filamentphp v3 widgets
• Support the development
• Credits
• License

📦 Install

composer require sakanjo/laravel-easy-metrics

🦄 Usage

Value metric

use SaKanjo\EasyMetrics\Metrics\Value;
use App\Models\User;

$data = Value::make(User::class)
    ->count();

Query types

The currently supported aggregate functions to calculate a given column compared to the previous time interval / range

Min

Value::make(User::class)
    ->min('age');

Max

Value::make(User::class)
    ->max('age');

Sum

Value::make(User::class)
    ->sum('age');

Average

Value::make(User::class)
    ->average('age');

Count

Value::make(User::class)
    ->count();

Doughnut metric

use SaKanjo\EasyMetrics\Metrics\Doughnut;
use App\Models\User;

[$labels, $data] = Doughnut::make(User::class)
    ->count('gender');

Query types

The currently supported aggregate functions to calculate a given column compared to the previous time interval / range

Min

Doughnut::make(User::class)
    ->min('age', 'gender');

Max

Doughnut::make(User::class)
    ->max('age', 'gender');

Sum

Doughnut::make(User::class)
    ->sum('age', 'gender');

Average

Doughnut::make(User::class)
    ->average('age', 'gender');

Count

Doughnut::make(User::class)
    ->count('gender');

Trend metric

use SaKanjo\EasyMetrics\Metrics\Trend;
use App\Models\User;

[$labels, $data] = Trend::make(User::class)
    ->countByMonths();

Query types

The currently supported aggregate functions to calculate a given column compared to the previous time interval / range

Min

$trend->minByYears('age'); 
$trend->minByMonths('age'); 
$trend->minByWeeks('age');  
$trend->minByDays('age');  
$trend->minByHours('age');  
$trend->minByMinutes('age');  

Max

$trend->maxByYears('age'); 
$trend->maxByMonths('age'); 
$trend->maxByWeeks('age');  
$trend->maxByDays('age');  
$trend->maxByHours('age');  
$trend->maxByMinutes('age');  

Sum

$trend->sumByYears('age'); 
$trend->sumByMonths('age'); 
$trend->sumByWeeks('age');  
$trend->sumByDays('age');  
$trend->sumByHours('age');  
$trend->sumByMinutes('age');  

Average

$trend->averageByYears('age'); 
$trend->averageByMonths('age'); 
$trend->averageByWeeks('age');  
$trend->averageByDays('age');  
$trend->averageByHours('age');  
$trend->averageByMinutes('age');  

Count

$trend->countByYears(); 
$trend->countByMonths(); 
$trend->countByWeeks();  
$trend->countByDays();  
$trend->countByHours();  
$trend->countByMinutes();  

Other metrics

• Bar extends Trend
• Line extends Trend
• Doughnut extends Pie
• Polar extends Pie

Ranges

Every metric class contains a ranges method, that will determine the range of the results based on it's date column.

use SaKanjo\EasyMetrics\Metrics\Trend;
use SaKanjo\EasyMetrics\Metrics\Enums\Range;
use App\Models\User;

Value::make(User::class)
    ->range(30)
    ->ranges([
        15, 30, 365,
        Range::TODAY, // Or 'TODAY'
    ]);

Available custom ranges

• Range::TODAY
• Range::YESTERDAY
• Range::MTD
• Range::QTD
• Range::YTD
• Range::ALL

Growth rates

Growth rate, expressed as both a value and a percentage, measures the change in a quantity over time, showing the speed of its expansion or contraction in both absolute and relative terms.

Using Value metric

use SaKanjo\EasyMetrics\Metrics\Value;
use SaKanjo\EasyMetrics\Enums\GrowthRateType;
use App\Models\User;

[$value, $growth] = Value::make(User::class)
    ->withGrowthRate()
    ->growthRateType(GrowthRateType::Value) // default is `Percentage`
    ->count();

Using Trend metric

use SaKanjo\EasyMetrics\Metrics\Trend;
use App\Models\User;

[$labels, $data, $growth] = Trend::make(User::class)
    ->withGrowthRate()
    ->countByYears();

Using Doughnut metric

use SaKanjo\EasyMetrics\Metrics\Doughnut;
use App\Models\User;

[$labels, $data, $growth] = Doughnut::make(User::class)
    ->withGrowthRate()
    ->count('gender');

Available growth rate types

• GrowthRateType::Value
• GrowthRateType::Percentage

🔥 Tips

Using getLabel

You can use the getLabel method to customize the retreived data labels, for example:

<?php

namespace App\Enums;

use SaKanjo\EasyEnum;

enum ExampleEnum: int
{
    use EasyEnum; // Includes getLabel method

    case Active = 0;
    case Disabled = 1;
}

🔥 Practical examples

Filamentphp v3 widgets

<?php

namespace App\Filament\Widgets\Admin;

use App\Models\User;
use Filament\Widgets\ChartWidget;
use SaKanjo\EasyMetrics\Metrics\Trend;

class UsersCountChart extends ChartWidget
{
    protected static ?string $heading = 'Users count trend';

    protected function getData(): array
    {
        [$labels, $data] = Trend::make(User::class)
            ->range($this->filter)
            ->rangesFromOptions($this->getFilters())
            ->countByMonths();

        return [
            'datasets' => [
                [
                    'label' => 'Users',
                    'data' => $data,
                ],
            ],
            'labels' => $labels,
        ];
    }

    protected function getType(): string
    {
        return 'line';
    }

    protected function getFilters(): ?array
    {
        return [
            15 => '15 Months',
            30 => '30 Months',
            60 => '60 Months',
        ];
    }
}

💖 Support the development

Do you like this project? Support it by donating

Click the "💖 Sponsor" at the top of this repo.

©️ Credits

• Salah Kanjo
• All Contributors

📄 License

MIT License © 2023-PRESENT Salah Kanjo