Pulse

• Introduzione
• Installazione
• Dashboard
• Acquisizione delle Voci
• Performance
• Schede Personalizzate

Introduzione

Laravel Pulse fornisce una panoramica immediata delle prestazioni e dell’utilizzo della tua applicazione. Con Pulse, puoi individuare colli di bottiglia come job e endpoint lenti, trovare i tuoi utenti più attivi e altro ancora.

Per un debug approfondito di eventi individuali, consulta Laravel Telescope.

Installazione

L’implementazione dello storage di prima parte di Pulse attualmente richiede un database MySQL, MariaDB o PostgreSQL. Se stai utilizzando un motore di database diverso, avrai bisogno di un database separato MySQL, MariaDB o PostgreSQL per i dati di Pulse.

Puoi installare Pulse usando il package manager Composer:

composer require laravel/pulse

Successivamente, dovresti pubblicare i file di configurazione e migrazione di Pulse usando il comando vendor:publish di Artisan:

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

Infine, dovresti eseguire il comando migrate per creare le tabelle necessarie a memorizzare i dati di Pulse:

php artisan migrate

Una volta eseguite le migrazioni del database di Pulse, puoi accedere al dashboard di Pulse tramite la rotta /pulse.

Se non vuoi memorizzare i dati di Pulse nel database principale della tua applicazione, puoi specificare una connessione database dedicata.

Configurazione

Molte opzioni di configurazione di Pulse possono essere controllate utilizzando variabili d’ambiente. Per vedere le opzioni disponibili, registrare nuovi recorders o configurare opzioni avanzate, puoi pubblicare il file di configurazione config/pulse.php:

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

Dashboard

Autorizzazione

La dashboard di Pulse è accessibile tramite la rotta /pulse. Di default, potrai accedere a questa dashboard solo nell’ambiente local, quindi dovrai configurare l’autorizzazione per gli ambienti di produzione personalizzando la gate di autorizzazione 'viewPulse'. Puoi fare questo nel file app/Providers/AppServiceProvider.php della tua applicazione:

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

    // ...
}

Personalizzazione

Le schede e il layout della dashboard Pulse possono essere configurati pubblicando la vista della dashboard. La vista della dashboard sarà pubblicata in resources/views/vendor/pulse/dashboard.blade.php:

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

La dashboard utilizza Livewire e ti permette di personalizzare le schede e il layout senza dover ricostruire alcun asset JavaScript.

All’interno di questo file, il componente <x-pulse> è responsabile del rendering della dashboard e fornisce un layout a griglia per le schede. Se desideri che la dashboard occupi tutta la larghezza dello schermo, puoi aggiungere il prop full-width al componente:

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

Per impostazione predefinita, il componente <x-pulse> crea una griglia a 12 colonne, ma puoi personalizzarla usando il prop cols:

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

Ogni scheda accetta i prop cols e rows per controllare lo spazio e il posizionamento:

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

La maggior parte delle schede accetta anche il prop expand per mostrare la scheda completa invece di scorrere:

<livewire:pulse.slow-queries expand />

Risoluzione Utenti

Per le card che mostrano informazioni sui tuoi utenti, come la card Utilizzo dell’Applicazione, Pulse registrerà solo l’ID dell’utente. Durante la visualizzazione del dashboard, Pulse risolverà i campi name ed email dal tuo modello predefinito Authenticatable e mostrerà gli avatar utilizzando il servizio web Gravatar.

Puoi personalizzare i campi e l’avatar chiamando il metodo Pulse::user all’interno della classe App\Providers\AppServiceProvider della tua applicazione.

Il metodo user accetta una closure che riceverà il modello Authenticatable da visualizzare e deve restituire un array contenente le informazioni name, extra e avatar per l’utente:

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,
    ]);

    // ...
}

Puoi personalizzare completamente come l’utente autenticato viene catturato e recuperato implementando il contratto Laravel\Pulse\Contracts\ResolvesUsers e associandolo nel service container di Laravel.

Carte

Servers

La card <livewire:pulse.servers /> mostra l’utilizzo delle risorse di sistema per tutti i server che eseguono il comando pulse:check. Consulta la documentazione relativa al servers recorder per ulteriori informazioni sul monitoraggio delle risorse di sistema.

