Tutorial Laravel 13 #4: pannello di amministrazione con Filament

Laravel non fornisce un back-office. Devi sceglierne uno, e questa scelta impegna il progetto per anni. Questo capitolo spiega perché la serie ha cambiato pacchetto, poi installa Filament.

Perché questo capitolo è cambiato

Le versioni precedenti di questo tutorial usavano Voyager. Non è più sostenibile.

tcg/voyager è segnato come abbandonato su Packagist. La sua ultima versione, la 1.8.0, risale a settembre 2024 e dichiara una compatibilità che si ferma a Laravel 11. Su un progetto Laravel 13, Composer si rifiuta semplicemente di installarlo: si blocca prima sugli avvisi di sicurezza che riguardano tutte le sue versioni, e il vincolo a Laravel 11 farebbe comunque fallire la risoluzione.

È la lezione utile dell’episodio: un tutorial che poggia su un pacchetto mantenuto da un solo team diventa falso il giorno in cui quel team si ferma. La scelta del sostituto deve quindi pesare la salute del progetto quanto le sue funzionalità.

Che cosa è stato esaminato

Quattro piste, misurate il 2 settembre 2026 sui dati pubblici di Packagist:

ilsondev/voyager è un fork che funziona: per questa revisione è stato installato su un Laravel 13.30.1 appena creato, e la dashboard, lo strumento BREAD, la media library, il costruttore di menu e le impostazioni rispondono tutti correttamente. Ma totalizza 12 download e una stella, e tutte le sue versioni sono state pubblicate in tre giorni di luglio 2026. Si porta dietro anche intervention/image in versione 2, il cui ramo non è più quello corrente. Consigliare questo fork a un principiante significherebbe rifare esattamente l’errore che ha rotto questo tutorial.

Resta il fatto che, se mantieni un’applicazione Voyager esistente e cerchi prima di tutto di passare a Laravel 13 senza riscrivere tutto, questo fork è un ponte onesto. Trattalo come una tappa, non come una destinazione.

La scelta: Filament

Filament vince per tre ragioni.

• Non sparirà domani. 3,3 milioni di download al mese, cento volte il pubblico di tutte le alternative messe insieme, e nuove versioni ogni settimana.
• Il back-office è codice. Voyager teneva la configurazione delle schermate nel database, cliccata dentro un’interfaccia. In Filament ogni schermata è una classe PHP versionata con il resto del progetto. Si rilegge, si confronta e si distribuisce come qualsiasi altro file.
• È una competenza che serve. Filament è oggi il back-office predefinito dell’ecosistema Laravel. Quello che impari qui lo ritroverai in un progetto vero.

Due alternative a pagamento vale la pena conoscerle, anche se non servono per questo tutorial: Nova, la soluzione ufficiale del team Laravel, e Backpack.

Installare Filament

L’estensione intl deve essere presente

Filament richiede l’estensione PHP intl. Verificala prima di installare:

php -m | grep intl

Se il comando non restituisce niente, l’installazione fallirà su questo messaggio, che non nomina Filament e lascia perplessi:

filament/support[...] require ext-intl * -> it is missing from your system.
Install or enable PHP's intl extension.

Il primo capitolo consigliava già di verificarla proprio per questo. Su Debian o Ubuntu, sudo apt install php8.4-intl. Su macOS con Homebrew l’estensione c’è già. Su Windows con WampServer, deseleziona e riseleziona php_intl nel menu delle estensioni PHP. Poi riavvia il server.

Il pacchetto e il pannello

composer require filament/filament
php artisan filament:install --panels

Il secondo comando crea app/Providers/Filament/AdminPanelProvider.php, pubblica i file CSS e JavaScript del pannello in public e svuota le cache.

INFO  Successfully published assets!
INFO  Successfully upgraded!

Creare un account

php artisan make:filament-user

Il comando chiede un nome, un indirizzo e-mail e una password, poi conferma:

INFO  Success! admin@gekkode.test may now log in at http://localhost:8000/admin/login.

Vai su http://127.0.0.1:8000/admin e accedi. La dashboard è vuota: è normale, non le è ancora stato affidato niente. Il capitolo 6 ci aggiungerà gli articoli, le categorie e i tag.

