Laravel Pulse

简介
安装
- 配置
仪表盘
- 授权
- 自定义
- 解析用户
- 卡片
捕获条目
- 记录器
- 过滤
性能
自定义卡片

简介

Laravel Pulse 可让您一目了然地洞察应用程序的性能和使用情况。通过 Pulse，您可以追踪诸如慢任务、慢端点等瓶颈，查找最活跃的用户，等等。

如需针对单个事件进行深度调试，请查看 Laravel Telescope。

安装

Pulse 的原生存储实现目前需要 MySQL、MariaDB 或 PostgreSQL 数据库。如果您使用的是其他数据库引擎，则需要为 Pulse 数据准备一个独立的 MySQL、MariaDB 或 PostgreSQL 数据库。

您可以使用 Composer 包管理器安装 Pulse：

1composer require laravel/pulse

composer require laravel/pulse

接下来，您应该使用 vendor:publish Artisan 命令发布 Pulse 的配置文件和迁移文件：

1php artisan vendor:publish --provider="Laravel\Pulse\PulseServiceProvider"

php artisan vendor:publish --provider="Laravel\Pulse\PulseServiceProvider"

最后，运行 migrate 命令以创建存储 Pulse 数据所需的表：

1php artisan migrate

php artisan migrate

运行完 Pulse 的数据库迁移后，您可以通过 /pulse 路由访问 Pulse 仪表盘。

如果您不想将 Pulse 数据存储在应用程序的主数据库中，可以指定一个专门的数据库连接。

配置

许多 Pulse 配置选项都可以通过环境变量来控制。要查看可用选项、注册新的记录器或配置高级选项，您可以发布 config/pulse.php 配置文件：

1php artisan vendor:publish --tag=pulse-config

php artisan vendor:publish --tag=pulse-config

仪表盘

授权

Pulse 仪表盘可通过 /pulse 路由访问。默认情况下，您只能在 local 环境中访问此仪表盘，因此您需要通过自定义 'viewPulse' 授权门控来配置生产环境的访问权限。您可以在应用程序的 app/Providers/AppServiceProvider.php 文件中实现这一点：

 1use App\Models\User;
 2use Illuminate\Support\Facades\Gate;
 3 
 4/**
 5 * Bootstrap any application services.
 6 */
 7public function boot(): void
 8{
 9    Gate::define('viewPulse', function (User $user) {
10        return $user->isAdmin();
11    });
12 
13    // ...
14}

use App\Models\User;
use Illuminate\Support\Facades\Gate;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Gate::define('viewPulse', function (User $user) {
        return $user->isAdmin();
    });

    // ...
}

自定义

Pulse 仪表盘卡片和布局可以通过发布仪表盘视图来进行配置。仪表盘视图将被发布到 resources/views/vendor/pulse/dashboard.blade.php：

1php artisan vendor:publish --tag=pulse-dashboard

php artisan vendor:publish --tag=pulse-dashboard

仪表盘由 Livewire 提供支持，允许您自定义卡片和布局，而无需重新构建任何 JavaScript 资产。

在此文件中，<x-pulse> 组件负责渲染仪表盘并为卡片提供网格布局。如果您希望仪表盘横跨屏幕全宽，可以向组件提供 full-width 属性：

1<x-pulse full-width>
2    ...
3</x-pulse>

<x-pulse full-width>
    ...
</x-pulse>

默认情况下，<x-pulse> 组件会创建一个 12 列的网格，但您可以使用 cols 属性进行自定义：

1<x-pulse cols="16">
2    ...
3</x-pulse>

<x-pulse cols="16">
    ...
</x-pulse>

每张卡片都接受 cols 和 rows 属性来控制空间和定位：

1<livewire:pulse.usage cols="4" rows="2" />

<livewire:pulse.usage cols="4" rows="2" />

大多数卡片还接受 expand 属性，以展开显示完整卡片而非滚动：

1<livewire:pulse.slow-queries expand />

<livewire:pulse.slow-queries expand />

解析用户

对于显示用户信息（如“应用程序使用情况”卡片）的卡片，Pulse 仅记录用户的 ID。在渲染仪表盘时，Pulse 会从您的默认 Authenticatable 模型中解析 name 和 email 字段，并使用 Gravatar 网络服务显示头像。

