Livewire 4 Tek Dosya Bileşenleri: Tek Dosyada Canlı Arama Oluşturma

Orijinal yazı hafiz.dev adresinde yayınlanmıştır.

Livewire v4’e güncellediğinizde php artisan make:livewire komutunu çalıştırdıysanız ve dosyanın resources/views/components/ altına düştüğünü fark ettiyseniz, bu bir hata değil. Bu, yeni varsayılan. Livewire 4, 2026 Ocak ayında tek dosya bileşenlerini standart format olarak sundu ve çoğu Livewire geliştiricisi hâlâ eski iki dosya modelini kullanmaya devam ediyor.

Bu makalede, tek dosya bileşenlerinin nasıl çalıştığını, hangi durumlarda bunların kullanılacağını, çok dosya formatındaki değişiklikleri, kapsamlı CSS ve JavaScript’i v4’te, ve bununla gerçek bir şey – filtreleme, kapsamlı stiller ve pahalı veriler için bir “Island” ile canlı bir arama bileşeni oluşturmayı ele alacağız. Kısayollar yok, sadece artık kullanacağınız format.

Eski İki Dosya Modelinin Sorunu

Livewire v3’te bir bileşen oluşturmak en az iki dosya gerektiriyordu. PHP sınıfı app/Livewire/SearchPosts.php içinde bulunurken, Blade görünümü resources/views/livewire/search-posts.blade.php içinde yer alıyordu. Bileşen belirli JavaScript eklemek isterseniz, @script veya @push('scripts') komutlarına başvuruyordunuz. CSS genellikle iç içe ya da bir yığına itiliyordu.

Bu yöntem işliyordu. Ancak her bileşeni oluşturduğunuzda zihninizde iki dosyayı birleştirmek zorundaydınız. Editörünüzde bir bileşen aradığınızda iki sonuç elde ediyordunuz. Bir diff okuduğunuzda, mantık ve şablon ayrı PR satırlarında görünüyordu. Aralarındaki bağlantı yalnızca kafanızda ve render() metodunda mevcuttu.

Livewire 4, her şeyi tek bir dosyada topluyor. PHP sınıfı, Blade şablonu, kapsamlı CSS ve bileşen JavaScript. Tek bir dosya, tek bir arama sonucu, tek bir diff parçası. Tüm amacımız bu.

Tek Dosya Bileşeni Nasıl Görünür?

Bunu oluşturmak için şu komutu çalıştırın:

php artisan make:livewire search-posts

Bu, resources/views/components/⚡search-posts.blade.php dosyası oluşturur. Yapısı şudur:

use Livewire\Component;
use Livewire\Attributes\Computed;
use App\Models\Post;

new class extends Component {

    public string $query = '';

    #[Computed]
    public function results()
    {
        if (strlen($this->query)  2) {
            return collect();
        }

        return Post::where('title', 'like', "%{$this->query}%")
            ->limit(10)
            ->get();
    }

};

?>

script ve style blokları tarayıcının önbelleği ile birlikte yerel .css ve .js dosyası olarak sunulmaktadır. Livewire, paketlemeyi yönetir. Bunun çalışması için vite.config.js veya webpack.mix.js dosyalarını değiştirmenize gerek yoktur.

Pahalı Veriler İçin Bir Island Ekleme

Arama bileşenimiz her tuşa bastığımızda bir veritabanı sorgusu çalıştırır (300ms ile geciktirilmiştir). Bu basit bir arama için sorun değil. Ancak bileşenin aynı zamanda bazı istatistikleri, toplam gönderileri, en fazla aranan terimleri gösterme gibi özellikleri varsa ve bunlar her aramada değişmiyorsa pahalı bir hesaplama yapılması gerekir.

İşte burada “Islands” devreye girer. Bileşeninizin bir bölümünü bağımsız olarak güncellemek için işaretlemenizi sağlar:

use Livewire\Component;
use Livewire\Attributes\Computed;
use App\Models\Post;

