Laravel Pulse

Introduction
Installation
- Configuration
Dashboard
Capturing Entries
- Recorders
- Filtering
Performance
Custom Cards

介绍

Laravel Pulse提供应用程序性能和使用情况的概览。借助 Pulse，您可以追踪运行缓慢的作业和端点等瓶颈，找到最活跃的用户等等。

要深入调试单个事件，请查看Laravel Telescope。

安装

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

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

1composer require laravel/pulse

composer require laravel/pulse

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

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 会解析默认模型中的name和字段，并使用 Gravatar Web 服务显示头像。emailAuthenticatable

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

该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您可以通过实施Contracts并将其绑定到 Laravel 的服务容器中来完全自定义如何捕获和检索经过身份验证的用户。

牌

服务器

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

如果您更换了基础架构中的服务器，您可能希望在给定的时间间隔后停止在 Pulse 仪表板中显示非Events服务器。您可以使用ignore-after属性来实现此目的，该属性接受应在多少秒后从 Pulse 仪表板中移除非Events服务器。或者，您可以提供一个相对时间格式的字符串，例如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,000 毫秒）。有关更多信息，请参阅慢速请求记录器文档。

缓慢的工作

该<livewire:pulse.slow-jobs />卡片会显示应用程序中超过配置阈值（默认为 1,000 毫秒）的排队作业。有关更多信息，请参阅慢速作业记录器文档。

慢查询

该<livewire:pulse.slow-queries />卡片显示应用程序中超过配置阈值（默认为 1,000 毫秒）的数据库查询。

默认情况下，慢速查询根据 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,000 毫秒。

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

缓存

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

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

捕获条目

大多数 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 数据库中的条目。记录器在Pulse 配置文件recorders的部分中注册和配置。

缓存交互

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

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

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

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

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

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

例外

记录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'则将使用该值。

缓慢的传出请求

记录器捕获使用 Laravel 的HTTP 客户端发出的超出配置阈值的SlowOutgoingRequests传出 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方法应该在boot应用程序的方法中调用AppServiceProvider：

 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 使用的数据库连接PULSE_DB_CONNECTION。

1PULSE_DB_CONNECTION=pulse

PULSE_DB_CONNECTION=pulse

Redis 摄取

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

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

1PULSE_INGEST_DRIVER=redis

PULSE_INGEST_DRIVER=redis

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

1PULSE_REDIS_CONNECTION=pulse

PULSE_REDIS_CONNECTION=pulse

当使用 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 中创建自定义卡片首先要扩展基本CardLivewire 组件并定义相应的视图：

 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、、和变量应传递给相应的 Blade 组件，以便可以从仪表板视图自定义卡片布局。您可能还希望在视图中包含$rows属性，以使卡片自动更新。$class$expandwire: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 卡，您可以通过css在 Livewire 组件上定义一个返回 CSS 文件路径的方法来指示 Pulse 加载其他样式表：

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 时，您应该创建专用的 Tailwind 配置文件，以避免加载不必要的 CSS 或与 Pulse 的 Tailwind 类冲突：

 1export default {
 2    darkMode: 'class',
 3    important: '#top-sellers',
 4    content: [
 5        './resources/views/livewire/pulse/top-sellers.blade.php',
 6    ],
 7    corePlugins: {
 8        preflight: false,
 9    },
10};

export default {
    darkMode: 'class',
    important: '#top-sellers',
    content: [
        './resources/views/livewire/pulse/top-sellers.blade.php',
    ],
    corePlugins: {
        preflight: false,
    },
};

然后您可以在 CSS 入口点中指定配置文件：

1@config "../../tailwind.top-sellers.config.js";
2@tailwind base;
3@tailwind components;
4@tailwind utilities;

@config "../../tailwind.top-sellers.config.js";
@tailwind base;
@tailwind components;
@tailwind utilities;

您还需要在卡片视图中包含一个id或属性，该属性与传递给 Tailwind 的重要选择器策略的选择器相匹配：class

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 可以将预聚合的值捕获到“存储桶”中，以便稍后高效检索。

可用的聚合方法有：

avg
count
max
min
sum

在构建捕获当前已验证用户 ID 的卡包时，您应该使用Pulse::resolveAuthenticatedUserId()尊重对应用程序所做的任何用户解析器自定义的方法。

检索聚合数据

扩展 Pulse 的CardLivewire 组件时，您可以使用该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 主要从预先聚合的 bucket 中检索数据；因此，指定的聚合必须已使用该方法预先捕获Pulse::record。最旧的 bucket 通常会部分超出周期范围，因此 Pulse 会聚合最旧的条目以填补空白，并给出整个周期的准确值，而无需在每次轮询请求时都聚合整个周期。

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

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

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

显示用户

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

 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 }}" />

定制录音机

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

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

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

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

        // ...
    ],
]

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

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

Prologue

Getting Started

Architecture Concepts

The Basics

Digging Deeper

Security

Database

Eloquent ORM

Testing

Packages

Laravel Pulse

本页内容