Se sostituisci un server nella tua infrastruttura, potresti voler smettere di visualizzare il server inattivo nella dashboard di Pulse dopo un certo periodo. Puoi farlo utilizzando la proprietà ignore-after, che accetta il numero di secondi dopo i quali i server inattivi verranno rimossi dalla dashboard di Pulse. In alternativa, puoi fornire una stringa di tempo relativa, come 1 hour o 3 days and 1 hour:

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

Utilizzo dell’Applicazione

La scheda <livewire:pulse.usage /> mostra i 10 utenti principali che effettuano richieste alla tua applicazione, inviano jobs e sperimentano richieste lente.

Se desideri visualizzare tutte le metriche di utilizzo sullo schermo contemporaneamente, puoi includere la scheda più volte e specificare l’attributo type:

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

Per imparare come personalizzare il modo in cui Pulse recupera e visualizza le informazioni degli utenti, consulta la nostra documentazione su risoluzione degli utenti.

Se la tua applicazione riceve molte richieste o invia molti jobs, potresti voler abilitare il campionamento. Consulta la documentazione su registratore delle richieste degli utenti, registratore dei jobs degli utenti e registratore dei jobs lenti per maggiori informazioni.

Eccezioni

La card <livewire:pulse.exceptions /> mostra quanto spesso e recentemente si verificano le eccezioni nella tua applicazione. Per impostazione predefinita, le eccezioni sono raggruppate per classe e per luogo in cui si sono verificate. Consulta la documentazione del registratore delle eccezioni per maggiori informazioni.

Code

La <livewire:pulse.queues /> card mostra il throughput delle code nella tua applicazione, incluso il numero di jobs in coda, in elaborazione, processati, rilasciati e falliti. Consulta la documentazione del recorder delle code per maggiori informazioni.

Richieste Lente

La scheda <livewire:pulse.slow-requests /> mostra le richieste in arrivo alla tua applicazione che superano la soglia configurata, che di default è 1.000ms. Consulta la documentazione del registratore delle richieste lente per ulteriori informazioni.

Slow Jobs

La scheda <livewire:pulse.slow-jobs /> mostra i job in coda nella tua applicazione che superano la soglia configurata, che di default è 1.000ms. Consulta la documentazione del registratore dei slow jobs per ulteriori informazioni.

Query Lente

La scheda <livewire:pulse.slow-queries /> mostra le query del database nella tua applicazione che superano la soglia configurata, che per impostazione predefinita è di 1.000 ms.

Per impostazione predefinita, le query lente vengono raggruppate in base alla query SQL (senza i binding) e al luogo in cui si sono verificate, ma puoi scegliere di non catturare la posizione se desideri raggruppare solo per query SQL.

Se riscontri problemi nelle prestazioni di rendering a causa di query SQL estremamente grandi che ricevono l’evidenziazione della sintassi, puoi disabilitare l’evidenziazione aggiungendo la prop without-highlighting:

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

Consulta la documentazione del #slow-queries-recorder per ulteriori informazioni.

Richieste in Uscita Lente

La card <livewire:pulse.slow-outgoing-requests /> mostra le richieste in uscita effettuate con l’HTTP client di Laravel che superano la soglia configurata, che di default è di 1.000ms.

Per impostazione predefinita, le voci vengono raggruppate per URL completo. Tuttavia, potresti voler normalizzare o raggruppare richieste in uscita simili usando espressioni regolari. Consulta la documentazione su slow outgoing requests recorder per maggiori informazioni.

Cache

La scheda <livewire:pulse.cache /> mostra le statistiche di cache hit e miss per la tua applicazione, sia globalmente che per singole chiavi.

Per impostazione predefinita, le voci saranno raggruppate per chiave. Tuttavia, potresti voler normalizzare o raggruppare chiavi simili utilizzando espressioni regolari. Consulta la documentazione del registratore delle interazioni della cache per ulteriori informazioni.

Acquisizione delle Voci

La maggior parte dei registratori Pulse cattura automaticamente le voci basandosi sugli eventi del framework lanciati da Laravel. Tuttavia, il registratore dei server e alcune schede di terze parti devono interrogare regolarmente le informazioni. Per utilizzare queste schede, devi eseguire il demone pulse:check su tutti i tuoi server applicativi individuali:

php artisan pulse:check

Per mantenere il processo pulse:check in esecuzione permanente in background, dovresti usare un monitor di processo come Supervisor per assicurarti che il comando non smetta di funzionare.