new class extends Component {

    public string $query = '';

    #[Computed]
    public function results()
    {
        if (strlen($this->query)  2) {
            return collect();
        }

        return Post::where(, , "%{$this->query}%")
            ->limit(10)
            ->get();
    }

    #[Computed]
    public function stats()
    {
        return [
            => Post::count(),
            => Post::where(, )->count(),
        ];
    }

};

?>

Kullanıcı yazarken yalnızca arama sonuçları yeniden oluşturulur. stats bölgesi tembel bir şekilde yüklenir ve açıkça yenilemenizi söylemedikçe önbellekte kalır. stats() için veritabanı sorguları her tuş vuruşunda çalışmaz. Ana performans kazanımınız burada, bileşeninizin pahalı bölümlerini izole ediyorsunuz, bunlara her etkileşimde ödeme yapmıyorsunuz.

Bileşeni Oluşturma

Herhangi bir Blade şablonuna normal bir Livewire bileşeni gibi dahil edebilirsiniz:

Bileşen adı dosya adından türetilir. ⚡ ön eki ve dizin yapıları otomatik olarak kaldırılır. Yani ⚡search-posts.blade.php search-posts olur. Sadece dosya değil, çok dosya ve tek dosya formatı arasında geçiş yapabilirsiniz.

Tam sayfa bileşenleri (örneğin bağımsız bir sayfa olarak arama sonuçları için) pages:: ad alanını kullanarak oluşturulur:

php artisan make:livewire pages::search

Yolu Route::livewire() ile kaydedin:

Route::livewire(, );

Ne Zaman Tek Dosya, Ne Zaman Çok Dosya Kullanılmalı?

Tek dosya, çoğu bileşen için doğru varsayılandır. Birkaç yüz satıra kadar iyi çalışır, gerçek dünya kullanım durumlarının çoğunu kapsar ve her şeyi bir arada tutar.

Çok dosya, bir bileşen yeterince karmaşık hale geldiğinde veya bileşenin yanına özel bir test dosyası istediğinizde mantıklıdır. Bunu oluşturmak için:

php artisan make:livewire post.editor --mfc

Bu, bir dizin oluşturur:

resources/views/components/post/⚡editor/
├── editor.php
├── editor.blade.php
├── editor.js
└── editor.css

Dizin yapısı bileşeni referanslama şeklinizi değiştirmez. yine de çalışır. Ve her zaman formatlar arasında geçiş yapabilirsiniz:

# Tek dosyadan → Çok dosyaya
php artisan livewire:convert search-posts

# Çok dosyadan → Tek dosyaya
php artisan livewire:convert post.editor --single

Bir çok dosya bileşeninin bir test dosyası varsa, Livewire, test dosyaları bu formatta korunamayacağından tek dosyaya geçiş yapmadan önce sizi uyaracaktır.

v3 Bileşenini Geçiş

Mevcut v3 sınıf tabanlı bileşenleriniz varsa, hiçbir şey bozulmaz. Tamamen olduğu gibi çalışmaya devam eder. Ama belirli bir bileşeni yeni formata taşımak istiyorsanız, işte öncesi ve sonrası:

Önce (v3 sınıf tabanlı):

app/Livewire/SearchPosts.php:

namespace App\Livewire;

use Livewire\Component;
use App\Models\Post;

class SearchPosts extends Component
{
    public string $query = ;

    public function render()
    {
        return view(, [
            => Post::where(, , {->query})
                ->limit()
                ->get(),
        ]);
    }
}

resources/views/livewire/search-posts.blade.php:

Sonra (v4 tek dosya):

resources/views/components/⚡search-posts.blade.php:

Ana farklılıklar: ayrı bir sınıf dosyası yok, render() metodu yok, sonuçlar $this->results aracılığıyla erişilir ve #[Computed] özellik kullanılır, ayrıca tanımsız bir sınıf tanımı ile yerel App\Livewire ad alanı kullanılmaz.

