Filament v5: Yenilikler, Degisiklikler ve Upgrade Rehberi

Filament v5 Ocak 2026'da yayinlandi ve ilk bakista "bu ne upgrade'i, hicbir sey degismemis" diye dusunebilirsiniz. Gercekten de Filament v5'te neredeyse sifir yeni ozellik var. Ama bunun cok gecerli bir sebebi var: Tum upgrade'in tek amaci Livewire v4 destegi. Bu yazida v5'te ne degisti, neden degisti, upgrade sureci nasil ve Livewire v4'un Filament'e ne kazandirdigini anlatacagim.

Neden Yeni Majör Versiyon?

Filament v4, Livewire v3 uzerine kuruluydu. Livewire v4 ciktiginda oyle buyuk breaking change'ler getirdi ki Filament'in buna ayak uydurabilmesi icin majör versiyon atlamasi gerekti. Yani:

• Filament v5 = Filament v4 + Livewire v4 destegi
• Yeni panel ozelligi yok
• Yeni form field'i yok
• Yeni tablo ozelligi yok

Tum is Livewire v4 uyumlulugu saglamak icin internal refactoring.

Bu kotu bir sey mi? Hayir. Livewire v4 oyle ozellikler getiriyor ki bunlar Filament'in DNA'sina isliyor. Birazdan goreceksiniz.

Gereksinimler

Upgrade yapmadan once ortaminizi kontrol edin:

Gereksinim	Minimum Versiyon
PHP	8.2+
Laravel	11.28+
Livewire	4.0+
Tailwind CSS	4.0+
Node.js	18+

Onemli: Livewire v4 ve Tailwind v4 birlikte geliyor. Yani Filament v5'e gecerken uc sey birden degisiyor: Filament, Livewire ve Tailwind. Bu nedenle upgrade'i dikkatli planlayin.

Upgrade Sureci

Filament ekibi otomatik upgrade script'i hazirladi. Cogu proje icin bu yeterli:

# Once backup alin
git stash  # veya yeni branch

# Otomatik upgrade script'i
composer require filament/upgrade:"^5.0" --dev
php artisan filament:upgrade

# Script bitince gereksiz paketi kaldir
composer remove filament/upgrade --dev

Bu script su islemleri yapiyor:

• composer.json'daki Filament paketlerini v5'e guncelliyor
• Livewire v4'e yukseltme yapiyor
• Tailwind v4 icin gerekli degisiklikleri uyguluyor
• Deprecated metodlari yenileriyle degistiriyor
• Custom theme'leri guncelliyor

Manuel Adimlar

Otomatik script her seyi cozmuyor. Bazi seyleri elle kontrol etmeniz gerekiyor.

composer.json

{
    "require": {
        "filament/filament": "^5.0",
        "livewire/livewire": "^4.0"
    }
}

composer update

Tailwind v4 Gecisi

Tailwind v4, konfigurasyonu tamamen degistirdi. tailwind.config.js yerine CSS-first yaklasim:

/* resources/css/filament/admin/theme.css */

/* Tailwind v3 (eski) */
/* @config './tailwind.config.js'; */

/* Tailwind v4 (yeni) */
@import 'tailwindcss';

@source '../../views/**/*.blade.php';
@source '../../../../vendor/filament/**/*.blade.php';

@theme {
    --color-primary-50: #eff6ff;
    --color-primary-100: #dbeafe;
    --color-primary-200: #bfdbfe;
    --color-primary-300: #93c5fd;
    --color-primary-400: #60a5fa;
    --color-primary-500: #3b82f6;
    --color-primary-600: #2563eb;
    --color-primary-700: #1d4ed8;
    --color-primary-800: #1e40af;
    --color-primary-900: #1e3a8a;
    --color-primary-950: #172554;
}

Tailwind v4'te tailwind.config.js artik YOK. Her sey CSS uzerinden.

Livewire v4 Degisiklikleri

Livewire v4 bazi syntax degisiklikleri getirdi. Filament'in internal component'lerinde bunlar zaten guncellenmis durumda ama kendi yazdiginiz custom Livewire component'lerini guncellemeniz gerekiyor:

