400 Satırlık Import Kontrolcülerden 20 Satırlık Konfigürasyonlara Laravel’de

Laravel ile iş uygulamaları geliştirdiyseniz, büyük ihtimalle şu isteği almışsınızdır:

“Bir admin olarak, stok seviyelerimizi güncellemek için 50.000 ürünle bir CSV yüklemem gerekiyor.”

Bu talebi farklı projelerde en az bir kez duymuş olmalısınız. İlk başta basit görünüyor. Bir CSV parser alıyorsunuz, belki league/csv veya maatwebsite/excel, ve bir Controller yazmaya başlıyorsunuz.

On dakika sonra, karmaşanın içinde kayboluyorsunuz:

• “49.000. satırı bellek çökmeden nasıl doğrulabilirim?”
• “Müşteri, ‘E-Mail’ sütununu adlandırıyor ama bazen ‘Email Address’ olarak geliyor.”
• “İsimle Kategori ID’sini bulmalıyım ama yoksa oluşturmalıyım.”
• “Müşteri, veritabanına işlemi gerçekleştirmeden önce hataları görmek istiyor.”

Controller’ınız while döngüleri, try-catch blokları ve manuel doğrulama mantığı ile 400 satıra ulaşan bir canavara dönüşüyor. Test etmek zor, okumak zor ve yeniden yapılandırmak korkutucu.

Daha iyi bir yolu olmalı.

Laravel Ingest adlı bir paket geliştirdim, bu tür karmaşaların önüne geçmek için.

Laravel Ingest, konfigürasyon odaklı bir çerçeve olarak, veri ithalatını yönetiyor. İşlem adımını kendiniz yazmak yerine, ne ithal etmek istediğinizi tanımlıyorsunuz ve paket nasıl yapılacağını hallediyor.

Aşağıdaki işlemleri üstleniyor:

• Streaming & Queues: 100’den 1 milyon satıra kadar sıfır bellek sorunu.
• Mapping & Transformation: CSV sütunlarını Eloquent niteliklerine haritalama için akıcı bir API.
• Relationships: BelongsTo ve BelongsToMany ilişkilerini otomatik olarak çözer.
• Dry Runs: Veritabanına dokunmadan hataları bulmak için ithalat simülasyonu yapar.
• API & CLI: Otomatik olarak oluşturulmuş uç noktalar ve Artisan komutları.

Gereksinimler

• PHP 8.3+
• Laravel 10, 11 veya 12

Nasıl Çalışır

Örneğin, Kullanıcıları ithal etmek istiyoruz. Bir Controller yerine, bir Importer Class oluşturuyoruz.

1. Bildirim Düzlemi

Burası sihrin olduğu yer. Ne kadar okunabilir olduğuna bakın:

namespace App\Ingest;

use App\Models\User;
use LaravelIngest\Contracts\IngestDefinition;
use LaravelIngest\IngestConfig;
use LaravelIngest\Enums\SourceType;
use LaravelIngest\Enums\DuplicateStrategy;

class UserImporter implements IngestDefinition
{
    public function getConfig(): IngestConfig
    {
        return IngestConfig::for(User::class)
            ->fromSource(SourceType::UPLOAD)
            // Kayıtları e-posta ile tanımlayın
            ->keyedBy('email')
            // Eğer e-posta mevcutsa, kaydı güncelleyin
            ->onDuplicate(DuplicateStrategy::UPDATE)
            // CSV 'Tam İsim' alanını DB 'name' alanına haritalayın
            ->map('Full Name', 'name')
            // CSV 'E-Mail' (veya 'Email') alanını DB 'email' alanına haritalayın
            ->map(['E-Mail', 'Email'], 'email')
            // 'yes/no' dizesini boolean'a dönüştürün
            ->mapAndTransform('Is Admin', 'is_admin', fn($val) => $val === )
            // Her satır için Laravel doğrulama kuralları kullanın
            ->validate([
                'Full Name' => 'required|string|min:3',
                'E-Mail'    => 'required|email',
            ]);
    }
}

2. İthalatçıyı Kaydetmek

AppServiceProvider içinde, sadece şu şekilde etiketliyorsunuz:

$this->app->tag([UserImporter::class], 'ingest.definition');

3. İthalatı Çalıştırmak

Yüklemeler için bir Controller yazmanıza gerek yok. Laravel Ingest, otomatik olarak API uç noktaları ve Artisan komutları sağlar.

CLI Üzerinden (cronjoblar veya S3 ithalatları için mükemmel):

php artisan ingest:run user-importer --file=users.csv

API Üzerinden (frontend’iniz için):

POST /api/v1/ingest/upload/user-importer
Body: file=@users.csv

Öne Çıkan Özellikler

1. İlişkileri Yönetmek Artık Kolay

Genellikle, ilişkili verileri içe aktarmak (örneğin, bir Ürünü Kategoriye isimle atamak) can sıkıcı arama mantığını gerektirir. Ingest bunu bir satırda yapar:

// 'name' ile Kategoriyi arar. 
// Varsa oluşturur!
->relate(
    sourceColumn: ,
    relation: ,
    relatedModel: Category::class,
    lookupColumn: ,
    createIfMissing: true
)

2. Dry Runs Kutudan Çıktığında

Müşteriler, ithalatın ortasında başarısız olduğu zaman bunu sevmez. Ingest ile tüm doğrulama ve dönüşümleri çalışan, ancak değişiklikleri geri alan bir simülasyon başlatabilirsiniz.

php artisan ingest:run user-importer --file=users.csv --dry-run

3. Hata Analizi API

Satırlar başarısız olduğunda, sadece bir log dosyası almazsınız. Ingest, hatalı satırları veritabanında takip eder ve hata mesajları ile birlikte yalnızca hatalı satırların CSV’sini indirmek için bir API uç noktası sağlar. Kullanıcılar hataları Excel’de düzeltebilir ve yalnızca bu satırları yeniden yükleyebilir.

Kaputun Altında

Laravel Ingest, büyük yapıların omuzlarında duruyor. spatie/simple-excel kullanarak dosyaları satır satır akıtarak (bellek kullanımını sabit tutarak) Laravel Queue’ya satır bloklarını itiyor.

Bu, uygulamanızın, 500MB’lık bir dosyayı ithalat yaparken bile duyarlı kalmasını sağlar.

Başlamak

Kurulum oldukça basittir:

composer require zappzerapp/laravel-ingest
php artisan vendor:publish --provider="LaravelIngest\IngestServiceProvider"
php artisan migrate

Kaynaklar:

Sonuç

Bu paketi, her projede aynı kırılgan ithalat kodunu yazmaktan bıktığım için geliştirdim. Eğer “CSV yükleme” kelimelerinden korktuysanız, Laravel Ingest’i deneyin.

Faydalı bulduysanız, GitHub’da repo’ya yıldız atın, özellik istekleri için bir sorun açın veya aşağıda bir yorum bırakın. Nasıl kullandığınızı duymak beni çok mutlu eder!