您可以通过在应用程序的 App\Providers\AppServiceProvider 类中调用 Pulse::user 方法来自定义这些字段和头像。

user 方法接受一个闭包，该闭包接收要显示的目标 Authenticatable 模型，并应返回一个包含用户 name、extra 和 avatar 信息的数组：

 1use Laravel\Pulse\Facades\Pulse;
 2 
 3/**
 4 * Bootstrap any application services.
 5 */
 6public function boot(): void
 7{
 8    Pulse::user(fn ($user) => [
 9        'name' => $user->name,
10        'extra' => $user->email,
11        'avatar' => $user->avatar_url,
12    ]);
13 
14    // ...
15}

use Laravel\Pulse\Facades\Pulse;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Pulse::user(fn ($user) => [
        'name' => $user->name,
        'extra' => $user->email,
        'avatar' => $user->avatar_url,
    ]);

    // ...
}

您可以通过实现 Laravel\Pulse\Contracts\ResolvesUsers 契约并将其绑定到 Laravel 的服务容器中，来完全自定义认证用户的捕获和获取方式。

卡片

服务器

<livewire:pulse.servers /> 卡片显示运行 pulse:check 命令的所有服务器的系统资源使用情况。有关系统资源报告的更多信息，请参阅关于服务器记录器的文档。

如果您更换了基础设施中的某台服务器，可能希望在一段持续时间后停止在 Pulse 仪表盘中显示该不活跃服务器。您可以使用 ignore-after 属性来实现，该属性接受不活跃服务器从 Pulse 仪表盘中移除前所需的秒数。或者，您可以提供一个相对时间格式的字符串，例如 1 hour 或 3 days and 1 hour：

1<livewire:pulse.servers ignore-after="3 hours" />

<livewire:pulse.servers ignore-after="3 hours" />

应用程序使用情况

<livewire:pulse.usage /> 卡片显示向应用程序发送请求、分发任务以及遇到慢请求的前 10 名用户。

如果您希望同时在屏幕上查看所有使用情况指标，可以多次引入该卡片并指定 type 属性：

1<livewire:pulse.usage type="requests" />
2<livewire:pulse.usage type="slow_requests" />
3<livewire:pulse.usage type="jobs" />

<livewire:pulse.usage type="requests" />
<livewire:pulse.usage type="slow_requests" />
<livewire:pulse.usage type="jobs" />

要了解如何自定义 Pulse 获取和显示用户信息的方式，请参阅我们关于解析用户的文档。

如果您的应用程序接收大量请求或分发大量任务，您可能希望启用采样。有关更多信息，请参阅用户请求记录器、用户任务记录器和慢任务记录器文档。

异常

<livewire:pulse.exceptions /> 卡片显示应用程序中发生的异常频率和近期记录。默认情况下，异常会根据异常类和发生位置进行分组。有关更多信息，请参阅异常记录器文档。

队列

<livewire:pulse.queues /> 卡片显示应用程序中队列的吞吐量，包括已排队、正在处理、已处理、已释放和失败的任务数量。有关更多信息，请参阅队列记录器文档。

慢请求

<livewire:pulse.slow-requests /> 卡片显示超过配置阈值（默认 1,000ms）的应用程序传入请求。有关更多信息，请参阅慢请求记录器文档。

慢任务

<livewire:pulse.slow-jobs /> 卡片显示超过配置阈值（默认 1,000ms）的应用程序队列任务。有关更多信息，请参阅慢任务记录器文档。

慢查询

<livewire:pulse.slow-queries /> 卡片显示超过配置阈值（默认 1,000ms）的数据库查询。

默认情况下，慢查询会根据 SQL 查询（不含绑定）和发生位置进行分组，但如果您只想根据 SQL 查询进行分组，也可以选择不捕获位置信息。

如果您因超长 SQL 查询的语法高亮渲染而遇到性能问题，可以通过添加 without-highlighting 属性来禁用高亮：

1<livewire:pulse.slow-queries without-highlighting />

<livewire:pulse.slow-queries without-highlighting />

有关更多信息，请参阅慢查询记录器文档。

慢传出请求

<livewire:pulse.slow-outgoing-requests /> 卡片显示使用 Laravel HTTP 客户端发出的超过配置阈值（默认 1,000ms）的传出请求。