// Livewire v3 (eski)
class MyComponent extends Component
{
    #[Rule('required|string|max:255')]
    public string $name = '';

    public function save()
    {
        $this->validate();
        // ...
    }
}

// Livewire v4 (yeni)
class MyComponent extends Component
{
    #[Validate('required|string|max:255')]
    public string $name = '';

    public function save()
    {
        $this->validate();
        // ...
    }
}

#[Rule] attribute'u #[Validate] olarak degisti. Bu en yaygin breaking change.

Livewire v4 Ne Getiriyor?

Iste Filament v5'in gercek degeri burada. Livewire v4 ozellikleri Filament'in icinden otomatik olarak kullanilabiliyor.

1. Single-File Components

Livewire v4'un en buyuk yeniligi. PHP ve Blade ayni dosyada:

<?php
// resources/views/livewire/counter.blade.php

use Livewire\Component;
use Livewire\Attributes\Layout;

new #[Layout('components.layouts.app')] class extends Component
{
    public int $count = 0;

    public function increment(): void
    {
        $this->count++;
    }
}
?>

<div>
    <h1>Sayac: {{ $count }}</h1>
    <button wire:click="increment" class="btn">Artir</button>
</div>

Artik her component icin ayri PHP dosyasi + ayri Blade dosyasi olusturmaniza gerek yok. Kucuk component'ler icin bu muazzam bir kolaylik.

Filament baglaminda: Custom page'ler, custom widget'lar ve custom action modal'lari icin single-file component kullanabilirsiniz.

2. Livewire Islands

Bu ozellik performans icin devrim. Sayfanin sadece belirli bolumleri Livewire component'i oluyor, geri kalani statik HTML:

<!-- Statik HTML -->
<header>
    <h1>Dashboard</h1>
    <nav>...</nav>
</header>

<!-- Sadece bu alan Livewire -->
@island
    <livewire:notification-bell />
@endisland

<!-- Statik HTML -->
<main>
    <div class="grid">
        <!-- Bu da Livewire -->
        @island
            <livewire:stats-widget />
        @endisland

        <!-- Bu statik -->
        <div class="static-content">
            ...
        </div>
    </div>
</main>

Filament'te bu ozellikle dashboard widget'larinda etkili. Her widget bagimsiz bir island olabiliyor, sayfa yuklemesi hizlaniyor.

3. wire:sort

Drag-and-drop siralama artik yerlesik:

<ul wire:sort="updateOrder">
    @foreach($items as $item)
        <li wire:sort.item="{{ $item->id }}" wire:key="{{ $item->id }}">
            <span wire:sort.handle>&#9776;</span>
            {{ $item->name }}
        </li>
    @endforeach
</ul>

public function updateOrder(array $items): void
{
    foreach ($items as $item) {
        Model::where('id', $item['value'])
            ->update(['order' => $item['order']]);
    }
}

Filament'in siralama ozelligi (reorderable tables) artik bu native API'yi kullaniyor. Onceki hacky JavaScript cozumleri yerine temiz bir implementasyon.

4. Async Actions

Livewire v4 ile action'lar asenkron calisabiliyor:

<button wire:click="generateReport" wire:async>
    Rapor Olustur
</button>

<!-- wire:async ile butona basildiginda UI bloklanmiyor -->
<!-- Islem arka planda calisiyor, bitince sonuc guncelleniyor -->

Filament'te bu ozellikle Action modal'larinda ve toplu islemlerde (bulk actions) kullaniliyor. Artik "500 kaydi guncelle" butonuna bastiginizda sayfa donmuyor.

5. Performans Iyilestirmeleri

Livewire v4'un en onemli iyilestirmesi diff algoritmasi. v3'te her guncelleme tum DOM'u karsilastiriyordu. v4'te sadece degisen kisimlar guncelleniyor:

• Ilk yukleme: ~%20 daha hizli
• Sonraki guncellemeler: ~%40 daha hizli
• Bellek kullanimi: ~%30 daha az
• Network payload: ~%25 daha kucuk

Filament panel'lerinde bu farki hissediyorsunuz. Ozellikle cok satirli tablolar ve karmasik formlar belirgin sekilde daha hizli.