Controllare chi entra

In ambiente locale Filament lascia entrare qualsiasi utente autenticato. Ovunque altrove li rifiuta tutti con un errore 403, finché il modello User non dice chi ha il diritto di entrare. È una sicurezza predefinita, ma spiazza: il pannello funziona sulla tua macchina e risponde 403 appena vai online.

La regola si dichiara implementando l’interfaccia FilamentUser. Conservate tutto ciò che il modello fornito contiene già, gli attributi #[Fillable] e #[Hidden] come il metodo casts(): si aggiungono soltanto l’interfaccia e il metodo canAccessPanel().

<?php

namespace App\Models;

use Database\Factories\UserFactory;
use Filament\Models\Contracts\FilamentUser;
use Filament\Panel;
use Illuminate\Database\Eloquent\Attributes\Fillable;
use Illuminate\Database\Eloquent\Attributes\Hidden;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;

#[Fillable(['name', 'email', 'password'])]
#[Hidden(['password', 'remember_token'])]
class User extends Authenticatable implements FilamentUser
{
    /** @use HasFactory<UserFactory> */
    use HasFactory, Notifiable;

    public function canAccessPanel(Panel $panel): bool
    {
        return str_ends_with($this->email, '@gekkode.test');
    }

    protected function casts(): array
    {
        return [
            'email_verified_at' => 'datetime',
            'password' => 'hashed',
        ];
    }
}

Sostituisci il dominio con il tuo. Questa regola è volutamente semplicistica: basta per un progetto di apprendimento, non per un sito pubblico. Un progetto vero si appoggia a una colonna is_admin o a un sistema di ruoli.

Il comportamento si verifica con due test. Il secondo conta quanto il primo: nell’ambiente di test, Filament rifiuta tutti finché la regola non esiste, quindi un test che verificasse solo il rifiuto passerebbe anche senza di essa.

<?php

namespace Tests\Feature;

use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class AdminTest extends TestCase
{
    use RefreshDatabase;

    public function test_un_email_hors_domaine_est_refuse(): void
    {
        $user = User::factory()->create(['email' => 'intrus@example.com']);

        $this->actingAs($user)->get('/admin')->assertForbidden();
    }

    public function test_un_email_du_domaine_est_accepte(): void
    {
        $user = User::factory()->create(['email' => 'admin@gekkode.test']);

        $this->actingAs($user)->get('/admin')->assertOk();
    }
}

Migrare dalla versione Voyager di questo tutorial

Se avevi seguito questo tutorial nella sua versione Voyager, ecco che cosa cambia.

• Le tabelle di Voyager spariscono. L’installazione ne creava dieci: data_types, data_rows, menus, menu_items, settings, roles, permissions, permission_role, user_roles e translations. Nessuna serve più. Le tue tabelle di dominio, posts, categories, tags, post_tag, users, restano tali e quali: Filament ci si aggancia sopra senza migrazione di dati.
• La configurazione BREAD è persa, ed è voluto. Quello che avevi cliccato in Voyager si riscrive in PHP, una volta sola, nei file del capitolo 6. È mezz’ora di lavoro, dopo la quale la configurazione è versionata.
• La funzione setting() non esiste più. Voyager la forniva per leggere il titolo e la descrizione del sito. Sostituisci setting('site.title') con config('app.name'), o con le tue impostazioni.
• L’aggiramento sullo slug posts non serve più. Voyager portava il proprio modello Post, il che obbligava a rinominare lo slug della tabella in blog-posts e a correggere un template del pacchetto. Filament non impone alcun modello, il conflitto sparisce.
• L’indirizzo del back-office non cambia. Anche Filament si installa su /admin.

Per togliere Voyager da un progetto esistente: composer remove tcg/voyager, poi elimina le sue tabelle e la cartella resources/views/vendor/voyager se esiste. Fai prima un backup del database.

Che cosa questo capitolo non ha trattato

I ruoli e i permessi granulari, la personalizzazione del tema del pannello e i widget della dashboard escono dal perimetro di questa serie. La documentazione di Filament li copre.

Il capitolo successivo costruisce la home page del sito pubblico.