コンテンツにスキップ
Laravel

Laravel Pulse

はじめに

Laravel Pulse は、アプリケーションのパフォーマンスと使用状況に関する一目でわかる洞察を提供します。Pulseを使用すると、遅いジョブやエンドポイントなどのボトルネックを追跡し、最もアクティブなユーザーを見つけることができます。

個々のイベントの詳細なデバッグについては、Laravel Telescope を確認してください。

インストール

exclamation

Pulseのファーストパーティストレージの実装では、現在、MySQL、MariaDB、またはPostgreSQLデータベースが必要です。異なるデータベースエンジンを使用している場合は、Pulseデータ用に別のMySQL、MariaDB、またはPostgreSQLデータベースが必要になります。

Pulseは、Composerパッケージマネージャーを使用してインストールできます

composer require laravel/pulse

次に、`vendor:publish` Artisanコマンドを使用して、Pulseの設定およびマイグレーションファイルを公開する必要があります

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

最後に、Pulseのデータを保存するために必要なテーブルを作成するために、`migrate`コマンドを実行する必要があります

php artisan migrate

Pulseのデータベースマイグレーションが実行されると、`/pulse`ルートを介してPulseダッシュボードにアクセスできます。

lightbulb

Pulseデータをアプリケーションのプライマリデータベースに保存したくない場合は、専用のデータベース接続を指定できます。

設定

Pulseの構成オプションの多くは、環境変数を使用して制御できます。利用可能なオプションを確認したり、新しいレコーダーを登録したり、高度なオプションを構成したりするには、`config/pulse.php`構成ファイルを公開できます

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

ダッシュボード

認可