6. Gelismis Error Handling

Livewire v4 hata yonetimini iyilestirdi:

// Livewire v4'te component-level error handling
class MyComponent extends Component
{
    public function onError(\Throwable $e): void
    {
        // Component seviyesinde hata yakalama
        // Tum sayfayi cokertemek yerine sadece bu component hata gosteriyor
        $this->addError('general', 'Bir hata olustu, lutfen tekrar deneyin.');
    }
}

Filament'te bu, widget'larin birbirini etkilememesi anlamina geliyor. Bir widget hata verse bile diger widget'lar calismaya devam ediyor.

Breaking Changes

Upgrade sirasinda dikkat etmeniz gereken degisiklikler:

1. Tailwind Class Degisiklikleri

Tailwind v4 bazi class'lari degistirdi:

<!-- Eski (v3) -->
<div class="bg-opacity-50">
<div class="text-opacity-75">

<!-- Yeni (v4) -->
<div class="bg-black/50">
<div class="text-black/75">

2. Livewire Lifecycle Hook'lari

// Eski (Livewire v3)
public function updatedName($value) { }
public function updatingName($value) { }

// Yeni (Livewire v4) - ayni calisiyor ama ek hook'lar var
public function updatedName($value) { }
public function updatingName($value) { }

// Yeni hook
public function changed(string $property, mixed $old, mixed $new): void
{
    // Herhangi bir property degistiginde
}

3. Custom Theme Guncelleme

Eger Filament theme'ini ozellestirdiyseniz CSS dosyasini guncellemeniz gerekiyor:

/* Eski (Tailwind v3 + PostCSS) */
@import '../../../../vendor/filament/filament/resources/css/theme.css';

@config 'tailwind.config.js';

/* Yeni (Tailwind v4 native) */
@import 'tailwindcss';
@import '../../../../vendor/filament/filament/resources/css/theme.css';

@source '../../views/**/*.blade.php';
@source '../../../../vendor/filament/**/*.blade.php';

@theme {
    --color-primary-500: #3b82f6;
    /* ... */
}

4. Removed Deprecated Methods

v4'te deprecated olan bazi metotlar v5'te tamamen kaldirildi:

// Kaldirildi: Bunlari kullaniyorsaniz degistirin
// $this->emit() -> $this->dispatch()
// $this->emitTo() -> $this->dispatch()->to()
// $this->emitSelf() -> $this->dispatch()->self()

Ne Zaman Upgrade Etmeli?

Hemen upgrade edin eger:

• Yeni proje basliyorsaniz (direkt v5 ile baslayin)
• Livewire v4 ozelliklerini kullanmak istiyorsaniz
• Tailwind v4'e gecmeyi planliyorsaniz
• Custom Livewire component'leriniz azsa

Bekleyin eger:

• Production'da stabil calisan buyuk bir projeniz varsa
• Cok sayida custom Livewire component'iniz varsa
• Ucuncu parti Filament plugin'leri kullaniyorsaniz (plugin'lerin v5 uyumlulugunu bekleyin)
• Tailwind v3'te kalmayi planliyorsaniz

Benim onerim: Yeni projelerde kesinlikle v5, mevcut projelerde 1-2 ay bekleyip plugin ekosisteminin uyum saglamasini gozleyin.

Filament Blueprint

Filament ekibinin duyurdugu premium AI araci Blueprint'ten de bahsetmek lazim. Bu Filament v5 ile birlikte duyuruldu ama ayri bir urun.

Blueprint, AI kullanarak Filament resource'lari, form'lari ve tablo'lari olusturuyor:

"Kullanici yonetimi sayfasi olustur. Kullanicilarin adi, emaili, rolu olsun.
Tablo filtrelenebilir ve aranabilir olsun. Form'da rol secimi dropdown olsun."

Bu prompt'tan:

• UserResource
• Form schema
• Table columns + filters
• Relations (varsa)
• Policies

uretiyor. Sonucu dogrudan projenize kopyaliyorsunuz.