默认情况下，条目将按完整 URL 进行分组。但是，您可能希望使用正则表达式来规范化或分组相似的传出请求。有关更多信息，请参阅慢传出请求记录器文档。

缓存

<livewire:pulse.cache /> 卡片显示应用程序的缓存命中和未命中统计信息，包括全局统计和单个 Key 的统计。

默认情况下，条目将按 Key 进行分组。但是，您可能希望使用正则表达式来规范化或分组相似的 Key。有关更多信息，请参阅缓存交互记录器文档。

捕获条目

大多数 Pulse 记录器会自动根据 Laravel 分发的框架事件捕获条目。但是，服务器记录器和某些第三方卡片必须定期轮询信息。要使用这些卡片，您必须在所有应用程序服务器上运行 pulse:check 守护进程：

1php artisan pulse:check

php artisan pulse:check

为了使 pulse:check 进程在后台永久运行，您应该使用 Supervisor 等进程监控工具来确保该命令不会停止运行。

由于 pulse:check 命令是一个长驻进程，它无法在不重启的情况下感知代码库的变更。您应该在应用程序部署过程中通过调用 pulse:restart 命令来优雅地重启该命令：

1php artisan pulse:restart

php artisan pulse:restart

Pulse 使用缓存来存储重启信号，因此在使用此功能之前，请确保已为您的应用程序正确配置了缓存驱动程序。

记录器

记录器负责从您的应用程序中捕获条目，并记录到 Pulse 数据库中。记录器在配置文件的 recorders 部分进行注册和配置。

缓存交互

CacheInteractions 记录器捕获应用程序中发生的缓存命中和未命中信息，以显示在缓存卡片上。

您可以选择调整采样率和忽略的 Key 模式。

您还可以配置 Key 分组，以便将相似的 Key 分组为单个条目。例如，您可能希望从缓存相同类型信息的 Key 中移除唯一 ID。分组是通过使用正则表达式“查找并替换”部分 Key 来配置的。配置文件中包含了一个示例。

1Recorders\CacheInteractions::class => [
2    // ...
3    'groups' => [
4        // '/:\d+/' => ':*',
5    ],
6],

Recorders\CacheInteractions::class => [
    // ...
    'groups' => [
        // '/:\d+/' => ':*',
    ],
],

将使用第一个匹配的模式。如果没有模式匹配，则 Key 将按原样捕获。

异常

Exceptions 记录器捕获应用程序中发生的可报告异常信息，以显示在异常卡片上。

您可以选择调整采样率和忽略的异常模式。您还可以配置是否捕获异常产生的原始位置。捕获的位置将显示在 Pulse 仪表盘上，这有助于追踪异常根源；但是，如果同一个异常发生在多个位置，它将为每个唯一位置显示多次。

队列

Queues 记录器捕获应用程序队列的相关信息，以显示在队列卡片上。

您可以选择调整采样率和忽略的任务模式。

慢任务

SlowJobs 记录器捕获应用程序中发生的慢任务信息，以显示在慢任务卡片上。

您可以选择调整慢任务阈值、采样率和忽略的任务模式。

您可能有一些任务预计会比其他任务执行时间更长。在这种情况下，您可以配置针对特定任务的阈值：

1Recorders\SlowJobs::class => [
2    // ...
3    'threshold' => [
4        '#^App\\Jobs\\GenerateYearlyReports$#' => 5000,
5        'default' => env('PULSE_SLOW_JOBS_THRESHOLD', 1000),
6    ],
7],

Recorders\SlowJobs::class => [
    // ...
    'threshold' => [
        '#^App\\Jobs\\GenerateYearlyReports$#' => 5000,
        'default' => env('PULSE_SLOW_JOBS_THRESHOLD', 1000),
    ],
],

如果没有正则表达式模式匹配任务的类名，则将使用 'default' 值。

慢传出请求

SlowOutgoingRequests 记录器捕获使用 Laravel HTTP 客户端发出的超过配置阈值的传出 HTTP 请求信息，以显示在慢传出请求卡片上。

您可以选择调整慢传出请求阈值、采样率和忽略的 URL 模式。

您可能有一些传出请求预计会比其他请求花费更长时间。在这种情况下，您可以配置针对特定请求的阈值：

1Recorders\SlowOutgoingRequests::class => [
2    // ...
3    'threshold' => [
4        '#backup.zip$#' => 5000,
5        'default' => env('PULSE_SLOW_OUTGOING_REQUESTS_THRESHOLD', 1000),
6    ],
7],