Pulseダッシュボードには、`/pulse`ルートを介してアクセスできます。デフォルトでは、このダッシュボードには`local`環境でのみアクセスできるため、`'viewPulse'`認証ゲートをカスタマイズして、本番環境の認証を構成する必要があります。これは、アプリケーションの`app/Providers/AppServiceProvider.php`ファイル内で行うことができます

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`に公開されます

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

ダッシュボードはLivewireによって駆動されており、JavaScriptアセットを再構築することなく、カードとレイアウトをカスタマイズできます。

このファイル内で、`<x-pulse>`コンポーネントがダッシュボードのレンダリングを担当し、カードのグリッドレイアウトを提供します。ダッシュボードを画面の全幅にまたがらせたい場合は、コンポーネントに`full-width` propを指定できます

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

デフォルトでは、`<x-pulse>`コンポーネントは12列のグリッドを作成しますが、`cols` propを使用してこれをカスタマイズできます

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

各カードは、スペースと位置を制御するための`cols`と`rows` propを受け入れます

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

ほとんどのカードは、スクロールする代わりにカード全体を表示するための`expand` propも受け入れます

<livewire:pulse.slow-queries expand />

ユーザーの解決

アプリケーション使用状況カードなど、ユーザーに関する情報を表示するカードの場合、PulseはユーザーのIDのみを記録します。ダッシュボードをレンダリングすると、Pulseはデフォルトの`Authenticatable`モデルから`name`フィールドと`email`フィールドを解決し、Gravatar Webサービスを使用してアバターを表示します。

`Pulse::user`メソッドをアプリケーションの`App\Providers\AppServiceProvider`クラス内で呼び出すことで、フィールドとアバターをカスタマイズできます。

`user`メソッドは、表示する`Authenticatable`モデルを受け取るクロージャを受け入れ、ユーザーの`name`、`extra`、および`avatar`情報を含む配列を返す必要があります

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,
    ]);
 
    // ...
}
lightbulb

認証済みユーザーをキャプチャおよび取得する方法を完全にカスタマイズするには、`Laravel\Pulse\Contracts\ResolvesUsers`コントラクトを実装し、Laravelのサービスコンテナにバインドします。

カード

サーバー

`<livewire:pulse.servers />`カードは、`pulse:check`コマンドを実行しているすべてのサーバーのシステムリソース使用量を表示します。システムリソースレポートの詳細については、サーバーレコーダーに関するドキュメントを参照してください。

インフラストラクチャ内のサーバーを置き換える場合は、指定された期間後にPulseダッシュボードに非アクティブなサーバーが表示されないようにすることができます。これは、非アクティブなサーバーをPulseダッシュボードから削除するまでの秒数を受け入れる`ignore-after` propを使用することで実現できます。または、`1 hour`や`3 days and 1 hour`などの相対時間形式の文字列を指定することもできます。

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

アプリケーションの使用状況

`<livewire:pulse.usage />`カードは、アプリケーションにリクエストを送信したり、ジョブをディスパッチしたり、遅いリクエストを経験したりする上位10人のユーザーを表示します。

すべての使用状況メトリックを画面に同時に表示する場合は、カードを複数回含めて、`type`属性を指定できます

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

Pulseがユーザー情報を取得および表示する方法をカスタマイズする方法については、ユーザーの解決に関するドキュメントを参照してください。

lightbulb

アプリケーションが大量のリクエストを受信したり、大量のジョブをディスパッチしたりする場合は、サンプリングを有効にすることをお勧めします。詳細については、ユーザーリクエストレコーダー、ユーザージョブレコーダー、および遅いジョブレコーダーのドキュメントを参照してください。

例外

`<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` propを追加して強調表示を無効にすることができます

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

詳細については、遅いクエリレコーダーのドキュメントを参照してください。

遅い送信リクエスト

`<livewire:pulse.slow-outgoing-requests />`カードは、LaravelのHTTPクライアントを使用して行われた、構成されたしきい値（デフォルトでは1,000ミリ秒）を超える送信リクエストを表示します。

デフォルトでは、エントリは完全なURLでグループ化されます。ただし、正規表現を使用して、類似の送信リクエストを正規化またはグループ化することもできます。詳細については、遅い送信リクエストレコーダーのドキュメントを参照してください。

キャッシュ

`<livewire:pulse.cache />`カードは、アプリケーションのキャッシュヒットとミス統計を、グローバルと個々のキーの両方について表示します。

デフォルトでは、エントリはキーごとにグループ化されます。ただし、正規表現を使用して、類似のキーを正規化またはグループ化したい場合があります。詳細については、キャッシュインタラクションレコーダーのドキュメントを参照してください。

エントリのキャプチャ

ほとんどのPulseレコーダーは、Laravelによってディスパッチされたフレームワークイベントに基づいて、自動的にエントリをキャプチャします。ただし、サーバーレコーダーや一部のサードパーティ製カードは、情報を定期的にポーリングする必要があります。これらのカードを使用するには、個々のアプリケーションサーバーすべてでpulse:checkデーモンを実行する必要があります。

php artisan pulse:check
lightbulb

pulse:checkプロセスをバックグラウンドで永続的に実行し続けるには、Supervisorなどのプロセスモニターを使用して、コマンドが停止しないようにする必要があります。

pulse:checkコマンドは長時間実行されるプロセスであるため、再起動しない限りコードベースへの変更は認識されません。アプリケーションのデプロイプロセス中にpulse:restartコマンドを呼び出して、コマンドを正常に再起動する必要があります。

php artisan pulse:restart
lightbulb

Pulseは、再起動シグナルを保存するためにキャッシュを使用するため、この機能を使用する前に、アプリケーションにキャッシュドライバーが適切に構成されていることを確認する必要があります。

レコーダー

レコーダーは、Pulseデータベースに記録されるアプリケーションからのエントリをキャプチャする役割を担います。レコーダーは、Pulse構成ファイルのrecordersセクションで登録および構成されます。

キャッシュインタラクション

CacheInteractionsレコーダーは、キャッシュのヒットとミスに関する情報をキャプチャし、キャッシュカードに表示します。

オプションで、サンプルレートと無視するキーパターンを調整できます。

また、類似したキーが単一のエントリとしてグループ化されるように、キーグループ化を構成することもできます。たとえば、同じ種類の情報をキャッシュするキーから一意のIDを削除したい場合があります。グループは、キーの一部を「検索と置換」するための正規表現を使用して構成されます。例は構成ファイルに含まれています。

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

最初に一致したパターンが使用されます。一致するパターンがない場合、キーはそのままキャプチャされます。

例外

Exceptionsレコーダーは、アプリケーションで発生した報告可能な例外に関する情報をキャプチャし、例外カードに表示します。

オプションで、サンプルレートと無視する例外パターンを調整できます。また、例外の発生元となった場所をキャプチャするかどうかを構成することもできます。キャプチャされた場所はPulseダッシュボードに表示され、例外の発生元を追跡するのに役立ちますが、同じ例外が複数の場所で発生した場合、一意の場所ごとに複数回表示されます。

キュー

Queuesレコーダーは、キューに表示するために、アプリケーションのキューに関する情報をキャプチャします。

オプションで、サンプルレートと無視するジョブパターンを調整できます。

遅いジョブ

SlowJobsレコーダーは、アプリケーションで発生した低速ジョブに関する情報をキャプチャし、低速ジョブカードに表示します。

オプションで、低速ジョブのしきい値、サンプルレート、および無視するジョブパターンを調整できます。

他のジョブよりも時間がかかることが予想されるジョブがある場合があります。その場合は、ジョブごとのしきい値を構成できます。

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

ジョブのクラス名に一致する正規表現パターンがない場合、'default'値が使用されます。

遅い送信リクエスト

SlowOutgoingRequestsレコーダーは、LaravelのHTTPクライアントを使用して行われた、構成されたしきい値を超えるHTTPリクエストに関する情報をキャプチャし、低速な送信リクエストカードに表示します。

オプションで、低速な送信リクエストのしきい値、サンプルレート、および無視するURLパターンを調整できます。

他のリクエストよりも時間がかかることが予想される送信リクエストがある場合があります。その場合は、リクエストごとのしきい値を構成できます。

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

リクエストのURLに一致する正規表現パターンがない場合、'default'値が使用されます。

また、類似したURLが単一のエントリとしてグループ化されるように、URLグループ化を構成することもできます。たとえば、URLパスから一意のIDを削除したり、ドメインのみでグループ化したりしたい場合があります。グループは、URLの一部を「検索と置換」するための正規表現を使用して構成されます。例は構成ファイルに含まれています。

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

最初に一致したパターンが使用されます。一致するパターンがない場合、URLはそのままキャプチャされます。

遅いクエリ

SlowQueriesレコーダーは、アプリケーション内の構成されたしきい値を超えるデータベースクエリをキャプチャし、低速クエリカードに表示します。

オプションで、低速クエリのしきい値、サンプルレート、および無視するクエリパターンを調整できます。また、クエリの場所をキャプチャするかどうかを構成することもできます。キャプチャされた場所はPulseダッシュボードに表示され、クエリの発生元を追跡するのに役立ちますが、同じクエリが複数の場所で行われた場合、一意の場所ごとに複数回表示されます。

他のクエリよりも時間がかかることが予想されるクエリがある場合があります。その場合は、クエリごとのしきい値を構成できます。

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

クエリのSQLに一致する正規表現パターンがない場合、'default'値が使用されます。

遅いリクエスト

Requestsレコーダーは、アプリケーションへのリクエストに関する情報をキャプチャし、低速リクエストカードとアプリケーション使用量カードに表示します。

オプションで、低速ルートのしきい値、サンプルレート、および無視するパスを調整できます。

他のリクエストよりも時間がかかることが予想されるリクエストがある場合があります。その場合は、リクエストごとのしきい値を構成できます。

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環境変数を設定できます。

PULSE_SERVER_NAME=load-balancer

Pulse構成ファイルでは、監視するディレクトリをカスタマイズすることもできます。

ユーザー ジョブ

UserJobsレコーダーは、アプリケーションでジョブをディスパッチするユーザーに関する情報をキャプチャし、アプリケーション使用量カードに表示します。

オプションで、サンプルレートと無視するジョブパターンを調整できます。

ユーザー リクエスト

UserRequestsレコーダーは、アプリケーションにリクエストを行うユーザーに関する情報をキャプチャし、アプリケーション使用量カードに表示します。

オプションで、サンプルレートと無視するURLパターンを調整できます。

フィルタリング

これまで見てきたように、多くのレコーダーは、リクエストのURLなど、値に基づいて受信エントリを「無視」する機能を構成によって提供します。ただし、現在認証されているユーザーなど、他の要因に基づいてレコードをフィルタリングすることが便利な場合もあります。これらのレコードをフィルタリングするには、Pulseのfilterメソッドにクロージャを渡すことができます。通常、filterメソッドはアプリケーションのAppServiceProviderのbootメソッド内で呼び出す必要があります。

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で使用されるデータベース接続をカスタマイズできます。

PULSE_DB_CONNECTION=pulse

Redisインジェスト

exclamation

Redis Ingestには、Redis 6.2以上と、アプリケーションの構成済みRedisクライアントドライバーとしてのphpredisまたはpredisが必要です。

デフォルトでは、Pulseは、HTTPレスポンスがクライアントに送信された後、またはジョブが処理された後、構成済みのデータベース接続に直接エントリを保存します。ただし、PulseのRedisインジェストドライバーを使用して、代わりにRedisストリームにエントリを送信することもできます。これは、PULSE_INGEST_DRIVER環境変数を構成することで有効にできます。

PULSE_INGEST_DRIVER=redis

PulseはデフォルトでデフォルトのRedis接続を使用しますが、PULSE_REDIS_CONNECTION環境変数を介してこれをカスタマイズできます。

PULSE_REDIS_CONNECTION=pulse

Redisインジェストを使用する場合は、pulse:workコマンドを実行して、ストリームを監視し、RedisからPulseのデータベーステーブルにエントリを移動する必要があります。

php artisan pulse:work
lightbulb

pulse:workプロセスをバックグラウンドで永続的に実行し続けるには、Supervisorなどのプロセスモニターを使用して、Pulseワーカーが停止しないようにする必要があります。

pulse:workコマンドは長時間実行されるプロセスであるため、再起動しない限りコードベースへの変更は認識されません。アプリケーションのデプロイプロセス中にpulse:restartコマンドを呼び出して、コマンドを正常に再起動する必要があります。

php artisan pulse:restart
lightbulb

Pulseは、再起動シグナルを保存するためにキャッシュを使用するため、この機能を使用する前に、アプリケーションにキャッシュドライバーが適切に構成されていることを確認する必要があります。

サンプリング

デフォルトでは、Pulseはアプリケーションで発生するすべての関連イベントをキャプチャします。トラフィックの多いアプリケーションの場合、特に長期間の場合、ダッシュボードで数百万行のデータベース行を集計する必要が生じる可能性があります。

代わりに、特定のPulseデータレコーダーで「サンプリング」を有効にすることを選択できます。たとえば、User Requestsレコーダーでサンプルレートを0.1に設定すると、アプリケーションへのリクエストの約10％のみが記録されることになります。ダッシュボードでは、値はスケールアップされ、近似値であることを示すために〜がプレフィックスとして付加されます。

一般に、特定のメトリックのエントリが多いほど、精度をあまり損なうことなく、安全にサンプルレートを低く設定できます。

トリミング

Pulseは、保存されたエントリがダッシュボードウィンドウの外に出ると、自動的にトリミングします。トリミングは、Pulseの構成ファイルでカスタマイズできる宝くじシステムを使用してデータをインジェストするときに発生します。

Pulse例外の処理

ストレージデータベースに接続できないなど、Pulseデータのキャプチャ中に例外が発生した場合、Pulseはアプリケーションに影響を与えないように、通知なしに失敗します。

これらの例外の処理方法をカスタマイズする場合は、handleExceptionsUsingメソッドにクロージャを提供できます。

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コンポーネントを拡張し、対応するビューを定義することから始めます。

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コンポーネントを利用して、一貫したルックアンドフィールを実現できます。

<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コンポーネントとテンプレートを定義したら、カードをダッシュボードビューに含めることができます。

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

カードがパッケージに含まれている場合は、Livewire::componentメソッドを使用して、コンポーネントをLivewireに登録する必要があります。

スタイリング

Pulseに含まれているクラスやコンポーネント以外に追加のスタイルが必要な場合は、カードにカスタムCSSを含めるためのいくつかのオプションがあります。

Laravel Vite統合

カスタムカードがアプリケーションのコードベース内にあり、LaravelのVite統合を使用している場合は、vite.config.jsファイルを更新して、カード専用のCSSエントリポイントを含めることができます。

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

その後、カードのCSSエントリポイントを指定して、ダッシュボードビューで@vite Bladeディレクティブを使用できます。

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

CSSファイル

パッケージに含まれるPulseカードなど、他のユースケースでは、LivewireコンポーネントにCSSファイルのファイルパスを返すcssメソッドを定義することで、Pulseに追加のスタイルシートを読み込むように指示できます。

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

このカードがダッシュボードに含まれると、Pulseはこのファイルの内容を<style>タグ内に自動的に含めるため、publicディレクトリに公開する必要はありません。

Tailwind CSS

Tailwind CSSを使用する場合は、不要なCSSの読み込みやPulseのTailwindクラスとの競合を避けるために、専用のTailwind構成ファイルを作成する必要があります。

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

次に、CSSエントリポイントで構成ファイルを指定できます。

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

また、Tailwindのimportantセレクタ戦略に渡されるセレクタに一致するidまたはclass属性をカードのビューに含める必要があります。

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

データキャプチャと集計

カスタムカードはどこからでもデータを取得して表示できます。ただし、Pulseの強力で効率的なデータ記録および集計システムを活用することもできます。

エントリのキャプチャ

Pulseでは、Pulse::recordメソッドを使用して「エントリ」を記録できます。

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

recordメソッドに提供される最初の引数は、記録するエントリのtypeであり、2番目の引数は、集計されたデータのグループ化方法を決定するkeyです。ほとんどの集計方法では、集計するvalueも指定する必要があります。上記の例では、集計されている値は$sale->amountです。次に、1つ以上の集計メソッド（sumなど）を呼び出して、Pulseが事前に集計された値を「バケット」に取り込み、後で効率的に取得できるようにすることができます。

使用可能な集計メソッドは次のとおりです。

  • avg
  • count
  • max
  • min
  • sum
lightbulb

現在認証されているユーザーIDをキャプチャするカードパッケージを構築する場合は、アプリケーションに対して行われたユーザーリゾルバーのカスタマイズを尊重するPulse::resolveAuthenticatedUserId()メソッドを使用する必要があります。

集計データの取得

PulseのCard Livewireコンポーネントを拡張する場合は、aggregateメソッドを使用して、ダッシュボードに表示されている期間の集計データを取得できます。

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

aggregateメソッドは、PHPのstdClassオブジェクトのコレクションを返します。各オブジェクトには、以前にキャプチャされたkeyプロパティと、要求された各集計のキーが含まれます。

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

Pulseは主に事前に集計されたバケットからデータを取得します。したがって、指定された集計は、Pulse::recordメソッドを使用して事前にキャプチャされている必要があります。最も古いバケットは通常、期間の一部に該当しないため、Pulseは最も古いエントリを集計してギャップを埋め、各ポーリングリクエストで期間全体を集計する必要なく、期間全体の正確な値を提示します。

また、aggregateTotalメソッドを使用して、特定のタイプの合計値を取得することもできます。たとえば、次のメソッドは、ユーザーごとのグループ化ではなく、すべてのユーザーの売上の合計を取得します。

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

ユーザーの表示

ユーザーIDをキーとして記録する集計を使用する場合は、Pulse::resolveUsersメソッドを使用してキーをユーザーレコードに解決できます。

$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コンポーネントに直接渡すことができます。

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

カスタムレコーダー

パッケージの作成者は、ユーザーがデータのキャプチャを構成できるように、レコーダークラスを提供したい場合があります。

レコーダーは、アプリケーションのconfig/pulse.php構成ファイルのrecordersセクションに登録されます。

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

レコーダーは、$listenプロパティを指定することにより、イベントをリッスンできます。Pulseは、リスナーを自動的に登録し、レコーダーのrecordメソッドを呼び出します。

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