README

此包提供了一个简单的方法来将应用程序中的 KPI 存储到数据库中，并以各种格式检索它们。它特别适用于跟踪与模型相关的数据，例如

用户数量
订阅用户数量
总收入
等等...

它是构建仪表板并显示统计信息和图表的完美工具。

Filament 插件

使用我们的 filament 插件以一行代码的方式以优雅的方式显示您的 KPI： elegantly/filament-kpi

安装

通过 Composer 安装包

composer require elegantly/laravel-kpi

使用以下命令发布和运行迁移

php artisan vendor:publish --tag="kpi-migrations"
php artisan migrate

使用以下命令发布配置文件

php artisan vendor:publish --tag="kpi-config"

以下是已发布的配置文件内容

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' => [],
];

概念

此包不是一个查询构建器。相反，它基于一个 kpis 表，其中存储了所有 KPI。这使得历史数据（例如，一年前的用户数量）保持完整，即使模型被永久删除。

在计算复杂值（例如“上周进行了购物的用户”）时，检索 KPI 也更加高效。

KPI 可以简单或复杂。例如

注册用户数量
月活跃用户
向客户开具的总收入
重复购买客户数量
平均订单价值
...

KPI 可以是“绝对”或“相对”的

绝对 KPI 代表当前状态，例如总用户数量。
相对 KPI 代表变化，例如每天的新用户数量。

根据上下文，绝对或相对 KPI 可能更有意义。在大多数情况下，相对 KPI 可以从绝对 KPI 中派生出来，反之亦然。因此，通常建议将 KPI 存储为“绝对”的，并在需要时计算相对值。

用法

KPI 由两个关键组件组成

定义
它的值

定义是一个扩展 KpiDefinition 的类，其中您配置 KPI。

每个 KPI 定义都必须有一个唯一的 name，例如 users:count。

值存储在 kpis 表中，并由 Kpi 模型表示。

KPI 值可能包含

一个值（浮点数、字符串、货币、JSON）
描述（可选）
标签（可选）
元数据（可选）
时间戳

1. 定义 KPI

每个 KPI 都由一个单一的 KpiDefinition 类表示。此包为每种数据类型提供预定义的类

KpiFloatDefinition
KpiStringDefinition
KpiMoneyDefinition
KpiJsonDefinition

如果您需要自定义行为，也可以扩展 KpiDefinition。

示例

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;
    }
}

如上图所示，KpiDefinition 类有一个 date 属性，代表快照日期。当可能时，在 getValue 中使用 date，这将允许您使用过去的数据初始化 KPI。

2. 快照 KPI

有两种方法可以创建 KPI 快照

安排 kpis:snapshot 命令
手动创建快照

使用命令和调度器

为了以固定的时间间隔（例如每小时或每天）捕获关键绩效指标（KPI）数据，请在应用程序的调度器中安排 kpis:snapshot 命令。

示例

$schedule->command(SnapshotKpisCommand::class, [
    'interval' => KpiInterval::Hour,
])->everyHour();

$schedule->command(SnapshotKpisCommand::class, [
    'interval' => KpiInterval::Day,
])->daily();

手动快照

您可以使用 snapshot 方法手动快照 KPI。

use App\Kpis\Users\UsersCountKpi;

UsersCountKpi::snapshot(
    date: now()
);

3. KPI 预种

使用命令预种

当向现有项目添加 KPI 时，您可能希望预种过去的数据。如果您的 KpiDefinition 类支持 date 属性，您可以使用以下命令预种 KPI。

php artisan kpis:seed "one year ago" "now"

手动预种

您还可以使用 seed 方法手动预种 KPI。

use App\Kpis\Users\UsersCountKpi;

UsersCountKpi::seed(
    from: now()->subYear(),
    to: now(),
    interval: KpiInterval::Day
);

4. 查询 KPI

要将在图表或仪表板中可视化的 KPI，KpiDefinition 类提供了一些辅助方法。

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
);

5. 聚合 KPI

您可以使用以下方法轻松聚合 KPI。

/**
 * 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(...);

测试

使用以下命令运行测试

composer test

变更日志

有关最近更改的详细信息，请参阅变更日志。

贡献

有关贡献指南，请参阅贡献指南。

安全漏洞

有关报告安全漏洞的详细信息，请查阅我们的安全策略。

鸣谢

许可证

MIT 许可证（MIT）。有关更多信息，请参阅许可证文件。

优雅 / laravel-kpi

维护者

详情