Recorders\SlowOutgoingRequests::class => [
    // ...
    'threshold' => [
        '#backup.zip$#' => 5000,
        'default' => env('PULSE_SLOW_OUTGOING_REQUESTS_THRESHOLD', 1000),
    ],
],

如果没有正则表达式模式匹配请求的 URL，则将使用 'default' 值。

您还可以配置 URL 分组，以便将相似的 URL 分组为单个条目。例如，您可能希望从 URL 路径中移除唯一 ID 或仅按域名进行分组。分组是通过使用正则表达式“查找并替换”部分 URL 来配置的。配置文件中包含一些示例：

1Recorders\SlowOutgoingRequests::class => [
2    // ...
3    'groups' => [
4        // '#^https://api\.github\.com/repos/.*$#' => 'api.github.com/repos/*',
5        // '#^https?://([^/]*).*$#' => '\1',
6        // '#/\d+#' => '/*',
7    ],
8],

Recorders\SlowOutgoingRequests::class => [
    // ...
    'groups' => [
        // '#^https://api\.github\.com/repos/.*$#' => 'api.github.com/repos/*',
        // '#^https?://([^/]*).*$#' => '\1',
        // '#/\d+#' => '/*',
    ],
],

将使用第一个匹配的模式。如果没有模式匹配，则 URL 将按原样捕获。

慢查询

SlowQueries 记录器捕获应用程序中超过配置阈值的任何数据库查询，以显示在慢查询卡片上。

您可以选择调整慢查询阈值、采样率和忽略的查询模式。您还可以配置是否捕获查询位置。捕获的位置将显示在 Pulse 仪表盘上，这有助于追踪查询根源；但是，如果相同的查询发生在多个位置，它将为每个唯一位置显示多次。

您可能有一些查询预计会比其他查询耗时更长。在这种情况下，您可以配置针对特定查询的阈值：

1Recorders\SlowQueries::class => [
2    // ...
3    'threshold' => [
4        '#^insert into `yearly_reports`#' => 5000,
5        'default' => env('PULSE_SLOW_QUERIES_THRESHOLD', 1000),
6    ],
7],

Recorders\SlowQueries::class => [
    // ...
    'threshold' => [
        '#^insert into `yearly_reports`#' => 5000,
        'default' => env('PULSE_SLOW_QUERIES_THRESHOLD', 1000),
    ],
],

如果没有正则表达式模式匹配查询的 SQL，则将使用 'default' 值。

慢请求

Requests 记录器捕获应用程序请求信息，以显示在慢请求和应用程序使用情况卡片上。

您可以选择调整慢路由阈值、采样率和忽略的路径。

您可能有一些请求预计会比其他请求耗时更长。在这种情况下，您可以配置针对特定请求的阈值：

1Recorders\SlowRequests::class => [
2    // ...
3    'threshold' => [
4        '#^/admin/#' => 5000,
5        'default' => env('PULSE_SLOW_REQUESTS_THRESHOLD', 1000),
6    ],
7],

Recorders\SlowRequests::class => [
    // ...
    'threshold' => [
        '#^/admin/#' => 5000,
        'default' => env('PULSE_SLOW_REQUESTS_THRESHOLD', 1000),
    ],
],

如果没有正则表达式模式匹配请求的 URL，则将使用 'default' 值。

服务器

Servers 记录器捕获支持应用程序的服务器的 CPU、内存和存储使用情况，以显示在服务器卡片上。此记录器需要在您希望监控的每台服务器上运行 pulse:check 命令。

每台报告服务器都必须有一个唯一的名称。默认情况下，Pulse 将使用 PHP 的 gethostname 函数返回的值。如果您希望自定义此名称，可以设置 PULSE_SERVER_NAME 环境变量：

1PULSE_SERVER_NAME=load-balancer

PULSE_SERVER_NAME=load-balancer

Pulse 配置文件还允许您自定义要监控的目录。

用户任务

UserJobs 记录器捕获应用程序中分发任务的用户信息，以显示在应用程序使用情况卡片上。

您可以选择调整采样率和忽略的任务模式。

用户请求

UserRequests 记录器捕获向应用程序发送请求的用户信息，以显示在应用程序使用情况卡片上。

