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,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' 值。

慢速傳出請求

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 或更高版本，以及 phpredis 或 predis 作為應用程式設定的 Redis 客戶端驅動程式。

預設情況下，Pulse 會在 HTTP 回應傳送給客戶端或工作處理完成後，直接將條目儲存到設定的資料庫連線；但是，您可以使用 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: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 資料記錄器上啟用「取樣」。例如，在 User Requests 記錄器上將取樣率設定為 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 時，您應該建立一個專用的 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 或 class 屬性，該屬性與傳遞給 Tailwind 的 important 選擇器策略的選擇器相符

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 的 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 記錄為鍵的彙總時，您可以使用 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 }}" />

自訂記錄器

套件作者可能會希望提供記錄器類別，以允許使用者設定資料擷取。

記錄器會在應用程式 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(
            // ...
        );
    }
}

前言

開始使用

架構概念

基礎知識

深入探討

安全性

資料庫

Eloquent ORM

測試

套件

Laravel Pulse

產品

套件

資源