1,200 Satırlık Filament Kaynağını Bakımını Yapabileceğim Bir Şeye Nasıl Yeniden Yapılandırdım

Orijinal yayın hafiz.dev

Bir kaynak dosyasının sorun yaşadığına dair en büyük ipucu, table() fonksiyonuna ulaşmak için üç sayfa aşağı kaydırmak zorunda kalmanızdır. Eğer her pull request aynı dosyada değişiklik yapıyorsa ve her şey tek bir yerde yaşıyorsa sorun büyüyor demektir. Eğer bir tabloya yeni bir sütun eklemek, 400 satırlık form alanlarından kaydırarak bulmayı zorlaştırıyorsa bu kod gözden geçirilmelidir.

Filament kaynakları, bir Laravel projesindeki diğer dosyalardan çok daha hızlı büyür. Framework, küçük modeller için harika olan tüm formları, tabloları, eylemleri, filtreleri ve ilişkileri tek bir sınıfta tanımlamayı kolaylaştırır. Ancak karmaşık bir yapı için bu tek sınıf, kod tabanınızdaki en tehlikeli dosya haline gelir: geçişi zor, test edilmesi karmaşık ve değiştirilmesi kırılgan olur.

Bir çok adımlı onboarding akışını yöneten bir kaynakla bu durumu yaşadım. Form, sekmeler, koşullu alanlar, tekrar eden bileşenler ve özel doğrulama içeriyordu. Tablo 15 sütun, 6 filtre ve 4 özel işlem içeriyordu. Kaynak dosyası 1,247 satırdı. Her açtığımda, koddan çok kaydırma yaparak vakit geçiriyordum.

Seviye 1: Form ve tabloyu metotlara ayırın

Bu işlem sadece beş dakika sürer ve dosyayı hemen gezilebilir hale getirir.

Her şeyi form() ve table() fonksiyonları içinde tanımlamak yerine, mantıksal bölümleri aynı sınıf içinde statik metotlara çıkarın:

class OrderResource extends Resource
{
    public static function form(Form $form): Form
    {
        return $form->schema([
            Tabs::make('Order')
                ->tabs([
                    Tab::make('Details')->schema(static::detailsFormSchema()),
                    Tab::make('Shipping')->schema(static::shippingFormSchema()),
                    Tab::make('Payment')->schema(static::paymentFormSchema()),
                ]),
        ]);
    }

    protected static function detailsFormSchema(): array
    {
        return [
            TextInput::make()->disabled(),
            Select::make()->options(OrderStatus::labels()),
            Select::make()
                ->relationship(, )
                ->searchable()
                ->preload(),
            // ... 15 more fields
        ];
    }

    protected static function shippingFormSchema(): array
    {
        return [
            TextInput::make(),
            TextInput::make(),
            Select::make()
                ->options(Country::pluck(, )),
            // ...
        ];
    }

    protected static function paymentFormSchema(): array
    {
        }
}

Aynı şeyi tablo için de yapın:

public static function table(Table $table): Table
{
    return $table
        ->columns(static::tableColumns())
        ->filters(static::tableFilters())
        ->actions(static::tableActions())
        ->bulkActions(static::tableBulkActions());
}

protected static function tableColumns(): array
{
    return [
        TextColumn::make()->sortable()->searchable(),
        TextColumn::make()->sortable(),
        BadgeColumn::make()->colors(OrderStatus::colors()),
        TextColumn::make()->money()->sortable(),
        // ...
    ];
}

Bu işlem satır sayısını azaltmaz, ancak dosyayı gezilebilir hale getirir. IDE’nizde metotları çökertmek mümkündür. form() metodu artık 200 yerine 10 satırdır. Bir düzenlemeye ihtiyaç duyduğunuzda doğrudan shippingFormSchema() fonksiyonuna atlayabilirsiniz.

Ne zaman kullanılmalı: Her zaman. Küçük kaynaklar için bile bu iyi bir uygulamadır. Hiçbir maliyeti yoktur ve hemen faydasını görürsünüz.

Seviye 2: Form bölümlerini ayrı sınıflara çıkarın

Bir form bölümünde 20’den fazla alan veya karmaşık koşullu mantık varsa, bunu kendi sınıfına çıkarın. İşte burada gerçek satır sayısını azaltabilirsiniz.

Filament\Forms\Components\Section sınıfını genişleten bir sınıf oluşturun:

namespace App\Filament\Forms\Sections\Order;

use Filament\Forms\Components\Section;
use Filament\Forms\Components\TextInput;
use Filament\Forms\Components\Select;

class ShippingSection extends Section
{
    public static function make(string $heading = ): static
    {
        return parent::make($heading)
            ->schema([
                TextInput::make()
                    ->required()
                    ->maxLength(255),
                TextInput::make()
                    ->required(),
                Select::make()
                    ->options(Country::pluck(, ))
                    ->searchable()
                    ->required(),
                TextInput::make(),
                TextInput::make(),
            ])
            ->columns(2)
            ->collapsible();
    }
}