您可以选择调整采样率和忽略的 URL 模式。

过滤

正如我们所见，许多记录器提供通过配置“忽略”传入条目的能力（基于其值，例如请求的 URL）。但有时，根据其他因素（例如当前认证的用户）过滤记录也是有用的。要过滤这些记录，您可以向 Pulse 的 filter 方法传递一个闭包。通常，filter 方法应在应用程序的 AppServiceProvider 的 boot 方法中调用：

 1use Illuminate\Support\Facades\Auth;
 2use Laravel\Pulse\Entry;
 3use Laravel\Pulse\Facades\Pulse;
 4use Laravel\Pulse\Value;
 5 
 6/**
 7 * Bootstrap any application services.
 8 */
 9public function boot(): void
10{
11    Pulse::filter(function (Entry|Value $entry) {
12        return Auth::user()->isNotAdmin();
13    });
14 
15    // ...
16}

use Illuminate\Support\Facades\Auth;
use Laravel\Pulse\Entry;
use Laravel\Pulse\Facades\Pulse;
use Laravel\Pulse\Value;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Pulse::filter(function (Entry|Value $entry) {
        return Auth::user()->isNotAdmin();
    });

    // ...
}

性能

Pulse 的设计旨在植入现有应用程序中，无需任何额外的基础设施。然而，对于高流量应用程序，有几种方法可以消除 Pulse 对应用程序性能可能产生的影响。

使用不同的数据库

对于高流量应用程序，您可能更倾向于为 Pulse 使用专用的数据库连接，以避免影响您的应用程序数据库。

您可以通过设置 PULSE_DB_CONNECTION 环境变量来自定义 Pulse 使用的数据库连接。

1PULSE_DB_CONNECTION=pulse

PULSE_DB_CONNECTION=pulse

Redis 摄入

Redis 摄入需要 Redis 6.2 或更高版本，且应用程序配置的 Redis 客户端驱动程序为 phpredis 或 predis。

默认情况下，在 HTTP 响应发送给客户端或任务被处理后，Pulse 会将条目直接存储到已配置的数据库连接中；但是，您可以使用 Pulse 的 Redis 摄入驱动程序将条目发送到 Redis 流。可以通过配置 PULSE_INGEST_DRIVER 环境变量来启用此功能：

1PULSE_INGEST_DRIVER=redis

PULSE_INGEST_DRIVER=redis

Pulse 默认会使用您的默认 Redis 连接，但您可以通过 PULSE_REDIS_CONNECTION 环境变量进行自定义：

1PULSE_REDIS_CONNECTION=pulse

PULSE_REDIS_CONNECTION=pulse

使用 Redis 摄入驱动程序时，如果适用，Pulse 安装应始终使用与 Redis 队列不同的 Redis 连接。

使用 Redis 摄入时，您需要运行 pulse:work 命令来监控流，并将条目从 Redis 移动到 Pulse 的数据库表中。

1php artisan pulse:work

php artisan pulse:work

为了使 pulse:work 进程在后台永久运行，您应该使用 Supervisor 等进程监控工具来确保 Pulse 工作进程不会停止运行。

由于 pulse:work 命令是一个长驻进程，它无法在不重启的情况下感知代码库的变更。您应该在应用程序部署过程中通过调用 pulse:restart 命令来优雅地重启该命令：

1php artisan pulse:restart

php artisan pulse:restart

Pulse 使用缓存来存储重启信号，因此在使用此功能之前，请确保已为您的应用程序正确配置了缓存驱动程序。

采样

默认情况下，Pulse 会捕获应用程序中发生的每一个相关事件。对于高流量应用程序，这可能导致需要在仪表盘中聚合数百万行数据库记录，尤其是在较长的时间段内。

您可以选择在某些 Pulse 数据记录器上启用“采样”。例如，在用户请求记录器上将采样率设置为 0.1，意味着您仅记录大约 10% 的应用程序请求。在仪表盘中，这些值会被放大，并带有 ~ 前缀，以表明它们是近似值。

通常，特定指标的条目越多，您在不牺牲太多准确性的前提下，可以将采样率设置得越低。

修剪

Pulse 会在存储的条目超出仪表盘展示时间窗后自动进行修剪。修剪操作在摄入数据时通过彩票系统进行，该系统可在 Pulse 配置文件中自定义。

