README

这主要依赖于 Laravel Pulse 包来确定获取和处理数据的一般方法，但进行了重构以提供替代方案和更长的周期，并且与前端无关。没有内置接口 - 这需要您来完成和组合，但数据聚合和拉取数据的基本功能已经准备好了供您使用。

安装

您可以通过 composer 安装此包

composer require vulpecula-io/laravel-datum

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

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

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

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

这是发布配置文件的内容

return [

    /*
    |--------------------------------------------------------------------------
    | Datum Master Switch
    |--------------------------------------------------------------------------
    |
    | This configuration option may be used to completely disable all Datum
    | data recorders regardless of their individual configurations. This
    | provides a single option to quickly disable all Datum recording.
    |
    */

    'enabled' => env('DATUM_ENABLED', true),

    /*
    |--------------------------------------------------------------------------
    | Datum Storage Driver
    |--------------------------------------------------------------------------
    |
    | This configuration option determines which storage driver will be used
    | while storing entries from Datum's recorders. In addition, you also
    | may provide any options to configure the selected storage driver.
    |
    */

    'storage' => [
        'driver' => env('DATUM_STORAGE_DRIVER', 'database'),

        'database' => [
            'connection' => env('DATUM_DB_CONNECTION', 'tenant'),
            'chunk' => 1000,
        ],
    ],

    /*
    |--------------------------------------------------------------------------
    | Datum Ingest Driver
    |--------------------------------------------------------------------------
    |
    | This configuration options determines the ingest driver that will be used
    | to capture entries from Datum's recorders. Ingest drivers are great to
    | free up your request workers quickly by offloading the data storage.
    |
    */

    'ingest' => [
        'driver' => env('DATUM_INGEST_DRIVER', 'storage'),

        'buffer' => env('DATUM_INGEST_BUFFER', 5000),

        'trim' => [
            'lottery' => [1, 1_000],
            'keep' => '365 days',
        ],

        'redis' => [
            'connection' => env('DATUM_REDIS_CONNECTION'),
            'chunk' => 1000,
        ],
    ],

    /*
    |--------------------------------------------------------------------------
    | Datum Cache Driver
    |--------------------------------------------------------------------------
    |
    | This configuration option determines the cache driver that will be used
    | for various tasks, including caching dashboard results, establishing
    | locks for events that should only occur on one server and signals.
    |
    */

    'cache' => env('DATUM_CACHE_DRIVER'),

    /*
    |--------------------------------------------------------------------------
    | Datum Recorders
    |--------------------------------------------------------------------------
    |
    | The following array lists the "recorders" that will be registered with
    | Datum, along with their configuration. Recorders gather application
    | event data from requests and tasks to pass to your ingest driver.
    |
    */

    'recorders' => [
        //        Recorders\ExampleRecord::class => [
        //            'enabled' => env('YOUR_RECORDER_ENABLED', true),
        //            'sample_rate' => env('DATUM_USER_REQUESTS_SAMPLE_RATE', 1),
        //            'ignore' => [
        //                '#^/datum$#', // Datum dashboard...
        //                '#^/telescope#', // Telescope dashboard...
        //            ],
        //        ],
    ],
];

记录器

就像在 Laravel Pulse 中一样，您需要创建自己的自定义记录器来处理数据“获取”。您可以查看 Pulse 的代码以查看如何编写自定义记录器的示例 在此处。

注意

记住，记录器应该在数据不会发生变化或多次出现在数据聚合器中不会有任何影响时才应该“触发”。

提示

示例：如果您基于 Invoice 模型记录营业额，则需要确保仅在发票不再会被编辑/更改时触发相关的记录器，否则营业额将被记录多次，并为稍后获得的任何图表/聚合器提供错误值。

注册记录器

一旦您有了自定义记录器，您需要将其添加到配置文件中的 recorders 数组中。键是记录器的类名，值是一个配置选项数组。唯一的必需选项是 enabled，它是一个布尔值，用于确定是否使用记录器。其他选项是可选的，并将传递给记录器的构造函数。