Poiché il comando pulse:check è un processo di lunga durata, non rileverà le modifiche al tuo codice senza essere riavviato. Dovresti riavviare il comando in modo sicuro chiamando il comando pulse:restart durante il processo di distribuzione della tua applicazione:

php artisan pulse:restart

Pulse utilizza la cache per memorizzare i segnali di riavvio, quindi dovresti verificare che un driver di cache sia configurato correttamente per la tua applicazione prima di usare questa funzionalità.

Recorders

I recorders sono responsabili per la cattura delle voci dalla tua applicazione per essere registrate nel database Pulse. I recorders vengono registrati e configurati nella sezione recorders del file di configurazione Pulse.

Interazioni con la Cache

Il registratore CacheInteractions cattura informazioni sui cache hit e miss che si verificano nella tua applicazione per mostrarle nella scheda Cache.

Puoi opzionalmente regolare il tasso di campionamento e i pattern delle chiavi da ignorare.

Puoi anche configurare il raggruppamento delle chiavi in modo che le chiavi simili siano raggruppate come un’unica voce. Ad esempio, potresti voler rimuovere ID unici dalle chiavi che memorizzano lo stesso tipo di informazioni. I gruppi vengono configurati usando un’espressione regolare per "trovare e sostituire" parti della chiave. Un esempio è incluso nel file di configurazione:

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

Verrà usato il primo pattern che corrisponde. Se nessun pattern corrisponde, la chiave sarà catturata così com’è.

Eccezioni

Il registratore Exceptions cattura informazioni sulle eccezioni segnalabili che si verificano nella tua applicazione per mostrarle sulla card Exceptions.

Puoi opzionalmente regolare il tasso di campionamento e i pattern delle eccezioni ignorate. Puoi anche configurare se catturare la posizione da cui è originata l’eccezione. La posizione catturata sarà mostrata sulla dashboard di Pulse, il che può aiutare a tracciare l’origine dell’eccezione; tuttavia, se la stessa eccezione si verifica in più posizioni, apparirà più volte per ogni posizione unica.

Queues

Il registratore Queues raccoglie informazioni sulle code della tua applicazione per mostrarle nella sezione Queues.

Puoi opzionalmente regolare il sample rate e i modelli dei job ignorati.

Slow Jobs

Il recorder SlowJobs rileva informazioni sulle job lente che si verificano nella tua applicazione per mostrarle nella scheda Slow Jobs.

Puoi opzionalmente regolare la soglia per le job lente, il tasso di campionamento e i pattern di job ignorati.

Potresti avere alcune job che prevedi richiedano più tempo di altre. In questi casi, puoi configurare soglie per ogni job:

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

Se nessun pattern di espressione regolare corrisponde al nome della classe della job, verrà usato il valore 'default'.

Richieste in uscita lente

Il registratore SlowOutgoingRequests cattura informazioni sulle richieste HTTP in uscita effettuate utilizzando il client HTTP di Laravel che superano la soglia configurata per essere visualizzate sulla scheda delle richieste in uscita lente.

Puoi opzionalmente regolare la soglia per le richieste in uscita lente, il tasso di campionamento e i pattern delle URL da ignorare.

Potresti avere alcune richieste in uscita che prevedi richiedano più tempo rispetto ad altre. In questi casi, puoi configurare soglie per singola richiesta:

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

Se nessuno dei pattern delle espressioni regolari corrisponde alla URL della richiesta, verrà utilizzato il valore 'default'.

Puoi anche configurare il raggruppamento delle URL in modo che URL simili siano raggruppate come un’unica voce. Ad esempio, potresti voler rimuovere ID unici dai percorsi delle URL o raggruppare solo per dominio. I gruppi sono configurati utilizzando una espressione regolare per "trovare e sostituire" parti della URL. Alcuni esempi sono inclusi nel file di configurazione:

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

La prima espressione che corrisponde sarà utilizzata. Se nessun pattern corrisponde, la URL verrà catturata così com’è.

Slow Queries

Il registratore SlowQueries cattura tutte le query del database nella tua applicazione che superano la soglia configurata per essere visualizzate nella scheda Slow Queries.

Opzionalmente, puoi modificare la soglia delle query lente, il tasso di campionamento e i pattern di query ignorati. Puoi anche configurare se catturare la posizione della query. La posizione catturata verrà mostrata nella dashboard di Pulse, il che può aiutare a individuare l’origine della query; tuttavia, se la stessa query viene eseguita in più posizioni, apparirà più volte per ogni posizione unica.