处理 Pulse 异常

如果捕获 Pulse 数据时发生异常（例如无法连接到存储数据库），Pulse 将静默失败以避免影响您的应用程序。

如果您希望自定义这些异常的处理方式，可以向 handleExceptionsUsing 方法提供一个闭包：

1use Laravel\Pulse\Facades\Pulse;
2use Illuminate\Support\Facades\Log;
3 
4Pulse::handleExceptionsUsing(function ($e) {
5    Log::debug('An exception happened in Pulse', [
6        'message' => $e->getMessage(),
7        'stack' => $e->getTraceAsString(),
8    ]);
9});

use Laravel\Pulse\Facades\Pulse;
use Illuminate\Support\Facades\Log;

Pulse::handleExceptionsUsing(function ($e) {
    Log::debug('An exception happened in Pulse', [
        'message' => $e->getMessage(),
        'stack' => $e->getTraceAsString(),
    ]);
});

自定义卡片

Pulse 允许您构建自定义卡片，以显示满足您应用程序特定需求的数据。Pulse 使用 Livewire，因此在构建第一个自定义卡片之前，您可能需要查看其文档。

卡片组件

在 Laravel Pulse 中创建自定义卡片，始于继承基础的 Card Livewire 组件并定义相应的视图：

 1namespace App\Livewire\Pulse;
 2 
 3use Laravel\Pulse\Livewire\Card;
 4use Livewire\Attributes\Lazy;
 5 
 6#[Lazy]
 7class TopSellers extends Card
 8{
 9    public function render()
10    {
11        return view('livewire.pulse.top-sellers');
12    }
13}

namespace App\Livewire\Pulse;

use Laravel\Pulse\Livewire\Card;
use Livewire\Attributes\Lazy;

#[Lazy]
class TopSellers extends Card
{
    public function render()
    {
        return view('livewire.pulse.top-sellers');
    }
}

当使用 Livewire 的懒加载功能时，Card 组件会自动提供一个占位符，该占位符会遵循传递给您组件的 cols 和 rows 属性。

在编写 Pulse 卡片的相应视图时，您可以利用 Pulse 的 Blade 组件来实现一致的视觉风格：

 1<x-pulse::card :cols="$cols" :rows="$rows" :class="$class" wire:poll.5s="">
 2    <x-pulse::card-header name="Top Sellers">
 3        <x-slot:icon>
 4            ...
 5        </x-slot:icon>
 6    </x-pulse::card-header>
 7 
 8    <x-pulse::scroll :expand="$expand">
 9        ...
10    </x-pulse::scroll>
11</x-pulse::card>

<x-pulse::card :cols="$cols" :rows="$rows" :class="$class" wire:poll.5s="">
    <x-pulse::card-header name="Top Sellers">
        <x-slot:icon>
            ...
        </x-slot:icon>
    </x-pulse::card-header>

    <x-pulse::scroll :expand="$expand">
        ...
    </x-pulse::scroll>
</x-pulse::card>

$cols、$rows、$class 和 $expand 变量应传递给其各自的 Blade 组件，以便从仪表盘视图中自定义卡片布局。您可能还希望在视图中包含 wire:poll.5s="" 属性，以使卡片自动更新。

定义好 Livewire 组件和模板后，可以将该卡片包含在您的仪表盘视图中：

1<x-pulse>
2    ...
3 
4    <livewire:pulse.top-sellers cols="4" />
5</x-pulse>

<x-pulse>
    ...

    <livewire:pulse.top-sellers cols="4" />
</x-pulse>

如果您的卡片包含在包中，则需要使用 Livewire::component 方法向 Livewire 注册该组件。

样式

如果您的卡片需要 Pulse 包含的类和组件之外的额外样式，有几种方法可以为您的卡片包含自定义 CSS。

Laravel Vite 集成

如果您的自定义卡片位于应用程序的代码库中，并且您正在使用 Laravel 的 Vite 集成，您可以更新 vite.config.js 文件，为您的卡片包含一个专门的 CSS 入口点：

1laravel({
2    input: [
3        'resources/css/pulse/top-sellers.css',
4        // ...
5    ],
6}),

laravel({
    input: [
        'resources/css/pulse/top-sellers.css',
        // ...
    ],
}),