就像 Laravel Pulse 的标准记录器一样，您可以传递一个 sample_rate 或一个要 ignore 的项目数组。 sample_rate 是介于 0 和 1 之间的数字，用于确定应记录的请求数量的百分比。 ignore 选项是一个正则表达式数组，将进行匹配。如果项目与任何正则表达式匹配，则记录器将不会使用。

Period 枚举

Period 枚举用于确定数据使用的间隔。枚举如下

• Period::HOUR - 单小时间隔，分为 60 分钟间隔
• Period::SIXHOUR - 六小时间隔，分为 12 个半小时间隔
• Period::HALFDAY - 十二小时间隔，分为 24 个半小时间隔
• Period::DAY - 单日间隔，分为 24 小时间隔
• Period::WEEK - 标准周间隔，分为 7 天间隔
• Period::MONTH - 标准月间隔，分为每日间隔（根据月份天数：使用 CarbonImmutable::now()->daysInMonth）
• Period::QUARTER - 标准季度间隔，分为 (int) CarbonImmutable::now()->daysInYear / 4 （约 91 天）间隔
• Period::HALFYEAR - 以6个月为间隔的六个月周期
• Period::YEAR - 以12个月为间隔的标准年度周期

如果您想在您的代码中使用Period枚举，可以使用以下语句导入：use Vulpecula\Datum\Enums\Period;。存在一个label()函数，它会返回枚举值的标签。例如，Period::HOUR->label()将返回Hour。还提供了一个语言文件，可以使用以下方式发布：

php artisan vendor:publish --tag="datum-lang"

此外，您可以使用以下方法获取所有Period枚举值及其对应标签的数组：

array_map(
    fn(Period $period) => $period->label(), 
    Period::cases()
);

如果您想为用户提供可供选择的周期下拉列表，这很有用。

获取数据

一旦数据存储在数据库中，您就会希望在仪表板（或您想要使用的任何其他位置）上显示它。

有两个主要的功能可供使用：graph()和aggregate()。

graph()

graph()函数将返回一个可以用于图形化数据的Collection。该函数接受3个参数：

• array $types - 您想要图形化的数据类型数组。类型是数据表的type列，并在记录器中设置。
• string $aggregate - 要使用的聚合函数。这可以是任何标准的SQL聚合函数：count、sum、avg、min、max。
• Period $interval - 要使用的数据间隔（参见上面的可用间隔）。

$graphs = \Vulpecula\Datum\Facades\Datum::graph(['user_created', 'user_deleted'], 'count', Period::DAY);

这将返回一个包含对象的Collection，每个对象对应一个user_created和一个user_deleted。每个对象将是一个包含对象的集合，其中每个对象的key是数据库中针对types记录的不同的key。集合的值将是（在本例中）一个包含24个元素的数组，每个元素都有小时的开始时间戳和该小时的记录数。

aggregate()

aggregate()函数将返回一个可以用于在表中显示数据的Collection。该函数需要3个参数：

• string $type - 您想要聚合的数据类型。类型是数据表的type列，并在记录器中设置。
• array|string $aggregates - 要使用的聚合函数。这可以是任何标准的SQL聚合函数：count、sum、avg、min、max。如果您想使用多个聚合函数，可以传递一个包含函数的数组。
• Period $interval - 要使用的数据间隔（参见上面的可用间隔）。

可选参数包括：

• ?string $orderBy - 结果排序的列。默认是key。
• string $direction - 结果排序的方向。默认是desc。
• int $limit - 要返回的结果数量。默认是101，将返回所有结果。

测试

composer test

变更日志

请参阅变更日志，获取有关最近更改的更多信息。

贡献

请参阅贡献指南以获取详细信息。

安全漏洞

请审查我们的安全策略，了解如何报告安全漏洞。

鸣谢

• Richard Browne
• 所有贡献者

许可证

麻省理工学院许可证（MIT）。请参阅许可证文件获取更多信息。