Artık kaynak, sadece bir satırla buna referans verir:

use App\Filament\Forms\Sections\Order\ShippingSection;

public static function form(Form $form): Form
{
    return $form->schema([
        Tabs::make()->tabs([
            Tab::make()->schema(static::detailsFormSchema()),
            Tab::make()->schema([
                ShippingSection::make(),
            ]),
            Tab::make()->schema([
                PaymentSection::make(),
            ]),
        ]),
    ]);
}

Her bölüm sınıfı, kendi alanlarını, doğrulamasını ve düzenini üstlenir. Kaynak dosyası 1,200 satırdan 200’lere düşer. Ve aynı gönderim formu başka bir kaynakta (örneğin CustomerResource veya ReturnResource) gerekli olduğunda, bölüm sınıfını tekrar kullanabilirsiniz.

Kullandığım dizin yapısı:

app/Filament/Forms/Sections/
    Order/
        ShippingSection.php
        PaymentSection.php
        DetailsSection.php
    Customer/
        PersonalInfoSection.php
        AddressSection.php

Ne zaman kullanılmalı: Bir form bölümünde 15’ten fazla alan olduğunda, aynı alanlar birden fazla kaynakta tekrar ettiğinde veya bir bölümün karmaşık koşullu mantığı olduğunda.

Seviye 3: Tablo işlemlerini Eylem sınıflarına çıkarın

Filament tablo işlemleri çevrimiçi tanımlanır ve hızla artar. Bir onay penceresi, form alanları ve iş mantığı içeren bir işlem 30-50 satır olabilir. Dört işlem varsa, sadece eylemler dizisi için 200 satıra ulaşabilirsiniz.

Çözüm: özel Eylem sınıfları oluşturun. İşte Johannes Pichler’in yaklaşımından uyarlanan bir model:

namespace App\Filament\Actions\Order;

use Filament\Tables\Actions\Action;
use Filament\Notifications\Notification;

class MarkAsShippedAction
{
    public static function make(): Action
    {
        return Action::make()
            ->label()
            ->icon()
            ->requiresConfirmation()
            ->action(function ($record) {
                $record->update([=> ]);
                $record->customer->notifynew OrderShippedNotification($record));

                Notification::make()
                    ->title()
                    ->success()
                    ->send();
            })
            ->visiblefn ($record) => $record->status === );
    }
}

Kaynak içindeki işlem kaydı, bir satır haline gelir:

protected static function tableActions(): array
{
    return [
        MarkAsShippedAction::make(),
        SendInvoiceAction::make(),
        RefundAction::make(),
        Tables\Actions\EditAction::make(),
    ];
}

Her işlem bağımsız olarak test edilebilir. Her işlem gerektiğinde başka kaynaklarda tekrar kullanılabilir. Ve kaynak dosyası, yeni bir işlem ekledikçe büyümez.

Ne zaman kullanılmalı: Eylemler, basit CRUD’dan öte iş mantığı içerdiğinde. Eğer işlem sadece EditAction::make() veya DeleteAction::make() gibi basitse, çevrimiçi bırakın. İşlem özel mantık, onaylar, form alanları veya bildirimler içeriyorsa çıkarın.

İşlemleri Hizmetlerden ayırma konusunda daha geniş bir çerçeve için, Hizmet vs Eylem vs İş karar ağacı genel ilkelere göz atabilir.

Seviye 4: Sayfa düzeyinde override kullanın

Filament kaynakları, Oluştur, Düzenle, Görüntüle ve Liste için sayfa sınıflarına devreder. Her sayfa, kaynağın form veya tablo konfigürasyonunu geçersiz kılabilir. Bu, oluşturma ve düzenleme formlarınız önemli ölçüde farklı olduğunda faydalıdır.

namespace App\Filament\Resources\OrderResource\Pages;

use App\Filament\Resources\OrderResource;
use Filament\Resources\Pages\CreateRecord;
use Filament\Forms\Form;

class CreateOrder extends CreateRecord
{
    protected static string $resource = OrderResource::class;

    public function form(Form $form): Form
    {
        return $form->schema([
            // Basitleştirilmiş oluşturma formu: yalnızca temel alanlar
            TextInput::make()->required(),
            Select::make()->relationship(, ),
            TextInput::make()->numeric()->default(1),
        ]);
    }
}

Oluşturun formu 3 alan içerirken, düzenleme formu (kaynak üzerinde tanımlanan) 40 alan içerir. Bu ayrım olmadan, her yerde koşullu ->hidden() çağrıları bulmak zorunda kalırdınız, form tanımını takip etmeyi zorlaştırır.