Geçiş yapmak isteyenler için bilmesi gereken bir v4 değişikliği: wire:model artık alt öğelerden yukarı doğru tamponlanan olayları dinlemez. v3’te, bir kapsayıcı üzerindeki wire:model, içindeki girişlerden gelen olayları yakalıyordu. Bu v4 ile değişti, wire:model, yalnızca bağlı olduğu eleman üzerindeki doğrudan olayları yanıtlıyor. Eski davranışı istiyorsanız, .deep modifikatorunu ekleyin: wire:model.deep. Bu, çoğu geliştirici için ilk seferde olduklarından şaşırdığı bir durumdur.

SSS

Mevcut v3 bileşenlerimi yeniden yazmak zorunda mıyım?

Hayır. Sınıf tabanlı bileşenler, daha önce olduğu gibi çalışmaya devam eder. Tek dosya, gelecekte oluşturacağınız bileşenler için yeni varsayılan ancak eski bileşenleri taşımak zorunda değilsiniz.

Filament’i Livewire 4 tek dosya bileşenleriyle kullanabilir miyim?

Evet. Filament v5, Livewire v4 ile çalışır. Filament kaynaklarınız ve özel sayfalarınız, kendi Livewire bileşenlerinizden ayrı olarak, çelişmeden bir arada var olabilir. Bir Filament yönetim paneli inşa ediyorsanız, Filament’in işleyişinde hiçbir şey değiştirmeniz gerekmez.

#[Computed] niteliği, şablonda erişilen özellikler için gerekli mi?

Hayır. İsterseniz verileri şablona render() metoduyla da geçirebilirsiniz. #[Computed], isteğin ömrü boyunca sonucu önbelleğe alır ve özelliği doğrudan $this->results olarak şablonda erişilebilir hale getirir. v4 için daha temiz bir yapıdadır.

wire:model.live, v3’teki gibi çalışır mı?

Debouncing davranışı aynıdır, ancak olay baloncuklanma davranışı değişti. v4’te, wire:model yalnızca doğrudan elemana ait olayları dinler, alt öğelerden yukarı doğru baloncuklanan olayları dinlemez. Standart giriş öğeleri (metin, seçim, textarea) için farklılık göremezsiniz. Değişiklik yalnızca, kapsayıcı öğeler üzerindeki wire:model için geçerlidir.

Tek dosya bileşenleri içinde Alpine.js kullanmaya devam edebilir miyim?

Evet, tamamen. Alpine direktifleri, şablonda önceki gibi çalışır. bloğu, PHP-JavaScript sınırını geçmek için $wire kullanmanızı sağlar. Alpine, istemci tarafı durumunu yönetir, $wire sunucu durumunu yönetir.

Tek dosya formatı, v3’te mümkün olan hiç bir şeyi devre dışı bırakmaz, sadece her bileşen için iki dosyayı yönetme yükünü ortadan kaldırır. Küçük ve orta ölçekli bileşenler için bu, gerçek bir iyileşmedir ve kapsamlı CSS veya bileşene özel JavaScript içeren her şey için çok daha temizdir. Eğer bir Livewire ve Filament ile SaaS inşa ediyorsanız, artık v4 formatında yeni bileşenler oluşturmak, uygulamanız büyüdükçe daha az bağlam geçişi ve daha az dosya takip etmeyi sağlar.

Tam bileşen referansı için Livewire v4 resmi belgelerine göz atın, ad alanları, slotlar ve öznitelik iletimi dahil.

Bir proje planlıyorsanız ve Livewire mi yoksa Inertia mı seçmeniz gerektiğinden emin değilseniz, Livewire 4 ve Inertia.js 3 karşılaştırması kararınızı detaylı bir şekilde ele alır.

Livewire ile bir şey inşa ediyorsanız ve başka bir geliştiricinin gözden geçirmesini istiyorsanız, ulaşın.