Telescope

• Introduzione
• Installazione
• Aggiornamento di Telescope
• Filtraggio
• Tagging
• Watchers Disponibili
• Visualizzazione degli Avatar degli Utenti

Introduzione

Laravel Telescope è un ottimo compagno per il tuo ambiente di sviluppo Laravel locale. Telescope offre una visione dettagliata delle richieste che arrivano nella tua applicazione, eccezioni, voci di log, query al database, job in coda, mail, notifiche, operazioni della cache, task programmati, dump di variabili e altro ancora.

Installazione

Puoi usare il gestore di pacchetti Composer per installare Telescope nel tuo progetto Laravel:

composer require laravel/telescope

Dopo aver installato Telescope, pubblica le sue risorse e migrazioni usando il comando Artisan telescope:install. Inoltre, devi eseguire il comando migrate per creare le tabelle necessarie a memorizzare i dati di Telescope:

php artisan telescope:install

php artisan migrate

Infine, puoi accedere al dashboard di Telescope tramite la rotta /telescope.

Installazione Solo Locale

Se prevedi di utilizzare Telescope solo per assistere lo sviluppo locale, puoi installare Telescope usando l’opzione --dev:

composer require laravel/telescope --dev

php artisan telescope:install

php artisan migrate

Dopo aver eseguito telescope:install, dovresti rimuovere la registrazione del service provider TelescopeServiceProvider dal file di configurazione bootstrap/providers.php della tua applicazione. Invece, registra manualmente i service provider di Telescope nel metodo register della classe App\Providers\AppServiceProvider. Verificheremo che l’ambiente attuale sia local prima di registrare i provider:

/**
 * Registra i servizi dell'applicazione.
 */
public function register(): void
{
    if ($this->app->environment('local') && class_exists(\Laravel\Telescope\TelescopeServiceProvider::class)) {
        $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
        $this->app->register(TelescopeServiceProvider::class);
    }
}

Infine, dovresti anche impedire che il pacchetto Telescope venga scoperto automaticamente aggiungendo quanto segue al tuo file composer.json:

"extra": {
    "laravel": {
        "dont-discover": [
            "laravel/telescope"
        ]
    }
},

Configurazione

Dopo aver pubblicato le risorse di Telescope, il file di configurazione principale si troverà in config/telescope.php. Questo file di configurazione ti permette di impostare le tue opzioni di watcher. Ogni opzione di configurazione include una descrizione del suo scopo, quindi assicurati di esplorare attentamente questo file.

Se desideri, puoi disabilitare completamente la raccolta dei dati di Telescope utilizzando l’opzione di configurazione enabled:

'enabled' => env('TELESCOPE_ENABLED', true),

Pulizia dei Dati

Senza la pulizia, la tabella telescope_entries può accumulare record molto rapidamente. Per evitare questo, dovresti programmare il comando Artisan telescope:prune per eseguirsi ogni giorno:

use Illuminate\Support\Facades\Schedule;

Schedule::command('telescope:prune')->daily();

Per impostazione predefinita, tutte le entrate più vecchie di 24 ore verranno rimosse. Puoi usare l’opzione hours quando esegui il comando per determinare per quanto tempo conservare i dati di Telescope. Ad esempio, il comando seguente eliminerà tutti i record creati più di 48 ore fa:

use Illuminate\Support\Facades\Schedule;

Schedule::command('telescope:prune --hours=48')->daily();

Autorizzazione Dashboard

La dashboard di Telescope può essere accessibile tramite la rotta /telescope. Di default, potrai accedere a questa dashboard solo nell’ambiente local. Nel file app/Providers/TelescopeServiceProvider.php, c’è una definizione di authorization gate. Questo authorization gate controlla l’accesso a Telescope negli ambienti non locali. Puoi modificare questo gate secondo le tue necessità per limitare l’accesso alla tua installazione di Telescope:

use App\Models\User;

/**
 * Registra il gate di Telescope.
 *
 * Questo gate determina chi può accedere a Telescope negli ambienti non locali.
 */
protected function gate(): void
{
    Gate::define('viewTelescope', function (User $user) {
        return in_array($user->email, [
            'taylor@laravel.com',
        ]);
    });
}

Assicurati di cambiare la variabile d’ambiente APP_ENV in production nel tuo ambiente di produzione. Altrimenti, la tua installazione di Telescope sarà disponibile pubblicamente.

Aggiornamento di Telescope

Quando aggiorni a una nuova versione principale di Telescope, è importante che tu esamini attentamente la guida all’aggiornamento.

Inoltre, quando aggiorni a una nuova versione di Telescope, dovresti ripubblicare gli asset di Telescope:

php artisan telescope:publish

Per mantenere gli asset aggiornati ed evitare problemi nei futuri aggiornamenti, puoi aggiungere il comando vendor:publish --tag=laravel-assets agli script post-update-cmd nel file composer.json della tua applicazione:

{
    "scripts": {
        "post-update-cmd": [
            "@php artisan vendor:publish --tag=laravel-assets --ansi --force"
        ]
    }
}

Filtraggio

Voci

Puoi filtrare i dati registrati da Telescope tramite la chiusura filter definita nella tua classe App\Providers\TelescopeServiceProvider. Per impostazione predefinita, questa chiusura registra tutti i dati nell’ambiente local ed eccezioni, job falliti, task programmati e dati con tag monitorati in tutti gli altri ambienti:

use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;

/**
 * Registra i servizi dell'applicazione.
 */
public function register(): void
{
    $this->hideSensitiveRequestDetails();

    Telescope::filter(function (IncomingEntry $entry) {
        if ($this->app->environment('local')) {
            return true;
        }

        return $entry->isReportableException() ||
            $entry->isFailedJob() ||
            $entry->isScheduledTask() ||
            $entry->isSlowQuery() ||
            $entry->hasMonitoredTag();
    });
}

Batches

Mentre la closure filter filtra i dati per singoli elementi, puoi usare il metodo filterBatch per registrare una closure che filtra tutti i dati per una determinata richiesta o comando da console. Se la closure restituisce true, tutti gli elementi vengono registrati da Telescope:

use Illuminate\Support\Collection;
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;

/**
 * Registra i servizi dell'applicazione.
 */
public function register(): void
{
    $this->hideSensitiveRequestDetails();

    Telescope::filterBatch(function (Collection $entries) {
        if ($this->app->environment('local')) {
            return true;
        }

        return $entries->contains(function (IncomingEntry $entry) {
            return $entry->isReportableException() ||
                $entry->isFailedJob() ||
                $entry->isScheduledTask() ||
                $entry->isSlowQuery() ||
                $entry->hasMonitoredTag();
            });
    });
}

Tagging

Telescope ti permette di cercare le voci tramite un "tag". Spesso, i tag sono i nomi delle classi dei modelli Eloquent o gli ID degli utenti autenticati che Telescope aggiunge automaticamente alle voci. A volte, potresti voler aggiungere dei tag personalizzati alle voci. Per fare ciò, puoi usare il metodo Telescope::tag. Il metodo tag accetta una closure che deve restituire un array di tag. I tag restituiti dalla closure saranno uniti a quelli che Telescope aggiunge automaticamente alla voce. Di solito, dovresti chiamare il metodo tag all’interno del metodo register della tua classe App\Providers\TelescopeServiceProvider:

    use Laravel\Telescope\IncomingEntry;
    use Laravel\Telescope\Telescope;

    /**
     * Register any application services.
     */
    public function register(): void
    {
        $this->hideSensitiveRequestDetails();

        Telescope::tag(function (IncomingEntry $entry) {
            return $entry->type === 'request'
                        ? ['status:'.$entry->content['response_status']]
                        : [];
        });
     }

Watchers Disponibili

I "watchers" di Telescope raccolgono dati dell’applicazione quando viene eseguita una richiesta o un comando console. Puoi personalizzare l’elenco dei watchers che desideri abilitare nel file di configurazione config/telescope.php:

'watchers' => [
    Watchers\CacheWatcher::class => true,
    Watchers\CommandWatcher::class => true,
    ...
],

Alcuni watchers permettono anche di fornire opzioni di personalizzazione aggiuntive:

'watchers' => [
    Watchers\QueryWatcher::class => [
        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
        'slow' => 100,
    ],
    ...
],

Batch Watcher

Il Batch Watcher registra informazioni sui batches in coda, inclusi i dettagli dei job e delle connessioni.

Cache Watcher

Il cache watcher registra i dati quando una cache key viene hit, miss, aggiornata e dimenticata.

Command Watcher

Il command watcher registra gli argomenti, le opzioni, il codice di uscita e l’output ogni volta che viene eseguito un comando Artisan. Se desideri escludere alcuni comandi dalla registrazione del watcher, puoi specificarli nell’opzione ignore all’interno del file config/telescope.php:

'watchers' => [
    Watchers\CommandWatcher::class => [
        'enabled' => env('TELESCOPE_COMMAND_WATCHER', true),
        'ignore' => ['key:generate'],
    ],
    ...
],

Dump Watcher

Il Dump Watcher registra e mostra i dump delle tue variabili in Telescope. Quando usi Laravel, puoi fare il dump delle variabili usando la funzione globale dump. La scheda del Dump Watcher deve essere aperta in un browser affinché il dump venga registrato, altrimenti i dump verranno ignorati dal watcher.

Event Watcher

L’Event Watcher registra payload, listeners e dati di broadcast per qualsiasi eventi inviati dalla tua applicazione. Gli eventi interni del framework Laravel vengono ignorati dall’Event Watcher.