Ne zaman kullanılmalı: Oluşturma ve düzenleme formları önemli ölçüde farklı olduğunda, liste sayfasının kaynak tanımından farklı bir tablo konfigürasyonu gerektiğinde veya belirli bir sayfanın benzersiz üstbilgi işlemleri olduğunda.

Ne kadar ileri gitmeli

Her kaynak, dört seviye gerektirmez. İşte basit bir versiyon:

200 satırdan az: Refaktöre etmeyin. Kaynak iyi durumda.

200-500 satır: Seviye 1 (metot çıkarımı). Beş dakika sürer. Yapın.

500-1,000 satır: Seviye 1 + 2 (metot çıkarımı + bölüm sınıfları). Bu çoğu durumu yönetir.

1,000 satırdan fazla: Tüm dört seviye. Kaynağınız yeterince karmaşık, bu yapıya ihtiyaç var. Refaktörizasyon için harcanan zaman, 400 satırlık form alanlarının üzerine kaydırma yapmaktan kaçınmak için geri döner.

Amaç, kaynakta en az satır sayısına sahip olmak değil, kaynakları navigasyon, test edilebilirlik ve değişikliklerin güvenliğini sağlamaktır. Dosyayı açıp, aradığınız şeyi 5 saniye içinde bulabiliyor ve yan etkilerden korkmadan değiştirebiliyorsanız, refaktörizasyon başarılı olmuştur.

Filament tabanlı bir SaaS’ın daha geniş mimarisi için, tam SaaS kılavuzu bireysel kaynakların ötesindeki kalıpları ele alır. Bu çıkarım tekniklerinin temelini oluşturan tasarım kalıpları arasında Strateji ve Kompozisyon burada önemli olanlardır.

SSS

Form bölümlerini çıkarmak, Filament’in reactivity (wire:model, koşullu görünürlük) etkiler mi?

Hayır. Çıkarılan bölümler, aynı bileşen dizilerini döndüren PHP sınıflarıdır. Livewire’in reaktivitesi, işlenen bileşen ağaçlarına dayanmaktadır, hangi PHP sınıfının bileşenleri tanımladığına değil. ->visible(fn (Get $get) => $get('status') === 'active') kaynağın içinde veya bir bölüm sınıfında tanımlanmış olsun, aynı şekilde çalışır.

Traits yerine ayrı sınıflar mı kullanmalıyım?

Traits, küçük çıkarımlarda (paylaşılan bir filter seti, yaygın bir toplu işlem seti) işe yarar. Form bölümleri ve tablo konfigürasyonları için, ayrı sınıflar daha iyidir çünkü bağımsız olarak test edilebilirler ve kaynağın ad alanını kirletmezler. 6 trait içeren bir kaynak, 1,200 satırlık bir kaynağa göre gezmek açısından aynı şekilde zorlayıcı olabilir.

rmitesh/filament-action paketi ne olacak?

Bu, Filament eylem sınıflarını oluşturmak için bir artisan komutu sağlar: php artisan make:filament-action CommentAction --resource=UserResource. Birden fazla kaynakta birçok eylemi çıkarıyorsanız, gereksiz kodu azaltarak pratik olabilir. Az sayıda çıkarım için Seviye 3’teki manuel yöntem daha hafif kalır.

Çıkarılan bölüm sınıflarını nasıl test ederim?

Bölümü başlatın, statik make() metodunu çağırın ve şemanın beklenen bileşenleri içerdiğini doğrulayın. Tüm kaynakla beraber bölümü işleyen bir form render etmek için Filament’in test araçlarını kullanarak alan değerlerini de doğrulayabilirsiniz. Ana fayda: bölümü, tüm kaynağı yüklemeden test edebilirsiniz.

Bu yaklaşımı Filament v4/v5 ile kullanabilir miyim?

Evet. Bölüm ve eylem çıkarım kalıpları, Filament v3, v4 ve v5 üzerinde çalışır. Bileşen API’si istikrarlıdır. Versiyonlar arasında tek değişiklik, içe aktarma yolları ve bazı metot isimleri olacaktır, bunları güncellemek oldukça kolaydır.

Sonuç

Tüm dört seviyeyle 1,247 satırlık kaynak üzerinde uygulama yaptığınızda, kaynak dosyasının kendisi 187 satıra düştü. Form, bölüm referanslarının bir listesidir. Tablo, sütun ve eylem referanslarının bir listesidir. Her bölüm ve eylem kendi dosyasında, test edilebilir ve tekrar kullanılabilir bir halde bulunmaktadır.

Tüm dosyaların toplam satır sayısı aslında orijinal tek dosyadan daha yüksektir. Bu doğru bir takastır. Kod organizasyonu, daha az satırdan daha fazlasıdır. Her dosyanın bir işi olması, kolay bulunması ve yan etkiler olmaksızın güvenli şekilde değiştirilebilmesi amacı güder.

Gelişen bir projeniz varsa ve mevcut yapısının ötesine geçiyorsa, benimle iletişime geçebilirsiniz.