PDF İşlemleri İçin Laravel Paketini Geliştirdim (Çünkü Başka Hiçbir Şey Uygun Gelmedi)

Kullanıcı projelerinde, yüklenen PDF’leri AI modeline göndermeden önce işlemenin gerekliliği ile karşılaştım. Belgeler, bir şehri tarif eden çok sayfalı taranmış belgelerdi ve AI, tüm belgeler yerine bireysel sayfalarla daha iyi çalışıyordu. Yani, yapmam gereken şey PDF’leri ayırmaktı.

Bu nedenle, bir Laravel paketi arayışına çıktım. Birkaç seçenek buldum, ancak hiçbiri doğru hissettirmedi.

Laravel Ekosistemindeki PDF Problemi

Laravel ekosistemi, PDF’leri oluşturmak için harika paketler sunuyor, örneğin Spatie’nin laravel-pdf paketi. Ancak mevcut PDF’leri (örneğin ayırma, birleştirme, sayfa çıkarma veya filigran ekleme) manipüle etmek söz konusu olduğunda durum farklı.

Bu işlemler mevcut araçlarla yapılabilir. Örneğin, FPDI sayfaları birleştirebilir ve qpdf veya Ghostscript gibi CLI araçlarını sararak belgeleri ayırabilirsiniz. Ancak, bu durumda tüm entegrasyon kodunu kendiniz yazmak zorundasınız. Dosya sistem disk desteği yok, hizmet kapsayıcı entegrasyonu yok ve akıcı bir API yok.

Bir façad ile, zincirleme yöntemler ve uygun Depolama entegrasyonu arıyordum. Eloquent sorguları yazıyormuşum gibi hissettiren bir şey.

Collate ile Tanışın

Collate, arka planda qpdf ile güçlendirilmiş bir Laravel paketidir. İşte bu sorunumu çözmek için nasıl kullanıldığına dair bir örnek:

use Johind\Collate\Facades\Collate;

$pages = Collate::open($request->file('directory-scan'))
    ->split('ai-processing/scan-page-{page}.pdf');

// $pages → Collection ['ai-processing/scan-page-1.pdf', ...]
// Şimdi her sayfayı AI işlem hattınıza besleyin

İşte bu. Yüklenen dosya işlendi, sayfalar ayrıldı, geçici dosyalar otomatik olarak temizlendi ve bir path koleksiyonu geri alındı.

Ancak temeli oluşturduktan sonra devam ettim. Bunun ekosistemde eksik olduğunu düşündüm ve doğrusu bunu inşa etmek eğlenceliydi, bu nedenle tam bir araç setine dönüştü.

Başka Neler Yapabilirsiniz?

Birden fazla belgeyi birleştirin:

Collate::merge('cover.pdf', 'report.pdf', 'appendix.pdf')
    ->save('complete-report.pdf');

Bir belgeyi bir overlay ile filigranlayın:

Collate::open('proposal.pdf')
    ->overlay('branding/confidential-stamp.pdf')
    ->save('stamped-proposal.pdf');

Tüm bir iş akışını zincirleyin. Standart şartları ekleyin, meta verileri ayarlayın, şifreleyin ve S3’e itebilirsiniz:

Collate::open($request->file('document'))
    ->addPages('legal/standard-terms.pdf')
    ->withMetadata(title: 'Client Report 2025')
    ->encrypt('client-password')
    ->toDisk('s3')
    ->save('reports/final.pdf');

Belirli sayfaları çıkarın veya kaldırın:

Collate::open('document.pdf')
    ->onlyPages([1, 2, 3])
    ->save('first-three-pages.pdf');

Collate::open('document.pdf')
    ->removePages('5-10')
    ->save('trimmed.pdf');

Sayfaları döndürün, formları düzleştirin, web için optimize edin:

Collate::open('scanned.pdf')
    ->rotate(90, range: '1-3')
    ->flatten()
    ->linearize()
    ->save('cleaned-up.pdf');

Metaverileri ve sayfa sayılarını okumak için hiçbir şeyi değiştirmeden:

$meta = Collate::inspect('document.pdf')->metadata();
$meta->title;  // 'Quarterly Report'
$meta->author; // 'Taylor Otwell'

$count = Collate::inspect('document.pdf')->pageCount();

Her şey zincirlenebilir.

Laravel için Özel Olarak Tasarlandı

Onu özelleştiren birkaç özellik:

Depolama disk entegrasyonu. S3’ten okuma, yerel diske yazma veya tersine. Collate, uzaktaki diskler için geçici dosya yönetimini şeffaf bir şekilde halleder:

Collate::fromDisk('s3')
    ->open('uploads/contract.pdf')
    ->toDisk('local')
    ->save('processed/contract.pdf');

Responsable. Kontrolörden doğrudan bir PendingCollate döndürün ve Laravel bunu tarayıcıya akıtır. Daha fazla kontrol gerekiyorsa download() ve stream() seçenekleri de mevcuttur:

public function show()
{
    return Collate::open('invoice.pdf');
}

Şartlı işlemler Laravel’in Conditionable trait’i aracılığıyla:

Collate::open('document.pdf')
    ->when($request->boolean('watermark'), fn ($pdf) => $pdf->overlay('watermark.pdf'))
    ->when($request->boolean('flatten'), fn ($pdf) => $pdf->flatten())
    ->save('output.pdf');

Kendi yeniden kullanılabilir işlemleriniz için makrolar:

PendingCollate::macro('stamp', function () {
    return $this->overlay('assets/stamp.pdf');
});

Collate::open('contract.pdf')->stamp()->save('stamped.pdf');

Gereksinimler

Collate, PHP 8.4+, Laravel 11 veya 12 ve sisteminizde qpdf v11.0.0+ yüklenmesini gerektirir. Kurulumu oldukça basittir:

composer require johind/collate
php artisan collate:install

Kurulum komutu, konfigürasyonu yayınlar ve qpdf’nin mevcut olup olmadığını doğrular.

Sonuç

Collate’i, gerçek bir proje için ihtiyacım olduğu için inşa ettim ve Laravel’de evinde hissettiğim bir şey bulamadım. Bir PDF ayırıcı olarak başlayan bu proje, ekosistemin eksik olduğunu düşündüğüm bir şeye dönüştü. Paket, üretimde güvenebileceğiniz tam bir test seti ile birlikte gelir.

Eğer mevcut PDF’ler üzerinde çalışıyorsanız, belgeleri birleştirme veya ayırma, filigran ekleme, şifreleme veya web için optimize etme gibi işlemler yapmak istiyorsanız, denemeye değer. Tüm işlem listelemeleri README‘de mevcuttur.

→ GitHub · Packagist

Paketi aktif bir şekilde geliştirmeye devam ediyorum, bu nedenle geri bildirim ve sorunlarınızı bekliyorum.