Symfony geliştirici kılavuzu

Bir bakışta

Symfony paketi hizmetleri merkeze alır. PdfFactory bileşenini enjekte edin, her PDF belgesi için create() çağırın ve eşzamansız oluşturma için Messenger oluşturucularını kullanın. Her çağrı yeni bir belge döndürdüğünden, fabrikayı kapsayıcı hizmeti olarak tutabilirsiniz.

Bu kılavuzu, nextpdf/symfony için denetleyiciler, hizmetler, Messenger işleyicileri veya paket düzeyinde genişletme noktaları tasarlarken kullanın.

Mimari sınırlar

Katman	Sahibi	Sorumluluk	Buraya koymayın
Controller	Uygulama	İsteği yetkilendirin, girdileri toplayın ve PdfResponse döndürün.	Birden çok kullanım durumu arasında paylaşılan PDF yerleşimi.
Uygulama hizmeti	Uygulama	Etki alanı verilerini yükleyin ve bir oluşturucu seçin.	Symfony kapsayıcısının derleyici mantığı.
Oluşturucu hizmeti	Uygulama	Eşzamanlı veya kuyruğa alınmış belge oluşturma için PdfBuilderInterface arabirimini uygulayın.	İstek nesneleri, varlık yöneticileri veya serileştirilemeyen bağlamlar.
Symfony paketi	nextpdf/symfony	Hizmetleri, yapılandırma ağacını, isteğe bağlı genişletme geçişini, yanıt yardımcılarını ve Messenger veri aktarım nesnelerini (DTO) kaydeder.	Kiracıya özgü depolama ilkesi.
Çekirdek motor	nextpdf/nextpdf	Belgeyi oluşturun ve serileştirin.	Symfony yanıtı veya Messenger davranışı.

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

Aşama	Davranış	Geliştirici eylemi
Paket önyüklemesi	NextPdfBundle::build() isteğe bağlı genişletme algılamasını kaydeder.	Symfony’nin paketi keşfetmesine izin verin veya paketi bundles.php içinde kaydedin.
Yapılandırmayı yükleme	NextPdfExtension::load(), nextpdf: yapılandırmasını işler ve hizmet tanımlarını yükler.	Yapılandırmayı açık ve ortama duyarlı tutun.
Fabrika kullanımı	PdfFactory::create() yeni, yapılandırılmış bir belge döndürür.	Belgeleri hizmetlerde saklamayın.
Denetleyici çıktısı	PdfResponse tamamlanmış bir belgeyi bir yanıta dönüştürür.	Başlıkları el ile birleştirmek yerine yardımcıyı kullanın.
Messenger gönderimi	GeneratePdfMessage oluşturucu sınıfını, çıktı yolunu ve serileştirilebilir bağlamı taşır.	Bağlamı asgari düzeyde tutun ve skaler değerlerle sınırlayın.
İleti işleme	GeneratePdfHandler oluşturucuyu bir hizmet konumlandırıcıdan çözer ve belgeyi kaydeder.	Oluşturucuları belirlenimci ve idempotent olacak şekilde tasarlayın.

Önerilen uygulama yapısı