Exception Watcher

L’exception watcher registra i dati e la stack trace per tutte le exception segnalabili lanciate dalla tua applicazione.

Gate Watcher

Il gate watcher registra i dati e i risultati dei controlli gate e policy effettuati dalla tua applicazione. Se desideri escludere alcune abilità dalla registrazione del watcher, puoi specificarle nell’opzione ignore_abilities nel file config/telescope.php:

    'watchers' => [
        Watchers\GateWatcher::class => [
            'enabled' => env('TELESCOPE_GATE_WATCHER', true),
            'ignore_abilities' => ['viewNova'],
        ],
        ...
    ],

HTTP Client Watcher

L’HTTP Client Watcher registra le richieste in uscita HTTP client requests effettuate dalla tua applicazione.

Job Watcher

Il job watcher registra i dati e lo stato di qualsiasi job inviato dalla tua applicazione.

Log Watcher

Il log watcher registra i dati di log per tutti i log scritti dalla tua applicazione.

Per impostazione predefinita, Telescope registra solo i log a livello error e superiori. Tuttavia, puoi modificare l’opzione level nel file di configurazione config/telescope.php della tua applicazione per cambiare questo comportamento:

'watchers' => [
    Watchers\LogWatcher::class => [
        'enabled' => env('TELESCOPE_LOG_WATCHER', true),
        'level' => 'debug',
    ],

    // ...
],

Mail Watcher

Il mail watcher ti permette di visualizzare un’anteprima nel browser delle emails inviate dalla tua applicazione insieme ai dati associati. Puoi anche scaricare l’email come file .eml.

Model Watcher

Il model watcher registra le modifiche ai modelli ogni volta che viene emesso un model event di Eloquent. Puoi specificare quali eventi dei modelli devono essere registrati tramite l’opzione events del watcher:

    'watchers' => [
        Watchers\ModelWatcher::class => [
            'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
            'events' => ['eloquent.created*', 'eloquent.updated*'],
        ],
        ...
    ],

Se desideri registrare il numero di modelli hydrated durante una determinata richiesta, abilita l’opzione hydrations:

    'watchers' => [
        Watchers\ModelWatcher::class => [
            'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
            'events' => ['eloquent.created*', 'eloquent.updated*'],
            'hydrations' => true,
        ],
        ...
    ],

Notification Watcher

Il notification watcher registra tutte le notifications inviate dalla tua applicazione. Se la notifica attiva un’email e hai abilitato il mail watcher, l’email sarà anche disponibile per l’anteprima nella schermata del mail watcher.

Query Watcher

Il Query Watcher registra il raw SQL, i bindings e il tempo di esecuzione di tutte le query eseguite dalla tua applicazione. Il Watcher marca anche le query che impiegano più di 100 millisecondi come slow. Puoi personalizzare la soglia per le query lente usando l’opzione slow del Watcher:

'watchers' => [
    Watchers\QueryWatcher::class => [
        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
        'slow' => 50,
    ],
    ...
],

Redis Watcher

Il Redis Watcher registra tutti i comandi Redis eseguiti dalla tua applicazione. Se usi Redis per la cache, anche i comandi della cache saranno registrati dal Redis Watcher.

Request Watcher

Il Request Watcher registra la richiesta, gli headers, la sessione e i dati della risposta associati a qualsiasi richiesta gestita dall’applicazione. Puoi limitare i dati della risposta registrati tramite l’opzione size_limit (in kilobyte):

'watchers' => [
    Watchers\RequestWatcher::class => [
        'enabled' => env('TELESCOPE_REQUEST_WATCHER', true),
        'size_limit' => env('TELESCOPE_RESPONSE_SIZE_LIMIT', 64),
    ],
    ...
],

Schedule Watcher

Il schedule watcher registra il comando e l’output di qualsiasi scheduled tasks eseguiti dalla tua applicazione.

View Watcher

Il view watcher registra il nome della view, il percorso, i dati e i "composers" utilizzati durante il rendering delle view.

Visualizzazione degli Avatar degli Utenti

Il cruscotto di Telescope mostra l’avatar dell’utente che è stato autenticato quando una determinata voce è stata salvata. Per impostazione predefinita, Telescope recupera gli avatar tramite il servizio web Gravatar. Tuttavia, puoi personalizzare l’URL dell’avatar registrando una callback nella classe App\Providers\TelescopeServiceProvider. La callback riceverà l’ID dell’utente e l’indirizzo email e dovrebbe restituire l’URL dell’immagine dell’avatar dell’utente:

use App\Models\User;
use Laravel\Telescope\Telescope;

/**
 * Registra i servizi dell'applicazione.
 */
public function register(): void
{
    // ...

    Telescope::avatar(function (string $id, string $email) {
        return '/avatars/'.User::find($id)->avatar_path;
    });
}