Kurs Laravel 13 #4: panel administracyjny z Filamentem

Laravel nie dostarcza back-office’u. Trzeba go wybrać, a ten wybór wiąże projekt na lata. Ten rozdział wyjaśnia, dlaczego seria zmieniła pakiet, a potem instaluje Filament.

Dlaczego ten rozdział się zmienił

Poprzednie wersje tego kursu korzystały z pakietu Voyager. Tego nie da się już utrzymać.

tcg/voyager jest oznaczony na Packagist jako porzucony. Jego ostatnia wersja, 1.8.0, pochodzi z września 2024 r. i deklaruje zgodność kończącą się na Laravel 11. W projekcie Laravel 13 Composer po prostu odmawia instalacji: najpierw zatrzymuje się na ostrzeżeniach bezpieczeństwa obejmujących wszystkie jego wersje, a ograniczenie do Laravel 11 i tak uniemożliwiłoby rozwiązanie zależności.

To użyteczna lekcja z całej historii: kurs oparty na pakiecie utrzymywanym przez jeden zespół staje się nieprawdziwy w dniu, w którym ten zespół odpuszcza. Wybierając zamiennik, trzeba więc ważyć kondycję projektu tak samo jak jego funkcje.

Co zostało sprawdzone

Cztery tropy, zmierzone 2 września 2026 roku na publicznych danych Packagista:

ilsondev/voyager to fork, który działa: na potrzeby tej rewizji został zainstalowany na świeżym Laravelu 13.30.1, a pulpit, narzędzie BREAD, biblioteka mediów, kreator menu i ustawienia odpowiadają poprawnie. Ma jednak 12 pobrań i jedną gwiazdkę, a wszystkie jego wersje ukazały się w ciągu trzech dni lipca 2026 roku. Ciągnie też intervention/image w wersji 2, której gałąź nie jest już gałęzią bieżącą. Polecanie tego forka początkującemu byłoby powtórzeniem dokładnie tego błędu, który zepsuł ten kurs.

Jeśli jednak utrzymujesz istniejącą aplikację na Voyagerze i zależy ci przede wszystkim na przejściu na Laravela 13 bez przepisywania wszystkiego, ten fork jest uczciwym pomostem. Traktuj go jako etap, nie jako cel.

Wybór: Filament

Filament wygrywa z trzech powodów.

• Nie zniknie z dnia na dzień. 3,3 miliona pobrań miesięcznie, sto razy więcej niż wszystkie alternatywy razem wzięte, i nowe wersje co tydzień.
• Back-office to kod. Voyager trzymał konfigurację ekranów w bazie danych, wyklikaną w interfejsie. W Filamencie każdy ekran to klasa PHP wersjonowana razem z resztą projektu. Czyta się ją, porównuje i wdraża jak każdy inny plik.
• To umiejętność, która się przydaje. Filament jest dziś domyślnym back-office’em ekosystemu Laravela. To, czego się tu nauczysz, spotkasz w prawdziwym projekcie.

Warto znać dwie płatne alternatywy, choć w tym kursie nie są potrzebne: Nova, oficjalne rozwiązanie zespołu Laravela, oraz Backpack.

Instalacja Filamenta

Rozszerzenie intl musi być obecne

Filament wymaga rozszerzenia PHP intl. Sprawdź je przed instalacją:

php -m | grep intl

Jeśli komenda nic nie zwróci, instalacja padnie na tym komunikacie, który nie wymienia Filamenta i potrafi wprawić w konsternację:

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

Pierwszy rozdział właśnie z tego powodu radził je sprawdzić. Na Debianie i Ubuntu: sudo apt install php8.4-intl. Na macOS z Homebrew rozszerzenie już tam jest. Na Windowsie z WampServerem odznacz i zaznacz ponownie php_intl w menu rozszerzeń PHP. Potem zrestartuj serwer.

Pakiet i panel

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

Druga komenda tworzy app/Providers/Filament/AdminPanelProvider.php, publikuje pliki CSS i JavaScript panelu w katalogu public i czyści cache.

INFO  Successfully published assets!
INFO  Successfully upgraded!

Utworzenie konta

php artisan make:filament-user

Komenda pyta o nazwę, adres e-mail i hasło, a następnie potwierdza:

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

Wejdź na http://127.0.0.1:8000/admin i zaloguj się. Pulpit jest pusty: to normalne, nic mu jeszcze nie powierzono. Rozdział 6 doda tam artykuły, kategorie i tagi.

Kontrola tego, kto wchodzi

W środowisku lokalnym Filament wpuszcza każdego zalogowanego użytkownika. Wszędzie indziej odmawia wszystkim błędem 403, dopóki model User nie powie, kto ma prawo wejść. To zabezpieczenie domyślne, ale potrafi zaskoczyć: panel działa na twojej maszynie i zwraca 403 zaraz po wypuszczeniu na serwer.

Regułę deklaruje się, implementując interfejs FilamentUser. Zachowaj wszystko, co dostarczony model już zawiera, atrybuty #[Fillable] i #[Hidden] oraz metodę casts(): dochodzą tylko interfejs i metoda 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',
        ];
    }
}

Podmień domenę na własną. Ta reguła jest celowo uproszczona: wystarczy w projekcie do nauki, nie na publicznej stronie. Prawdziwy projekt opiera się na kolumnie is_admin albo na systemie ról.

Zachowanie sprawdzają dwa testy. Drugi liczy się tak samo jak pierwszy: w środowisku testowym Filament odrzuca wszystkich, dopóki reguła nie istnieje, więc test sprawdzający tylko odmowę przeszedłby nawet bez niej.

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

Migracja z wersji tego kursu opartej na Voyagerze

Jeśli przerabiałeś ten kurs w wersji z Voyagerem, oto co się zmienia.

• Tabele Voyagera znikają. Instalacja tworzyła ich dziesięć: data_types, data_rows, menus, menu_items, settings, roles, permissions, permission_role, user_roles i translations. Żadna nie jest już potrzebna. Twoje tabele biznesowe, posts, categories, tags, post_tag, users, zostają bez zmian: Filament podpina się do nich bez migracji danych.
• Konfiguracja BREAD przepada, i tak ma być. To, co wyklikałeś w Voyagerze, zapisujesz raz w PHP, w plikach z rozdziału 6. To pół godziny pracy, po której konfiguracja jest wersjonowana.
• Funkcja setting() już nie istnieje. Voyager dostarczał ją do odczytu tytułu i opisu witryny. Zamień setting('site.title') na config('app.name') albo na własne ustawienia.
• Obejście dla sluga posts staje się zbędne. Voyager wnosił własny model Post, przez co trzeba było zmienić slug tabeli na blog-posts i poprawić jeden szablon pakietu. Filament nie narzuca żadnego modelu, konflikt znika.
• Adres back-office’u się nie zmienia. Filament też instaluje się pod /admin.

Żeby usunąć Voyagera z istniejącego projektu: composer remove tcg/voyager, a potem skasuj jego tabele oraz katalog resources/views/vendor/voyager, jeśli istnieje. Wcześniej zrób kopię zapasową bazy.

Czego ten rozdział nie objął

Szczegółowe role i uprawnienia, personalizacja motywu panelu oraz widżety pulpitu wykraczają poza ramy tej serii. Opisuje je dokumentacja Filamenta.

Następny rozdział buduje stronę główną publicznej witryny.