Blueprint ucretsiz degil, Filament'in premium araci. Ama prototipleme ve baslangic icin ciddi zaman kazandirabilir. Ben henuz production'da kullanmadim ama denedigim kadariyla basit CRUD'lar icin gayet iyi sonuc veriyor. Karmasik is mantigi olan resource'larda elle mudahale gerekiyor.

Upgrade Checklist

Upgrade sirasinda takip edebileceginiz bir kontrol listesi:

[ ] Git'te yeni branch olustur (upgrade/filament-v5)
[ ] PHP >= 8.2 kontrol et
[ ] Laravel >= 11.28 kontrol et
[ ] Node.js >= 18 kontrol et
[ ] Veritabani yedegi al
[ ] composer require filament/upgrade --dev
[ ] php artisan filament:upgrade calistir
[ ] Custom theme'leri Tailwind v4'e guncelle
[ ] Custom Livewire component'leri guncelle
    [ ] #[Rule] -> #[Validate]
    [ ] emit() -> dispatch()
[ ] Ucuncu parti plugin uyumlulugunu kontrol et
[ ] npm install && npm run build
[ ] Tum sayfalari test et
    [ ] Dashboard
    [ ] Resource listeleme
    [ ] Resource olusturma/duzenleme
    [ ] Toplu islemler (bulk actions)
    [ ] Custom page'ler
    [ ] Widget'lar
[ ] CI/CD pipeline'i guncelle
[ ] Staging'e deploy et ve test et
[ ] Production'a deploy et

Test Ornegi

Upgrade sonrasi en azindan temel islemlerin calistigini dogrulayin:

// tests/Feature/Filament/UserResourceTest.php
<?php

namespace Tests\Feature\Filament;

use App\Filament\Resources\UserResource;
use App\Filament\Resources\UserResource\Pages\ListUsers;
use App\Filament\Resources\UserResource\Pages\CreateUser;
use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Livewire\Livewire;
use Tests\TestCase;

class UserResourceTest extends TestCase
{
    use RefreshDatabase;

    public function test_can_list_users(): void
    {
        $admin = User::factory()->admin()->create();
        User::factory()->count(5)->create();

        $this->actingAs($admin);

        Livewire::test(ListUsers::class)
            ->assertSuccessful()
            ->assertCanSeeTableRecords(User::all());
    }

    public function test_can_create_user(): void
    {
        $admin = User::factory()->admin()->create();

        $this->actingAs($admin);

        Livewire::test(CreateUser::class)
            ->fillForm([
                'name' => 'Test Kullanici',
                'email' => '[email protected]',
                'password' => 'password123',
                'password_confirmation' => 'password123',
            ])
            ->call('create')
            ->assertHasNoFormErrors();

        $this->assertDatabaseHas('users', [
            'name' => 'Test Kullanici',
            'email' => '[email protected]',
        ]);
    }

    public function test_can_search_users(): void
    {
        $admin = User::factory()->admin()->create();
        $user = User::factory()->create(['name' => 'Ahmet Yilmaz']);
        User::factory()->create(['name' => 'Mehmet Demir']);

        $this->actingAs($admin);

        Livewire::test(ListUsers::class)
            ->searchTable('Ahmet')
            ->assertCanSeeTableRecords([$user])
            ->assertCanNotSeeTableRecords([User::where('name', 'Mehmet Demir')->first()]);
    }
}

Sonuc

Filament v5 "sessiz" bir upgrade. Yeni parlak ozellikler yok ama altyapisi tamamen guncellenmis durumda. Livewire v4 + Tailwind v4 destegi, gelecekteki tum yeniliklerin temelini olusturuyor.

Benim icin en degerli uc sey:

1. Performans: Livewire v4'un diff algoritmasi gercekten hissedilir bir fark yaratiyor
2. Single-file components: Custom widget ve page yazarken muazzam kolaylik
3. Wire:sort: Native drag-and-drop siralama, ekstra paket gerektirmiyor

Upgrade'i planliyorsaniz once staging ortaminda deneyin, otomatik script'i calistirin, sonra manuel kontrol listesini takip edin. Cogu proje icin sorunsuz bir gecis oluyor ama custom Livewire component'leri ve ucuncu parti plugin'ler ekstra dikkat gerektiriyor.