Symfony API başvuru kılavuzu

Bir bakışta

Symfony paketi; paket kaydı, yapılandırma ağacı, yeni belgeler için enjekte edilebilir fabrika, Köprü Metni Aktarım Protokolü (HTTP) yanıt yardımcıları ve asenkron üretim için Messenger türleri sunar. Uygulama kodunun büyük bölümü yalnızca iki sembol kullanır: belge oluşturmak için enjekte ettiğiniz PdfFactory hizmeti — bununla bir Document oluşturursunuz — ve bu belgeyi güvenli bir HTTP yanıtına dönüştüren PdfResponse yardımcısı. Geri kalan semboller (paket, uzantı, derleyici geçişi, yapılandırma ağacı, Messenger veri aktarım nesnesi (DTO) ve işleyici), bir kez yapılandırdığınız veya çerçevenin sizin yerinize yönettiği bağlantı katmanıdır.

Buradan başlayın: NextPDF\Symfony\Service\PdfFactory hizmetini enjekte edin, create() çağrısıyla yeni bir Document elde edin ve bunu NextPDF\Symfony\Http\PdfResponse::download() ile döndürün. İlk örnek bu akışı gösterir.

Yaygın görevler

En yaygın görevler için bu üç çalıştırılabilir kod parçasını kullanın. Her kod parçası yalnızca aşağıdaki tablolarda belgelenmiş doğrulanmış sembolleri kullanır.

Bir denetleyiciden Taşınabilir Belge Biçimi (PDF) indirme yanıtı döndürün: fabrikayı enjekte edin, bir belge oluşturun ve bunu yanıt yardımcısına iletin:

<?php

declare(strict_types=1);

namespace App\Controller;

use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class InvoiceController
{
    #[Route('/invoice/{number}', name: 'invoice_pdf')]
    public function download(PdfFactory $pdf, string $number): Response
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, "Invoice #{$number}");

        return PdfResponse::download($doc, "invoice-{$number}.pdf");
    }
}

Ne yapar: PdfFactory::create(), yeni ve önceden yapılandırılmış bir Document döndürür. PdfResponse::download(), bunu Content-Type: application/pdf, ek (attachment) disposition’ı ve paketin sabit güvenlik üst bilgileriyle birlikte gönderir.

En yüksek bellek kullanımını düşük tutmak için büyük bir PDF’yi akış olarak gönderin: akış yardımcısını kullanın ve bir StreamedResponse döndürün:

<?php

declare(strict_types=1);

namespace App\Controller;

use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;
use Symfony\Component\HttpFoundation\StreamedResponse;
use Symfony\Component\Routing\Attribute\Route;

final class ReportController
{
    #[Route('/report', name: 'report_pdf')]
    public function report(PdfFactory $pdf): StreamedResponse
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, 'Annual report');

        return PdfResponse::streamDownload($doc, 'annual-report.pdf');
    }
}

Ne yapar: PdfResponse::streamDownload(), oluşturulmuş PDF’yi parçalar hâlinde gönderir ve Content-Length başlığını atlar; satır içi eşdeğeri için streamInline() kullanın.

Bir PDF’yi asenkron üretim için kuyruğa gönderin: işlemenin bir işçi (worker) üzerinde çalışması için bir Messenger taşıyıcısına GeneratePdfMessage gönderin:

<?php

declare(strict_types=1);

namespace App\Controller;

use App\Pdf\InvoicePdfBuilder;
use NextPDF\Symfony\Message\GeneratePdfMessage;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Messenger\MessageBusInterface;
use Symfony\Component\Routing\Attribute\Route;

final class QueueController
{
    #[Route('/invoice/{id}/queue', name: 'invoice_queue')]
    public function queue(MessageBusInterface $bus, int $id): Response
    {
        $bus->dispatch(new GeneratePdfMessage(
            builderClass: InvoicePdfBuilder::class,
            outputPath: '/var/storage/invoices/' . $id . '.pdf',
            builderContext: ['invoice_id' => $id],
        ));

        return new Response('PDF generation queued.', 202);
    }
}

Ne yapar: DTO, bir oluşturucu sınıf dizesi (class-string) ve doğrulanmış bir çıktı yolu taşır. İşleyici, oluşturucuyu çözümler, belgeyi oluşturur ve işçi (worker) üzerinde kaydeder. Oluşturucu sınıfı PdfBuilderInterface arayüzünü uygular ve bir hizmet konumlandırıcısına (service locator) kaydedilir (konumlandırıcı ve işçi bağlantısı için Symfony hızlı başlangıç kılavuzuna bakın).

Fabrika

Yeni belgeler üreten enjekte edilebilir hizmetin tam yapıcı imzası ve create() sözleşmesi için bu tabloyu kullanın.

