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

資源

合作伙伴