然后，您可以在仪表盘视图中使用 @vite Blade 指令，并指定卡片的 CSS 入口点：

1<x-pulse>
2    @vite('resources/css/pulse/top-sellers.css')
3 
4    ...
5</x-pulse>

<x-pulse>
    @vite('resources/css/pulse/top-sellers.css')

    ...
</x-pulse>

CSS 文件

对于其他使用场景（包括包中包含的 Pulse 卡片），您可以指示 Pulse 通过在 Livewire 组件上定义一个 css 方法来加载额外的样式表，该方法返回 CSS 文件的路径：

1class TopSellers extends Card
2{
3    // ...
4 
5    protected function css()
6    {
7        return __DIR__.'/../../dist/top-sellers.css';
8    }
9}

class TopSellers extends Card
{
    // ...

    protected function css()
    {
        return __DIR__.'/../../dist/top-sellers.css';
    }
}

当此卡片包含在仪表盘中时，Pulse 会自动将此文件的内容包含在 <style> 标签内，因此无需将其发布到 public 目录。

Tailwind CSS

使用 Tailwind CSS 时，您应该创建一个专门的 CSS 入口点。以下示例排除了 Tailwind 的 Preflight 基础样式（Pulse 已包含这些样式），并使用 CSS 选择器限定 Tailwind 的作用域，以避免与 Pulse 的 Tailwind 类发生冲突：

 1@import "tailwindcss/theme.css";
 2 
 3@custom-variant dark (&:where(.dark, .dark *));
 4@source "./../../views/livewire/pulse/top-sellers.blade.php";
 5 
 6@theme {
 7  /* ... */
 8}
 9 
10#top-sellers {
11  @import "tailwindcss/utilities.css" source(none);
12}

@import "tailwindcss/theme.css";

@custom-variant dark (&:where(.dark, .dark *));
@source "./../../views/livewire/pulse/top-sellers.blade.php";

@theme {
  /* ... */
}

#top-sellers {
  @import "tailwindcss/utilities.css" source(none);
}

您还需要在卡片的视图中包含一个 id 或 class 属性，以匹配入口点中的 CSS 选择器。

1<x-pulse::card id="top-sellers" :cols="$cols" :rows="$rows" class="$class">
2    ...
3</x-pulse::card>

<x-pulse::card id="top-sellers" :cols="$cols" :rows="$rows" class="$class">
    ...
</x-pulse::card>

数据捕获与聚合

自定义卡片可以从任何地方获取并显示数据；但您可能希望利用 Pulse 强大且高效的数据记录和聚合系统。

捕获条目

Pulse 允许您使用 Pulse::record 方法记录“条目”：

1use Laravel\Pulse\Facades\Pulse;
2 
3Pulse::record('user_sale', $user->id, $sale->amount)
4    ->sum()
5    ->count();

use Laravel\Pulse\Facades\Pulse;

Pulse::record('user_sale', $user->id, $sale->amount)
    ->sum()
    ->count();

提供给 record 方法的第一个参数是您正在记录的条目的 type，第二个参数是决定如何对聚合数据进行分组的 key。对于大多数聚合方法，您还需要指定要聚合的 value。在上面的示例中，被聚合的值是 $sale->amount。然后，您可以调用一个或多个聚合方法（如 sum），以便 Pulse 可以将预聚合的值捕获到“桶（buckets）”中，以便日后高效检索。

可用的聚合方法包括：

avg（平均值）
count（计数）
max（最大值）
min（最小值）
sum（求和）

在构建捕获当前认证用户 ID 的卡片包时，您应该使用 Pulse::resolveAuthenticatedUserId() 方法，该方法会遵循应用程序中已做的任何用户解析器自定义。

获取聚合数据

在扩展 Pulse 的 Card Livewire 组件时，可以使用 aggregate 方法检索仪表盘中所查看时间段的聚合数据：

1class TopSellers extends Card
2{
3    public function render()
4    {
5        return view('livewire.pulse.top-sellers', [
6            'topSellers' => $this->aggregate('user_sale', ['sum', 'count'])
7        ]);
8    }
9}

class TopSellers extends Card
{
    public function render()
    {
        return view('livewire.pulse.top-sellers', [
            'topSellers' => $this->aggregate('user_sale', ['sum', 'count'])
        ]);
    }
}