Sembol	Parametreler	Varsayılan davranış	Döndürür	İstisna veya başarısızlık durumu	Notlar
new PdfFactory(DocumentFactoryInterface $factory, array $defaults, ?string $pdfa, array $artisanConfig)	factory: çekirdek fabrika; defaults: oluşturucu, yazar, dil, kenar boşlukları; pdfa: isteğe bağlı PDF/A profili; artisanConfig: isteğe bağlı Chrome işleyici yapılandırması.	Varsayılanlar yalnızca yapılandırıldığında uygulanır.	PdfFactory	Konteyner bağlantı hataları.	Hizmet tekil (singleton) olabilir, çünkü create() yeni bir belge döndürür.
PdfFactory::create()	yok.	Oluşturucuyu ve dili uygular; yazarı yalnızca boş olmadığında uygular; PDF/A ve Artisan yapılandırmasını yalnızca kullanılabilir olduğunda uygular.	NextPDF\Core\Document	Çekirdek yapılandırma hataları.	Her istek, komut veya mesaj başına bir kez kullanın.
PdfFactory::setArtisanAvailable(bool $available)	available: derleme zamanı kullanılabilirlik bayrağı.	Derleyici geçişi etkinleştirene kadar devre dışıdır.	void	Beklenen yok.	İsteğe bağlı uzantı derleyici geçişi tarafından çağrılan dahili kanca (hook).
PdfFactory::setProAvailable(bool $available)	available: derleme zamanı kullanılabilirlik bayrağı.	Derleyici geçişi etkinleştirene kadar devre dışıdır.	void	Beklenen yok.	Premium kullanılabilirliği için dahili kanca (hook).

Paket, uzantı ve yapılandırma

Bağlantı katmanı için ilk tabloyu kullanın: paket kaydı, nextpdf yapılandırma ağacı ve isteğe bağlı uzantı algılaması. İkinci tablo yapılandırma anahtarlarını listeler.

Sembol	Parametreler	Varsayılan davranış	Döndürür	İstisna veya başarısızlık durumu	Notlar
NextPdfBundle::build(ContainerBuilder $container)	Symfony konteyner oluşturucusu.	Üst sınıfın build yöntemini çağırır ve OptionalExtensionPass sınıfını kaydeder.	void	Derleyici geçişi kayıt hataları.	İsteğe bağlı Artisan ve Premium özellik algılamasını etkinleştirir.
NextPdfBundle::getPath()	yok.	Paket kök yolunu döndürür.	string	Beklenen yok.	Symfony paket keşfi ve kaynak yükleme tarafından kullanılır.
NextPdfExtension::load(array $configs, ContainerBuilder $container)	Kullanıcı yapılandırma dizileri ve konteyner oluşturucusu.	Sağlanan nextpdf yapılandırmasını işler, çözümlenmiş parametreleri saklar, hizmet tanımlarını yükler ve gerekli uzantıları denetler.	void	Yapılandırma doğrulama, hizmet yükleme veya eksik uzantı hataları.	Gerekli uzantılar mbstring ve zlib uzantılarıdır.
NextPdfExtension::getAlias()	yok.	Kök yapılandırma anahtarı olarak nextpdf kullanır.	string	Beklenen yok.	Paketi nextpdf: altında yapılandırın.
Configuration::getConfigTreeBuilder()	yok.	Doğrulanmış nextpdf yapılandırma ağacını tanımlar.	TreeBuilder	Symfony yapılandırma tanımlama hataları.	Uygulanabilir olduğunda Laravel yapılandırma biçimini yansıtır.
OptionalExtensionPass::process(ContainerBuilder $container)	Symfony konteyner oluşturucusu.	İsteğe bağlı Artisan ve Premium hizmetlerini algılar ve fabrika kullanılabilirlik bayraklarını değiştirir.	void	Derleyici geçişi bağlantı hataları.	Konteyner derlemesi sırasında çalışır.

Yapılandırma anahtarı	Tür	Varsayılan davranış	Notlar
page_format	enum	A4; izin verilen değerler A3, A5, Letter, Legal ve Tabloid değerlerini içerir.	Varsayılan belge oluşturmaya uygulanır.
orientation	enum	P; izin verilen değerler P ve L değerleridir.	Bir sayfa farklı bir yönlendirmeye ihtiyaç duyduğunda açık belge çağrıları kullanın.
unit	enum	mm; izin verilen değerler pt, mm, cm ve in değerleridir.	Çerçeve varsayılanlarını çekirdek birimlerle hizalı tutar.
pdfa	`string	null`	null; izin verilen değerler 4, 4e ve 4f değerleridir.
fonts_path / cache_path	string	Proje yazı tipleri yolu ve çekirdek (kernel) önbellek yolu.	Her yolu, çalışma zamanı rolüne göre okunabilir veya yazılabilir tutun.
signature.*	array	Varsayılan olarak devre dışıdır; imza düzeyi B-B.	Sertifika, anahtar, parola, ek sertifikalar ve düzey sağlar.
tsa.*	array	Tekdüzen Kaynak Konumlandırıcı (URL) null olduğunda devre dışıdır; zaman aşımı varsayılan olarak 30 saniyedir.	Kimlik bilgilerini, karşılıklı Aktarım Katmanı Güvenliği (mTLS) dosyalarını, ortak anahtar sabitlemelerini (pin) ve HTTP politikasını destekler.
ocsp_cache.*	array	86400 saniyelik bir yaşam süresi (TTL) ile etkindir.	Kullanılabilir olduğunda doğrulama ve uzun vadeli imza akışları tarafından kullanılır.
messenger.*	array	Taşıyıcı async, zaman aşımı 120, yeniden denemeler 3.	Asenkron üretim iş akışları tarafından kullanılır.
artisan.*	array	Chrome işleyici, yapılandırılıp kurulmadığı sürece devre dışıdır.	İsteğe bağlı işleyici kullanılabilir olduğunda ChromeRendererConfig ile eşlenir.
defaults.*	array	Oluşturucu NextPDF, yazar boş, dil en, varsayılan kenar boşlukları ve yazı tipi.	Bunu PdfFactory::create() uygular.