Potresti avere alcune query che ti aspetti richiedano più tempo di altre. In questi casi, puoi configurare soglie per singola query:

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

Se nessun pattern di espressioni regolari corrisponde all’SQL della query, verrà usato il valore 'default'.

Richieste lente

Il recorder Requests cattura informazioni sulle richieste fatte alla tua applicazione per mostrarle nelle schede Richieste lente e Uso dell’applicazione.

Puoi opzionalmente regolare la soglia delle rotte lente, il tasso di campionamento e i percorsi ignorati.

Potresti avere alcune richieste che ti aspetti richiedano più tempo di altre. In questi casi, puoi configurare soglie per richiesta:

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

Se nessun pattern con espressione regolare corrisponde all’URL della richiesta, verrà usato il valore 'default'.

Servers

Il registratore Servers cattura l’utilizzo di CPU, memoria e storage dei server che alimentano la tua applicazione per mostrarli sulla scheda Servers. Questo registratore richiede che il comando pulse:check sia in esecuzione su ciascuno dei server che desideri monitorare.

Ogni server che invia report deve avere un nome unico. Per impostazione predefinita, Pulse userà il valore restituito dalla funzione gethostname di PHP. Se desideri personalizzarlo, puoi impostare la variabile d’ambiente PULSE_SERVER_NAME:

PULSE_SERVER_NAME=load-balancer

Il file di configurazione di Pulse ti permette anche di personalizzare le directory che vengono monitorate.

User Jobs

Il registratore UserJobs raccoglie informazioni sugli utenti che inviano job nella tua applicazione, mostrandole nella scheda Application Usage.

Puoi opzionalmente regolare il tasso di campionamento e i pattern dei job da ignorare.

Richieste Utente

Il recorder UserRequests cattura informazioni sugli utenti che effettuano richieste alla tua applicazione per mostrarle sulla card Utilizzo Applicazione.

Puoi opzionalmente regolare il tasso di campionamento e i pattern URL ignorati.

Filtraggio

Come abbiamo visto, molti recorders offrono la possibilità di, tramite configurazione, "ignorare" le voci in entrata basate sul loro valore, come l’URL di una richiesta. Tuttavia, a volte può essere utile filtrare i record basandosi su altri fattori, come l’utente attualmente autenticato. Per escludere questi record, puoi passare una closure al metodo filter di Pulse. Tipicamente, il metodo filter dovrebbe essere invocato all’interno del metodo boot del AppServiceProvider della tua applicazione:

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

/**
 * Avvia tutti i servizi dell'applicazione.
 */
public function boot(): void
{
    Pulse::filter(function (Entry|Value $entry) {
        return Auth::user()->isNotAdmin();
    });

    // ...
}

Performance

Pulse è stato progettato per integrarsi in un’applicazione esistente senza necessitare di infrastrutture aggiuntive. Tuttavia, per applicazioni ad alto traffico, esistono diversi metodi per eliminare qualsiasi impatto che Pulse potrebbe avere sulle prestazioni della tua applicazione.

Usare un Database Diverso

Per applicazioni con alto traffico, potresti preferire usare una connessione database dedicata per Pulse, evitando così di influire sul database della tua applicazione.

Puoi personalizzare la connessione database usata da Pulse impostando la variabile d’ambiente PULSE_DB_CONNECTION.

PULSE_DB_CONNECTION=pulse

Ingest di Redis

L’Ingest di Redis richiede Redis 6.2 o superiore e phpredis o predis come driver client Redis configurato nell’applicazione.

Per impostazione predefinita, Pulse memorizzerà le voci direttamente nella connessione al database configurata dopo aver inviato la risposta HTTP al client o aver elaborato un lavoro; tuttavia, puoi utilizzare il driver ingest di Redis di Pulse per inviare le voci a uno stream Redis. Questo può essere abilitato configurando la variabile d’ambiente PULSE_INGEST_DRIVER:

PULSE_INGEST_DRIVER=redis

Per impostazione predefinita, Pulse utilizzerà la tua connessione Redis predefinita, ma puoi personalizzarla tramite la variabile d’ambiente PULSE_REDIS_CONNECTION:

PULSE_REDIS_CONNECTION=pulse

Quando usi l’ingest di Redis, dovrai eseguire il comando pulse:work per monitorare lo stream e spostare le voci da Redis nelle tabelle del database di Pulse.

php artisan pulse:work

Per mantenere in esecuzione permanentemente il processo pulse:work in background, dovresti utilizzare un monitor di processi come Supervisor per assicurarti che il worker di Pulse non si fermi.

Poiché il comando pulse:work è un processo a lunga durata, non rileverà le modifiche al tuo codice senza essere riavviato. Dovresti riavviare il comando in modo sicuro eseguendo il comando pulse:restart durante il processo di distribuzione della tua applicazione:

php artisan pulse:restart

Pulse utilizza la cache per memorizzare i segnali di riavvio, quindi dovresti verificare che un driver di cache sia configurato correttamente per la tua applicazione prima di utilizzare questa funzionalità.

Campionamento

Per impostazione predefinita, Pulse cattura ogni evento rilevante che si verifica nella tua applicazione. Per applicazioni ad alto traffico, questo può richiedere di aggregare milioni di righe di database nella dashboard, soprattutto per periodi di tempo più lunghi.

Puoi invece scegliere di abilitare il "campionamento" su alcuni registratori di dati Pulse. Ad esempio, impostando il tasso di campionamento a 0.1 sul registratore User Requests, registrerai solo circa il 10% delle richieste alla tua applicazione. Nella dashboard, i valori saranno scalati e preceduti da un ~ per indicare che sono approssimazioni.

In generale, più voci hai per una metrica particolare, più puoi impostare in sicurezza un tasso di campionamento basso senza sacrificare troppa accuratezza.

Trimming

Pulse eliminerà automaticamente le voci memorizzate una volta che saranno al di fuori della finestra del dashboard. L’eliminazione avviene durante l’acquisizione dei dati utilizzando un sistema a lotteria che può essere personalizzato nel file di configurazione di Pulse.

Gestione delle Eccezioni di Pulse

Se si verifica un’eccezione durante la raccolta dei dati di Pulse, ad esempio se non è possibile connettersi al database di archiviazione, Pulse fallirà silenziosamente per evitare di influenzare la tua applicazione.

Se desideri personalizzare la gestione di queste eccezioni, puoi fornire una closure al metodo 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(),
    ]);
});

Schede Personalizzate

Pulse ti permette di creare schede personalizzate per mostrare dati rilevanti per le specifiche esigenze della tua applicazione. Pulse utilizza Livewire, quindi potresti voler consultare la sua documentazione prima di creare la tua prima scheda personalizzata.

Componenti Card

Creare una card personalizzata in Laravel Pulse inizia estendendo il componente base Card di Livewire e definendo una vista corrispondente:

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');
    }
}

Quando usi la funzionalità di lazy loading di Livewire, il componente Card fornirà automaticamente un segnaposto che rispetta gli attributi cols e rows passati al tuo componente.

Quando scrivi la relativa vista della tua card Pulse, puoi utilizzare i componenti Blade di Pulse per un aspetto coerente:

<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>

Le variabili $cols, $rows, $class e $expand devono essere passate ai rispettivi componenti Blade affinché il layout della card possa essere personalizzato dalla vista dashboard. Potresti anche voler includere l’attributo wire:poll.5s="" nella tua vista per far sì che la card si aggiorni automaticamente.

Una volta definito il tuo componente Livewire e il template, la card può essere inclusa nella tua vista dashboard:

<x-pulse>
    ...

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

Se la tua card è inclusa in un pacchetto, dovrai registrare il componente con Livewire utilizzando il metodo Livewire::component.

<a name="stili"></a>
### Stili

Se la tua card richiede stili aggiuntivi oltre alle classi e ai componenti inclusi in Pulse, ci sono diverse opzioni per includere CSS personalizzato per le tue card.

<a name="integrazione-di-laravel-con-vite"></a>
#### Integrazione di Laravel con Vite

Se la tua card personalizzata fa parte del codice della tua applicazione e stai usando l'[integrazione di Vite di Laravel](https://laravel-italia.it/documentazione-laravel-11-x-vite), puoi aggiornare il file `vite.config.js` per includere un punto di entrata CSS dedicato alla tua card:

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

Puoi poi usare la direttiva Blade @vite nella tua vista dashboard, specificando il punto di entrata CSS per la tua card:

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

    ...
