NextPDF Symfony hızlı başlangıç kılavuzu

Bir bakışta

Önce PdfFactory bağımlılığını enjekte edin, bir Document oluşturun ve bunu PdfResponse aracılığıyla döndürün. Arka planda oluşturma gerektiğinde, bir Messenger taşımasına GeneratePdfMessage gönderin.

Adım 1 — Bir denetleyicide PDF oluşturma

Önce NextPDF\Symfony\Service\PdfFactory bağımlılığını enjekte edin. Bu sınıfın create() yöntemi, yeni bir NextPDF\Core\Document döndürür. Oluşturan, yazar ve dil alanları için yapılandırdığınız varsayılan değerleri uygular. Belgeyi NextPDF\Symfony\Http\PdfResponse aracılığıyla döndürün.

src/Controller/InvoiceController.php

<?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->cell(0, 10, "Invoice #{$number}", newLine: true);
        $doc->cell(0, 10, 'Thank you for your business.');

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

PdfResponse::download(), bir Symfony\Component\HttpFoundation\Response döndürür. Content-Type: application/pdf üst bilgisini, bir attachment düzenini, Content-Length üst bilgisini ve paketin sabit güvenlik üst bilgilerini ayarlar. Symfony standart Response sınıfını ve üst bilgi modelini belgeler (https://symfony.com/doc/current/components/http_foundation.html).

Adım 2 — PDF’yi satır içi görüntüleme

Tarayıcının PDF’yi indirmek yerine görüntülemesini istediğinizde inline() yöntemini kullanın:

return PdfResponse::inline($doc, 'preview.pdf');

Düzen inline olarak değişir. Diğer tüm üst bilgiler aynı kalır.

Adım 3 — Büyük bir PDF’yi akışla aktarma

Büyük belgeler için akışlı varyantları kullanın. Bu varyantlar PDF’yi 64 KB’lik parçalar hâlinde gönderir; bu da tepe bellek kullanımını azaltır. Symfony\Component\HttpFoundation\StreamedResponse döndürür ve Content-Length üst bilgisini atlar.

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

Satır içi akış için streamInline() yöntemini kullanın. Symfony, StreamedResponse geri çağırma sözleşmesini belgeler; bu, çıktıyı boşaltan ve void döndüren çağrılabilir bir yapıdır (https://symfony.com/doc/current/components/http_foundation.html).

Adım 4 — PDF’yi eşzamansız oluşturma

Sisteminizde symfony/messenger kuruluysa, oluşturma işlemini istek iş parçacığının dışına taşıyabilirsiniz.

4a — Bir oluşturucu uygulama

Önce NextPDF\Symfony\Message\PdfBuilderInterface arabirimini uygulayın. İşleyici size yeni, önceden yapılandırılmış bir Document ve iletideki serileştirilebilir bağlamı sağlar.

src/Pdf/InvoicePdfBuilder.php

<?php

declare(strict_types=1);

namespace App\Pdf;

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

final class InvoicePdfBuilder implements PdfBuilderInterface
{
    public function build(Document $document, array $context): Document
    {
        $document->addPage();
        $document->setFont('dejavusans', '', 12);
        $document->cell(0, 10, 'Invoice #' . $context['invoice_id']);

        return $document;
    }
}

4b — Oluşturucuyu konumlandırıcıya kaydetme

İşleyici, oluşturucuları sınıf adıyla anahtarlanmış bir PHP Standart Önerisi 11 (PSR-11) hizmet konumlandırıcısından çözer. Yalnızca kayıtlı oluşturuculara erişilebilir. Oluşturucuyu config/services.yaml dosyasındaki bir konumlandırıcıya ekleyin:

services:
    App\Pdf\InvoicePdfBuilder: ~

    nextpdf.pdf_builder_locator:
        class: Symfony\Component\DependencyInjection\ServiceLocator
        arguments:
            - 'App\Pdf\InvoicePdfBuilder': '@App\Pdf\InvoicePdfBuilder'
        tags: ['container.service_locator']

    NextPDF\Symfony\Message\GeneratePdfHandler:
        arguments:
            $builderLocator: '@nextpdf.pdf_builder_locator'

İşleyici, oluşturucuyu sınıf dizesi kimliğiyle konumlandırıcıdan ister. PSR-11’de kapsayıcı tanımlayıcısı, bir girdiyi benzersiz biçimde tanımlayan dizedir (PSR-11 §1.1.2).

4c — İletiyi gönderme

Önce Symfony\Component\Messenger\MessageBusInterface bağımlılığını enjekte edin, ardından iletiyi gönderin:

src/Controller/ReportController.php

<?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 ReportController
{
    #[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);
    }
}

GeneratePdfMessage, readonly bir veri aktarım nesnesidir (DTO). Yapıcısı, boş olan, .pdf ile bitmeyen, dizin geçişi bölümleri içeren, akış sarmalayıcı şemaları kullanan veya null baytlar barındıran çıktı yollarını reddeder. Ayrıca builderClass değerinin söz dizimi açısından geçerli bir sınıf adı olmasını gerektirir. İşleyici, yazma işleminden önce çalışma zamanında çıktı yolunu yeniden doğrular. Bir yol gönderim sırasında güvenli ancak tüketim sırasında güvensizse, işleyici yine de onu reddeder. #[AsMessageHandler] özniteliği ve MessageBusInterface gönderim sözleşmesi, standart Symfony Messenger modelini izler (https://symfony.com/doc/current/messenger.html).

4d — İletiyi yönlendirme ve bir çalışan çalıştırma

Şimdi, config/packages/messenger.yaml dosyasında iletiyi bir taşımaya yönlendirin:

framework:
    messenger:
        transports:
            async: '%env(MESSENGER_TRANSPORT_DSN)%'
        routing:
            NextPDF\Symfony\Message\GeneratePdfMessage: async

Ardından bir çalışan çalıştırın:

php bin/console messenger:consume async

Çalıştığını doğrulama

php bin/console debug:container --tag=container.service_locator
php bin/console messenger:consume async --limit=1 -vv

İlk komut, oluşturucu konumlandırıcısının kayıtlı olduğunu doğrular. İkinci komut, kuyruğa alınmış bir iletiyi tüketir ve işleyicinin ilerleme çıktısını yazdırır.

Sonraki adımlar

• /integrations/symfony/configuration/ — varsayılan değerleri, yazı tiplerini ve belge hizmetini ayarlayın.
• /integrations/symfony/production-usage/ — çalışan güvenliğini ve yük altında akış davranışını inceleyin.
• /integrations/symfony/troubleshooting/ — yaygın önyükleme ve çalışma zamanı sorunlarını çözün.

Uygunluk

Her satır, bu sayfada yapılan normatif bir iddiayı temsil eder ve erişimi kısıtlı standart geliştirme kuruluşu (SDO) bütüncesinden gelen tam 64 karakterlik onaltılık bir reference_id değerine sabitlenmiştir. _sidecars/rag-citations.yaml, bütünce bildirimi ve erişim taşıması dâhil köken bilgilerini içerir.

Belirtim	Madde	reference_id	İddia
PSR-11	psr_11_container#1.1.2.p4		Kapsayıcı has()/get() tanımlayıcı sözleşmesi

Ayrıca bakınız

• /integrations/symfony/overview/ — yetenek özetini inceleyin.
• /integrations/symfony/install/ — paketi kurun ve kaydedin.
• /integrations/symfony/integration/ — uçtan uca bağlantı referansını inceleyin.