Yol	Amaç
src/Pdf/Builder/*	Şu arabirimi uygulayan hizmetler: PdfBuilderInterface.
src/Pdf/Data/*	Oluşturucu bağlamı olarak kullanılan küçük DTO’lar veya diziler.
src/Pdf/Storage/*	Depolama kökü seçimi ve çıktı dosya adı ilkesi.
src/Controller/*	Eşzamanlı yanıt giriş noktaları.
tests/Pdf/*	Oluşturucu, yanıt, Messenger ve yapılandırma testleri.

Statik yardımcı işlevler yerine oluşturucu hizmetlerini tercih edin. Bunları etiketlemek, dekore etmek, test etmek ve Messenger’dan kullanmak kolaydır.

<?php

namespace App\Pdf\Builder;

use NextPDF\Core\Document;
use NextPDF\Symfony\Message\PdfBuilderInterface;

final readonly class InvoicePdfBuilder implements PdfBuilderInterface
{
    public function build(Document $document, array $context): Document
    {
        $document->setTitle((string) $context['title'])
            ->addPage()
            ->writeHtml((string) $context['html']);

        return $document;
    }
}

Eşzamanlı yanıt deseni

<?php

namespace App\Controller;

use App\Pdf\Builder\InvoicePdfBuilder;
use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;

final readonly class InvoiceController
{
    public function __invoke(
        PdfFactory $factory,
        InvoicePdfBuilder $builder,
    ) {
        $document = $builder->build($factory->create(), [
            'title' => 'Invoice 1234',
            'html' => '<h1>Invoice 1234</h1>',
        ]);

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

Denetleyici bağlamını küçük tutun. Bir oluşturucunun çok sayıda etki alanı nesnesine ihtiyacı olduğunda, düzenleme işini bir uygulama hizmetine taşıyın ve oluşturucuya bir DTO veya normalleştirilmiş bir dizi geçirin.

Messenger deseni

GeneratePdfMessage gönderilmeden önce oluşturucu sınıfını ve çıktı yolunu doğrular. İşleyici, çalışma sırasında yolu yeniden doğrular.

<?php

use App\Pdf\Builder\InvoicePdfBuilder;
use NextPDF\Symfony\Message\GeneratePdfMessage;

$bus->dispatch(new GeneratePdfMessage(
    builderClass: InvoicePdfBuilder::class,
    outputPath: $projectDir . '/var/pdfs/invoice-1234.pdf',
    builderContext: [
        'title' => 'Invoice 1234',
        'html' => '<h1>Invoice 1234</h1>',
    ],
));

Doctrine varlıklarını, açık akışları, closure’ları, istek nesnelerini veya hizmet nesnelerini builderContext içine koymayın.

Genişletme noktaları

Genişletme noktası	Şunun için kullanın	Kısıtlama
PdfFactory hizmet dekorasyonu	Belgeler denetleyicilere ulaşmadan önce uygulama varsayılanlarının uygulanması.	Yeni belge anlamını korumalıdır.
PdfBuilderInterface	Kuyruğa alınmış veya yeniden kullanılabilir belge oluşturucularının tanımlanması.	Bir Document döndürmelidir.
OptionalExtensionPass	İsteğe bağlı Artisan veya Premium özelliklerinin derleme zamanında etkinleştirilmesi.	Kullanılabilirlik, istek durumuna değil kapsayıcı derleme durumuna bağlıdır.
Symfony yapılandırma ağacı	Varsayılanlar, PDF/A, işleyici (renderer) ayarları, imza, zaman damgalama yetkilisi (TSA) ve Messenger.	Geçersiz yapılandırma, kapsayıcı derlemesini başarısız kılmalıdır.
GeneratePdfHandler hizmet bağlama	Kuyruğa alınmış iletilerden hangi oluşturuculara erişilebileceğinin kısıtlanması.	Hizmet konumlandırıcı yalnızca onaylanmış oluşturucu hizmetlerini açığa çıkarmalıdır.

Geliştirme iş akışı

1. Belirlenimci girdiye sahip bir oluşturucu hizmeti ekleyin.
2. Bir denetleyicide veya hizmette PdfFactory::create() kullanın.
3. Dosya adı, içerik türü ve başlıklar için bir yanıt testi ekleyin.
4. Aynı belgenin eşzamansız olarak oluşturulması gerektiğinde oluşturucuyu Messenger ile kaydedin.
5. Sınıf adı, çıktı yolu ve bağlam biçimi için geçersiz ileti testleri ekleyin.
6. En küçük ve üretim yapılandırmasıyla bir kapsayıcı derleme testi ekleyin.
7. İşleme süresini ve belleği, üretimdekiyle aynı PHP ayarları altında ölçün.

Hata işleme

Hata	Nerede işlenmelidir	Önerilen yanıt
Geçersiz yapılandırma	Kapsayıcı derlemesi.	Dağıtımı, trafik uygulamaya ulaşmadan önce başarısız kılın.
Eksik oluşturucu hizmeti	Messenger işleyici testleri ve hizmet etiketleri.	İletinin başarısız olmasını sağlayın ve sorumlu ekibi uyarın.
Güvenli olmayan çıktı yolu	İleti yapıcısı ve depolama ilkesi.	Gönderimden önce reddedin; işleyici doğrulamasını derinlemesine savunma olarak tutun.
İsteğe bağlı genişletme kullanılamıyor	Derleyici geçişi ve fabrika davranışı.	İsteğe bağlı özelliği devre dışı bırakın veya kurulum gereksinimini açıkça belirtin.
Hizmet dönüşümü veya işleme hatası	Oluşturucu sınırı.	Kullanım durumunda belgelenmiş bir geri dönüş yoksa güvenli şekilde başarısız olun.

Güvenli varsayılanlar

Konu	Varsayılan	Ne zaman geçersiz kılınmalı
Fabrika ömrü	Kapsayıcı hizmeti.	Bunu koruyun; fabrika yeni belgeler oluşturduğundan güvenlidir.
Belge ömrü	Tek bir iş birimi.	İstekler veya iletiler arasında asla paylaşmayın.
Çıktı yolu doğrulaması	İleti yapıcısı ve işleyici.	Uygulama kodunda kiracı veya depolama kökü kısıtlamaları ekleyin.
Yanıt dosya adı	document.pdf.	Temizlenmiş iş tanımlayıcılarıyla geçersiz kılın.
Messenger aktarımı	async.	PDF işi ağır olduğunda özel bir aktarım kullanın.

Test denetim listesi

• Kapsayıcı testleri, paketi en küçük ve üretim yapılandırmasıyla derler.
• Yanıt testleri, güvenlik başlıklarını ve dosya adı işlemeyi doğrular.
• Messenger testleri, geçersiz yolların ve geçersiz oluşturucu sınıf adlarının gönderimden önce başarısız olduğunu doğrular.
• İşleyici testleri, gerçek bir oluşturucu hizmeti ve geçici bir çıktı dizini kullanır.
• Oluşturucu testleri, temsili bir belgeyi işler ve onu üretim benzeri dosya sistemi izinleri altında kaydeder.
• İsteğe bağlı genişletme testleri, Artisan’ın kullanılamaması, Premium’un kullanılamaması ve yapılandırılmış PDF/A profili davranışını kapsar.