HTTP yanıtları

Görüntüleme moduna ve arabelleğe almaya göre bir yanıt yardımcısı seçmek için bu tabloyu kullanın: satır içi görüntüleme veya indirme, arabelleğe alınmış ya da akışlı. Tablo ayrıca dosya adı ve üst bilgi davranışını da gösterir.

Sembol	Parametreler	Varsayılan davranış	Döndürür	İstisna veya başarısızlık durumu	Notlar
PdfResponse::inline(Document $document, string $filename = 'document.pdf')	document: oluşturulmuş belge; filename: yanıt dosya adı.	Eksik olduğunda .pdf ekler.	Symfony\Component\HttpFoundation\Response	Çekirdek serileştirme hataları.	PDF içerik türünü ve koruyucu üst bilgileri ayarlar.
PdfResponse::download(Document $document, string $filename = 'document.pdf')	Tıpkı inline gibi; disposition’ı ek (attachment) olarak ayarlanır.	Tarayıcı indirme yanıtı.	Response	Tıpkı inline gibi.	Doğrudan indirmeler için kullanın.
PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')	Tıpkı inline gibi.	Oluşturulmuş PDF baytlarını parçalar hâlinde gönderir.	StreamedResponse	Tıpkı inline gibi.	Belgenin oluşturulmasını ortadan kaldırmaz.
PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')	Tıpkı streamInline gibi; disposition’ı ek (attachment) olarak ayarlanır.	Akışlı indirme yanıtı.	StreamedResponse	Tıpkı streamInline gibi.	İşlemeden önce çıktı boyutu politikasını uygulayın.

Messenger

Asenkron yol için bu tabloyu kullanın: gönderdiğiniz mesaj DTO’su, uyguladığınız oluşturucu arayüzü ve işçi (worker) üzerinde çalışan işleyici.

Sembol	Parametreler	Varsayılan davranış	Döndürür	İstisna veya başarısızlık durumu	Notlar
new GeneratePdfMessage(string $builderClass, string $outputPath, array $builderContext = [])	builderClass: PdfBuilderInterface arayüzünü uygulayan sınıf dizesi (class-string); outputPath: hedef .pdf; builderContext: serileştirilebilir veri.	Boş bağlam dizisi.	Mesaj DTO’su.	InvalidArgumentException: geçersiz tam nitelikli sınıf adı (FQCN), akış sarmalayıcısı, boş bayt, geçiş (traversal), boş yol veya .pdf olmayan hedef için fırlatılır.	Messenger taşıyıcıları kapanışları (closure) değil, veri taşır.
PdfBuilderInterface::build(Document $document, array $context): Document	document: yeni yapılandırılmış belge; context: serileştirilebilir mesaj verisi.	Mesaj değerinin ötesinde varsayılan bağlam yoktur.	Yapılandırılmış Document.	Oluşturucuya özgü istisnalar.	Oluşturucuları belirlenimci (deterministic) ve etkisiz (idempotent) yapın.
new GeneratePdfHandler(PdfFactory $pdfFactory, ContainerInterface $builderLocator)	PDF fabrikası ve etiketlenmiş oluşturucu hizmet konumlandırıcısı.	Yapım sırasında hiçbir belge oluşturulmaz.	GeneratePdfHandler	Konteyner bağlantı hataları.	Konumlandırıcı yalnızca PdfBuilderInterface uygulamalarını açığa çıkarmalıdır.
GeneratePdfHandler::__invoke(GeneratePdfMessage $message)	message: doğrulanmış mesaj DTO’su.	Oluşturucuyu konteynerden çözümler, belgeyi oluşturur ve kaydeder.	void	Eksik oluşturucu hizmeti, geçersiz oluşturucu sonucu, çekirdek yazma hataları.	Statik geri çağrılar yerine hizmet oluşturucularını tercih edin.

Geliştirme notları

• Bir Document nesnesini hizmet olarak saklamayın. PdfFactory nesnesini saklayın ve her iş birimi için create() çağrısını yapın.
• Yalnızca serileştirilebilir bağlamı kuyruğa alın. Açık akışları, kapanışları (closure) veya istek nesnelerini builderContext içine koymayın.
• Dağıtımda kiracıya özgü depolama kökleri olduğunda, DTO’nun sağladığından daha katı bir çıktı yolu politikası kullanın.