Laravel geliştirici kılavuzu

Bir bakışta

Laravel paketi, çekirdek belge yaşam döngüsünü değiştirmeden NextPDF’i Laravel kurallarıyla uyumlu hale getirir. Paylaşılan kayıt defterleri ve fabrikalar kapsayıcının sahipliğindedir. Her PDF belgesi tek kullanımlıktır; bu nedenle belgeyi bir kez oluşturmalı, döndürmeli, akışa almalı veya kaydetmelisiniz.

Uygulama hizmetleri, kuyruk işleri, yanıt akışları veya nextpdf/laravel için test kapsamı tasarlarken bu kılavuzu kullanın.

Mimari sınır

Katman	Sahibi	Sorumluluk	Buraya koymayın
Controller	Uygulama	İsteği yetkilendirin, bir belge oluşturucu seçin ve bir yanıt döndürün.	Birden çok kullanım senaryosunda paylaşılan PDF yerleşim kuralları.
Uygulama hizmeti	Uygulama	Etki alanı verilerini toplayın ve belge oluşturma kodunu çağırın.	Kapsayıcı önyükleme mantığı veya paket yapılandırması.
Belge oluşturucu	Uygulama	Etki alanı verilerini NextPDF belge çağrılarına çevirin.	İstek nesneleri, Eloquent sorgu mantığı veya kuyruk aktarım ayrıntıları.
Laravel entegrasyonu	nextpdf/laravel	Fabrikaları, kayıt defterlerini, imzalayıcıyı, TSA istemcisini, cepheyi, yanıtları ve kuyruk işini bağlayın.	İşletmeye özgü depolama yolları veya kiracı ilkesi.
Çekirdek motor	nextpdf/nextpdf	PDF’yi oluşturun ve serileştirin.	Laravel yanıtı, kuyruk veya dosya sistemi ilkesi.

Çalışma zamanı yaşam döngüsü

Aşama	Davranış	Geliştirici eylemi
Hizmet sağlayıcı kaydı	NextPdfServiceProvider::register() paylaşılan kayıt defterlerini, belge fabrikasını, belge bağlamasını, HTTP istemcisini, zaman damgası yetkilisi (TSA) istemcisini, imzalayıcıyı ve isteğe bağlı e-fatura sözleşmelerini kaydeder.	Üretime almadan önce config/nextpdf.php dosyasını yayımlayıp gözden geçirin.
Belge çözümleme	Hem Pdf cephesi hem de PdfDocumentInterface bağlaması, DocumentFactoryInterface aracılığıyla yeni bir belge çözer.	Her istek, komut veya kuyruğa alınmış iş için belgeyi bir kez çözün.
Yazım	Uygulama kodu, çekirdek belge API’lerini cephe veya enjekte edilmiş belge üzerinden çağırır.	Etki alanı verilerini çıkarma işini belge oluşturucunun dışında tutun.
Terminal çıktısı	PdfResponse HTTP çıktısı üretir veya belge diske kaydedilir.	Her belge için tek bir nihai çıktı yolu seçin.
Kuyruk yürütmesi	GeneratePdfJob belgeyi çalışanda yeniden oluşturur ve çıktı yolunu tekrar doğrular.	Skaler bağlam iletin ve geri çağırmaları bağımsız (idempotent) tutun.

Önerilen uygulama yapısı