aggregate 方法返回一个 PHP stdClass 对象的集合。每个对象将包含之前捕获的 key 属性，以及每个所请求聚合值的键。

1@foreach ($topSellers as $seller)
2    {{ $seller->key }}
3    {{ $seller->sum }}
4    {{ $seller->count }}
5@endforeach

@foreach ($topSellers as $seller)
    {{ $seller->key }}
    {{ $seller->sum }}
    {{ $seller->count }}
@endforeach

Pulse 主要从预聚合的桶中检索数据；因此，指定的聚合值必须已使用 Pulse::record 方法提前捕获。最旧的桶通常会部分落在时间段之外，因此 Pulse 会聚合最旧的条目来填补缺口，并为整个时间段提供准确的值，而无需在每次轮询请求时聚合整个时间段。

您还可以使用 aggregateTotal 方法获取给定类型的总值。例如，以下方法将检索所有用户销售额的总和，而不是按用户分组：

1$total = $this->aggregateTotal('user_sale', 'sum');

$total = $this->aggregateTotal('user_sale', 'sum');

显示用户

当处理将用户 ID 作为 Key 记录的聚合时，可以使用 Pulse::resolveUsers 方法将 Key 解析为用户记录：

 1$aggregates = $this->aggregate('user_sale', ['sum', 'count']);
 2 
 3$users = Pulse::resolveUsers($aggregates->pluck('key'));
 4 
 5return view('livewire.pulse.top-sellers', [
 6    'sellers' => $aggregates->map(fn ($aggregate) => (object) [
 7        'user' => $users->find($aggregate->key),
 8        'sum' => $aggregate->sum,
 9        'count' => $aggregate->count,
10    ])
11]);

$aggregates = $this->aggregate('user_sale', ['sum', 'count']);

$users = Pulse::resolveUsers($aggregates->pluck('key'));

return view('livewire.pulse.top-sellers', [
    'sellers' => $aggregates->map(fn ($aggregate) => (object) [
        'user' => $users->find($aggregate->key),
        'sum' => $aggregate->sum,
        'count' => $aggregate->count,
    ])
]);

find 方法返回一个包含 name、extra 和 avatar 键的对象，您可以选择将其直接传递给 <x-pulse::user-card> Blade 组件。

1<x-pulse::user-card :user="{{ $seller->user }}" :stats="{{ $seller->sum }}" />

<x-pulse::user-card :user="{{ $seller->user }}" :stats="{{ $seller->sum }}" />

自定义记录器

包作者可能希望提供记录器类，以允许用户配置数据捕获方式。

记录器在应用程序的 config/pulse.php 配置文件的 recorders 部分注册：

 1[
 2    // ...
 3    'recorders' => [
 4        Acme\Recorders\Deployments::class => [
 5            // ...
 6        ],
 7 
 8        // ...
 9    ],
10]

[
    // ...
    'recorders' => [
        Acme\Recorders\Deployments::class => [
            // ...
        ],

        // ...
    ],
]

记录器可以通过指定 $listen 属性来监听事件。Pulse 会自动注册监听器并调用记录器的 record 方法：

 1<?php
 2 
 3namespace Acme\Recorders;
 4 
 5use Acme\Events\Deployment;
 6use Illuminate\Support\Facades\Config;
 7use Laravel\Pulse\Facades\Pulse;
 8 
 9class Deployments
10{
11    /**
12     * The events to listen for.
13     *
14     * @var array<int, class-string>
15     */
16    public array $listen = [
17        Deployment::class,
18    ];
19 
20    /**
21     * Record the deployment.
22     */
23    public function record(Deployment $event): void
24    {
25        $config = Config::get('pulse.recorders.'.static::class);
26 
27        Pulse::record(
28            // ...
29        );
30    }
31}

<?php

namespace Acme\Recorders;

use Acme\Events\Deployment;
use Illuminate\Support\Facades\Config;
use Laravel\Pulse\Facades\Pulse;

class Deployments
{
    /**
     * The events to listen for.
     *
     * @var array<int, class-string>
     */
    public array $listen = [
        Deployment::class,
    ];

    /**
     * Record the deployment.
     */
    public function record(Deployment $event): void
    {
        $config = Config::get('pulse.recorders.'.static::class);

        Pulse::record(
            // ...
        );
    }
}

Laravel Pulse

在此页面上

产品

Packages

资源

合作伙伴