</x-pulse>

File CSS

Per altri casi d’uso, incluse le card Pulse contenute in un pacchetto, puoi istruire Pulse a caricare fogli di stile aggiuntivi definendo un metodo css nel tuo componente Livewire che restituisce il percorso del file CSS:

class TopSellers extends Card
{
    // ...

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

Quando questa card è inclusa nella dashboard, Pulse includerà automaticamente il contenuto di questo file all’interno di un tag <style> quindi non è necessario pubblicarlo nella directory public.

Tailwind CSS

Quando usi Tailwind CSS, dovresti creare un file di configurazione dedicato a Tailwind per evitare di caricare CSS non necessari o conflitti con le classi Tailwind di Pulse:

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

Puoi quindi specificare il file di configurazione nel tuo punto di ingresso CSS:

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

Dovrai inoltre includere un attributo id o class nella vista della tua card che corrisponda al selettore passato alla strategia del selettore important di Tailwind:

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

Acquisizione e Aggregazione dei Dati

Le schede personalizzate possono recuperare e visualizzare dati da qualsiasi fonte; tuttavia, potresti voler sfruttare il potente ed efficiente sistema di registrazione e aggregazione dei dati di Pulse.

Catturare le Voci

Pulse ti permette di registrare "voci" usando il metodo Pulse::record:

use Laravel\Pulse\Facades\Pulse;

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

Il primo argomento fornito al metodo record è il type della voce che stai registrando, mentre il secondo argomento è il key che determina come i dati aggregati devono essere raggruppati. Per la maggior parte dei metodi di aggregazione, dovrai anche specificare un value da aggregare. Nell’esempio sopra, il valore aggregato è $sale->amount. Puoi quindi invocare uno o più metodi di aggregazione (come sum) in modo che Pulse possa catturare valori pre-aggregati in "buckets" per un recupero efficiente in seguito.

I metodi di aggregazione disponibili sono:

• avg
• count
• max
• min
• sum

Quando crei un pacchetto di card che cattura l’ID utente attualmente autenticato, dovresti usare il metodo Pulse::resolveAuthenticatedUserId(), che rispetta eventuali personalizzazioni del resolver dell’utente effettuate nell’applicazione.

Recuperare Dati Aggregati

Quando estendi il componente Livewire Card di Pulse, puoi usare il metodo aggregate per ottenere dati aggregati per il periodo visualizzato nel dashboard:

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

Il metodo aggregate restituisce una collezione di oggetti PHP stdClass. Ogni oggetto conterrà la proprietà key catturata in precedenza, insieme alle chiavi per ciascuno degli aggregati richiesti:

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

Pulse recupererà principalmente i dati dai bucket pre-aggregati; quindi, gli aggregati specificati devono essere stati catturati in anticipo usando il metodo Pulse::record. Il bucket più vecchio di solito cade parzialmente al di fuori del periodo, quindi Pulse aggrega le voci più vecchie per colmare la lacuna e fornire un valore accurato per l’intero periodo, senza dover aggregare l’intero periodo ad ogni richiesta di polling.

Puoi anche ottenere un valore totale per un determinato tipo utilizzando il metodo aggregateTotal. Ad esempio, il metodo seguente recupererebbe il totale di tutte le vendite degli utenti invece di raggrupparle per utente.

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

Visualizzazione degli Utenti

Quando lavori con aggregati che registrano un ID utente come chiave, puoi risolvere le chiavi in record utente usando il metodo 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,
    ])
]);

Il metodo find restituisce un oggetto con le chiavi name, extra e avatar, che puoi passare direttamente al componente Blade <x-pulse::user-card>:

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

Custom Recorders

Gli autori dei pacchetti potrebbero voler fornire classi recorder per consentire agli utenti di configurare la cattura dei dati.

I recorders vengono registrati nella sezione recorders del file di configurazione config/pulse.php dell’applicazione:

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

        // ...
    ],
]

I recorders possono ascoltare gli eventi specificando una proprietà $listen. Pulse registrerà automaticamente gli ascoltatori e chiamerà il metodo record dei recorder:

<?php

namespace Acme\Recorders;

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

class Deployments
{
    /**
     * Gli eventi da ascoltare.
     *
     * @var array<int, class-string>
     */
    public array $listen = [
        Deployment::class,
    ];

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

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