Yol	Amaç
app/Pdf/Builders/*	Saf belge oluşturucular. Veri alır ve tamamlanmış bir belge döndürürler.
app/Pdf/Data/*	Önceden yetkilendirilmiş belge girdisini taşıyan küçük veri aktarım nesneleri (DTO’lar).
app/Services/*	Uygulama orkestrasyonu, sorgular, yetkilendirme devri ve depolama yolu seçimi.
app/Jobs/*	Uygulamanın adlandırılmış işlere ihtiyaç duyduğu durumlarda GeneratePdfJob çevresindeki isteğe bağlı sarmalayıcılar.
tests/Feature/Pdf/*	HTTP yanıtı, kuyruk gönderimi ve yetkilendirme testleri.
tests/Unit/Pdf/*	Küçük ve belirlenimci girdiyle oluşturucu testleri.

Oluşturucuları Laravel istek nesnelerinden bağımsız tutun. Bir oluşturucuyu aynı girdiyle bir controller’dan, komuttan, testten veya kuyruk çalışanından çağırabilir durumda olmalısınız.

<?php

namespace App\Pdf\Builders;

use App\Pdf\Data\InvoicePdfData;
use NextPDF\Contracts\PdfDocumentInterface;

final readonly class InvoicePdfBuilder
{
    public function build(PdfDocumentInterface $pdf, InvoicePdfData $data): PdfDocumentInterface
    {
        $pdf->setTitle($data->title)
            ->addPage()
            ->setFont('dejavusans', '', 12)
            ->writeHtml($data->html);

        return $pdf;
    }
}

Eşzamanlı yanıt deseni

PDF akışı uygulama mantığının bir parçası olduğunda kurucu enjeksiyonunu kullanın. Cepheyi yalnızca statik biçimin daha kolay okunduğu kısa controller akışlarında tercih edin.

<?php

namespace App\Http\Controllers;

use App\Pdf\Builders\InvoicePdfBuilder;
use App\Pdf\Data\InvoicePdfData;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

final readonly class DownloadInvoiceController
{
    public function __invoke(
        PdfDocumentInterface $pdf,
        InvoicePdfBuilder $builder,
    ) {
        $document = $builder->build(
            $pdf,
            InvoicePdfData::fromInvoiceId(1234),
        );

        return PdfResponse::download($document, 'invoice-1234.pdf');
    }
}

Yanıt yardımcıları, Laravel yanıtını oluşturmadan önce belge baytlarını somutlaştırır. Bunlar yanıt yardımcısıdır; arka plan işleyicisi değildir.

Kuyruk deseni

GeneratePdfJob, çağrılabilir bir oluşturucu ve bir çıktı yolu kabul eder. İş, güvenli olmayan yolları çalışma zamanında doğrular. Uygulama kodu yine de gönderimden önce kiracı açısından güvenli bir depolama kökü seçmelidir.

<?php

use App\Pdf\Builders\QueuedInvoiceBuilder;
use NextPDF\Laravel\Jobs\GeneratePdfJob;

GeneratePdfJob::dispatch(
    outputPath: storage_path('app/pdfs/invoice-1234.pdf'),
    builder: [QueuedInvoiceBuilder::class, 'build'],
)->onQueue(config('nextpdf.queue.queue', 'pdf'));

Kuyruk geri çağırmalarını küçük tutun. Karmaşık kapanışları (closure) kuyruk yükünde saklamak yerine kalıcı durumu bir uygulama iş dinleyicisi üzerinden yazmayı tercih edin.

Genişletme noktaları

Genişletme noktası	Şunun için kullanın	Kısıt
PdfDocumentInterface bağlaması	Uygulama genelindeki varsayılanlar için belge oluşturmayı değiştirin veya dekore edin.	Yeni bir belge örneği döndürmelidir.
DocumentFactoryInterface	Hizmetlerde ve testlerde yeni belgeleri açıkça oluşturun.	Döndürülen belgeleri önbelleğe almayın.
config/nextpdf.php	Varsayılanlar, kuyruk ayarları, Chrome işleyici ayarları, imzalama kancaları, TSA, OCSP önbelleği.	Ortam değişkenlerini istek girdisi olarak değil, dağıtım yapılandırması olarak ele alın.
GeneratePdfJob oluşturucusu	Belgeleri eşzamansız olarak oluşturun.	Çağrılabilir değer, Laravel’in kuyruk aktarımı tarafından serileştirilebilir olmalıdır.
Başarı/başarısızlık geri çağırmaları	Oluşturma sonrası bildirim veya temizleme.	Geri çağırmaları bağımsız (idempotent) ve yan etkilerin farkında tutun.
İsteğe bağlı Premium sözleşmeleri	E-fatura gömücüsü, doğrulayıcısı, profili ve Schematron çalıştırıcısı.	Yalnızca isteğe bağlı paketin kurulu ve lisanslı olduğu yerde çözün.

Geliştirme iş akışı

1. İlk belgeyi bir controller’da veya özellik testinde eşzamanlı olarak oluşturun.
2. Yerleşim kodunu app/Pdf/Builders altındaki bir oluşturucu sınıfına taşıyın.
3. Sorgu ve yetkilendirme mantığını bir uygulama hizmetine taşıyın.
4. Başlıklar ve dosya adları için PdfResponse testleri ekleyin.
5. Yavaş veya yüksek hacimli oluşturma işlemini GeneratePdfJob öğesine taşıyın.
6. Serileştirilmiş bağlam, çıktı yolu ilkesi ve başarısızlık işleme davranışı için kuyruk testleri ekleyin.
7. Belleği ve işleme süresini temsili üretim verisiyle ölçün.

Başarısızlık işleme

Başarısızlık	Nerede işlenmelidir	Önerilen yanıt
Geçersiz istek veya yetkisiz belge	Controller veya ilke.	Uygulamanın olağan yetkilendirme veya doğrulama yanıtını döndürün.
Eksik yazı tipi veya geçersiz görüntü	Oluşturucu testi ve uygulama günlüklemesi.	İsteği veya işi başarısız kılın; kısmi PDF’ler yayımlamayın.
Güvenli olmayan çıktı yolu	Uygulama depolama hizmeti ve GeneratePdfJob.	Gönderimden önce reddedin ve derinlemesine savunma için çalışan tarafındaki doğrulamaya da güvenin.
İmzalama veya TSA başarısızlığı	İmzalama hizmeti sınırı.	Belgenin imzasız bırakılıp bırakılamayacağına karar verin; düzenlemeye tabi belgelerde varsayılan olarak güvenli kapanışı (fail closed) seçin.
Kuyruk zaman aşımı	Kuyruk çalışanı yapılandırması ve gözlemlenebilirlik.	Yalnızca oluşturucu belirlenimciyse ve çıktı yolunun üzerine yazmak güvenliyse yeniden deneyin.

Güvenli varsayılanlar

Husus	Varsayılan	Ne zaman geçersiz kılmalı
Kuyruk adı	pdf	Oluşturma, kullanıcıya yönelik işlerle rekabet ettiğinde özel bir kuyruk kullanın.
İş zaman aşımı	120 saniye	Yalnızca belge boyutunu ve çalışan kapasitesini ölçtükten sonra artırın.
Yanıt dosya adı	document.pdf	Temizlenmiş işletme tanımlayıcılarını kullanın.
Yazı tipi kayıt defteri	Paylaşılandır ve ısınmadan sonra kilitlenir.	Sık kullanılan yollarda kullanılan yazı tipleri için preload_fonts ekleyin.
Görüntü kayıt defteri	Paylaşılan, sınırlı önbellek.	Bellek kısıtlı çalışanlar için image_cache_mb değerini düşürün.
Akışa alınan yanıt parçalaması	64 KB parçalar.	Parça sınırlarına bağımlı olmayın; bunlar bir çıktı ayrıntısıdır.

Test denetim listesi

• Controller testleri Content-Type, Content-Disposition ve savunmacı başlıkları doğrular.
• Oluşturucu testleri belirlenimci DTO’lar kullanır ve veritabanını sorgulamaz.
• Kuyruk testleri, oluşturucunun yeni bir belge aldığını doğrular.
• Yol testleri dizin geçişini, akış sarmalayıcısını, boş baytı ve .pdf dışı reddetmeyi kapsar.
• Çalışan testleri, temsili belgeleri üretimdekiyle aynı bellek sınırı altında işler.
• İsteğe bağlı imzalama testleri eksik sertifikayı, geçersiz parolayı, TSA kullanılamamasını ve yapılandırılmış imza düzeyini kapsar.