Costruire Laravel Error Share

La scorsa settimana abbiamo rilasciato Laravel Error Share, un pacchetto per condividere le eccezioni Laravel locali con un collega o con il tuo amico debugger su internet. Abbiamo scritto tutto sulla funzionalità del pacchetto sul blog di Flare. In questo post vorrei analizzare alcuni dettagli implementativi e le considerazioni che abbiamo fatto durante la sua costruzione.

Da due settimane, Laravel include una bellissima nuova pagina di errore minimale. In Spatie abbiamo creato e continueremo a mantenere Ignition, la precedente pagina di errore. Dopo il rilascio della nuova, alcune persone sentivano la mancanza di funzionalità offerte da Ignition che non sono più disponibili. Puoi ancora installare Ignition per una vista più dettagliata durante il debug, ma volevamo anche rendere alcune funzionalità principali di Ignition accessibili come “plugin” per la pagina di errore nativa di Laravel.

La funzionalità principale che volevamo portare—che era anche di gran lunga la più richiesta—era il pulsante di condivisione. Il pulsante di condivisione su Ignition è probabilmente una delle cose open source che preferisco tra quelle che abbiamo costruito negli anni. Mi capita così spesso di imbattermi in un problema su uno dei nostri progetti e di voler chiedere a un collega di aiutarmi con il debug. Uno stack trace condiviso e interattivo con il contesto è molto, molto più utile di uno screenshot .png.

Laravel Error Share è stato creato dal mio collega Ruben, quindi la maggior parte del codice che esaminerò in questo post è a lui attribuita. Io ho contribuito al design e ho dato feedback sull’implementazione.

Volevamo inserire il pulsante “Condividi” accanto al selettore del tema dark/light mode in alto a destra nella pagina di errore. Il template per questa intestazione è memorizzato nella vista vendor laravel-exceptions-renderer::navigation.

Per sovrascrivere la vista vendor, abbiamo creato una nostra cartella resources/views nel pacchetto e l’abbiamo registrata sotto un namespace personalizzato nel service provider del pacchetto.

View::prependNamespace('laravel-exceptions-renderer', [__DIR__.'/../resources/views']);

Successivamente, abbiamo creato il nostro file navigations.blade.php, che è una copia della vista di Laravel. Il nostro ha un componente <x-laravel-exceptions-renderer::error-share> aggiunto che viene renderizzato prima del selettore del tema.

<header class="mt-3 px-5 sm:mt-10">
    <div class="py-3 dark:border-gray-900 sm:py-5">
        <div class="flex items-center justify-between">
            <!-- A bunch of other stuff… -->
            
            <div class="flex items-center gap-3 sm:gap-6">
                <x-laravel-exceptions-renderer::error-share :exception="$exception" />
                <x-laravel-exceptions-renderer::theme-switcher />
            </div>
        </div>
    </div>
</header>

Passiamo l’oggetto exception al componente error share in modo che possa analizzarlo e trasformarlo in un formato che la Flare API può digerire per l’URL condiviso pubblicamente.

Lo svantaggio di questo metodo è che dobbiamo mantenere manualmente il pacchetto aggiornato con il file di vista upstream di Laravel. Per evitare di essere colti alla sprovvista dai cambiamenti di Laravel, abbiamo aggiunto un test snapshot usando Pest e il nostro plugin snapshot che viene eseguito sulla vista nella cartella vendor. Non è perfetto, perché intercetteremo gli aggiornamenti solo quando qualcuno esegue i test o fa una PR, ma è meglio che dover verificare manualmente.

<?php
use function Spatie\Snapshots\assertMatchesFileSnapshot;
it('still is the same laravel navigation blade component', function () {
    assertMatchesFileSnapshot(__DIR__.'/../vendor/laravel/framework/src/Illuminate/Foundation/resources/exceptions/renderer/components/navigation.blade.php');
})->skipOnWindows();

In futuro, prenderemmo in considerazione l’idea di fare una PR a Laravel per rendere la pagina di errore estendibile con slot o qualcosa di simile, ma per ora va bene così.

Nella prima versione, abbiamo replicato lo stile del pulsante “Espandi vendor frames” con un’icona di condivisione pesante. Anche se questo faceva risaltare il pulsante, sembrava troppo prominente.

Invece, abbiamo adottato un approccio più discreto, simile al pulsante del selettore del tema accanto. Abbiamo cercato in Heroicons (la libreria di icone usata per le altre icone nella pagina di errore) un’icona adatta e abbiamo rimosso lo sfondo del pulsante per renderlo più discreto. Avevamo considerato di rimuovere l’etichetta in modo che sembrasse proprio come il selettore del tema, ma alla fine l’abbiamo mantenuta perché un’icona da sola non basta a comunicare la funzionalità.

Abbiamo anche replicato il selettore del tema per lo stile del dropdown. Abbiamo deciso di mantenere la tonalità viola di Flare sul pulsante “Crea condivisione” per avere un riferimento discreto al servizio senza esagerare con il branding in un ambiente di sviluppo.

Ed è così che è nato Laravel Error Share! Attualmente stiamo portando altre funzionalità di Ignition sulla pagina di errore nativa di Laravel, così gli sviluppatori possono scegliere tra una selezione di piccoli addon o installare Ignition per un rinnovamento completo.