Denetleyicide oluşturulan PDF'i döndürme

Bir bakışta

Bir denetleyici eyleminde Taşınabilir Belge Biçimi (PDF) dosyası oluşturup bunu Köprü Metni Aktarım Protokolü (HTTP) yanıtı olarak döndürün. Her çerçeve tümleştirmesinde bir PdfResponse yardımcısı bulunur; bu yardımcı yanıt nesnesini oluşturur, Content-Type: application/pdf başlığını ayarlar, güvenlik başlıklarını ekler ve dosya adını temizler. Bu kılavuz, Laravel, Symfony ve CodeIgniter 4 için üç teslim kipini kapsar: satır içi önizleme, dosya indirme ve akışla teslim.

Denetleyici yolunun hazır olduğundan emin olmak için başlamadan önce şu ön koşulları denetleyin:

NextPDF core kurulu olmalıdır.
Bir çerçeve tümleştirmesi kurulu olmalı ve ona ait hizmet sağlayıcı, bundle veya hizmet bulunmuş olmalıdır. Başlamadan önce çerçevenizin kurulum sayfasında bulma işlemini doğrulayın.
Akış kipi ek paket gerektirmez. Her tümleştirme, arabelleğe alan varyantın yanı sıra akış varyantını da içerir.

Bu bir nasıl yapılır kılavuzudur. Çerçevenizde bir isteği denetleyiciye nasıl yönlendireceğinizi zaten bildiğiniz varsayılır. Her çerçevede ilk çalıştırılabilir örnek için Ayrıca bakın bölümünde bağlantısı verilen çerçeve hızlı başlangıç kılavuzunu okuyun.

Kurulum

Çerçeveniz için tümleştirmeyi kurun. Aşağıdaki komutlardan birini çalıştırın.

composer require nextpdf/laravel

composer require nextpdf/symfony

composer require nextpdf/codeigniter

Laravel için yapılandırmayı kurulumdan sonra yayımlayın.

php artisan vendor:publish --tag=nextpdf-config

Symfony, bundle’ı Flex aracılığıyla kaydeder; CodeIgniter ise hizmeti otomatik olarak bulur. Devam etmeden önce çerçevenizin kurulum sayfasında bulma işlemini doğrulayın.

Kavramsal genel bakış

Her çerçeve tümleştirmesi aynı üç parçalı yapıyı izler: yeni bir belge edinir, içeriği bu belgeye yazar ve onu HTTP yanıtı döndüren bir PdfResponse fabrikasına geçirirsiniz. Belge API’si (addPage(), cell(), setFont()) çekirdek motorun API yüzeyidir ve çerçeveler arasında aynıdır. Yanıt fabrikası yalnızca döndürdüğü yanıt sınıfı bakımından farklılık gösterir, çünkü her çerçevenin kendi HTTP yanıt türü vardır.

PdfResponse üç teslim kipi sunar. Satır içi kipi bir Content-Disposition: inline başlığı ayarlar; böylece tarayıcı PDF’yi bir görüntüleyici sekmesinde işler. İndirme kipi Content-Disposition: attachment başlığını ayarlar; böylece tarayıcı dosyayı kaydeder. Akış kipi, belgenin tamamını bellekte arabelleğe almak yerine PDF gövdesini sabit parçalar hâlinde gönderir. En yüksek bellek kullanımı, bilinen bir Content-Length değerinden daha önemli olduğunda büyük belgeler için bunu seçin.

Belgeyi çerçevenizin olağan çözümleme yoluyla alın:

Laravel — NextPDF\Contracts\DocumentFactoryInterface arabirimini kapsayıcıdan app(...) ile çözümleyin ve create() çağırın; bu, yeni bir NextPDF\Core\Document döndürür — PdfResponse fabrikalarının kabul ettiği somut tür.
Symfony — NextPDF\Symfony\Service\PdfFactory hizmetini enjekte edin ve create() çağırın; bu, yapılandırılmış belge varsayılanları halihazırda uygulanmış yeni bir NextPDF\Core\Document döndürür.
CodeIgniter 4 — Pdf kitaplığını Services::pdf() (veya pdf() yardımcısı) aracılığıyla çözümleyin veya pdf_document() aracılığıyla yalın bir belge edinin.

API yüzeyi

İlgi alanı	Laravel	Symfony	CodeIgniter 4
Yeni belge	`app(DocumentFactoryInterface::class)->create()`	`PdfFactory::create()`	`pdf_document()` / `Services::pdf()->document()`
Satır içi yanıt	`PdfResponse::inline($doc, $name)`	`PdfResponse::inline($doc, $name)`	`$pdf->inline($name)` / `PdfResponse::inline($doc, $name)`
İndirme yanıtı	`PdfResponse::download($doc, $name)`	`PdfResponse::download($doc, $name)`	`$pdf->download($name)` / `PdfResponse::download($doc, $name)`
Akışla satır içi	`PdfResponse::streamInline($doc, $name)`	`PdfResponse::streamInline($doc, $name)`	`PdfResponse::streamInline($doc, $name)`
Akışla indirme	`PdfResponse::streamDownload($doc, $name)`	`PdfResponse::streamDownload($doc, $name)`	`PdfResponse::streamDownload($doc, $name)`
Döndürülen tür	`Illuminate\Http\Response` (akış: `StreamedResponse`)	`Symfony\Component\HttpFoundation\Response` (akış: `StreamedResponse`)	`CodeIgniter\HTTP\DownloadResponse`

Laravel PdfResponse sınıfı NextPDF\Laravel\Http\PdfResponse konumunda, Symfony sınıfı NextPDF\Symfony\Http\PdfResponse konumunda ve CodeIgniter sınıfı NextPDF\CodeIgniter\Http\PdfResponse konumunda bulunur. Her tümleştirmenin güvenlik ve işletim sayfası, o paket için yanıt davranışının tamamını belgeler: başlık kümesi, disposition kuralları ve dosya adı temizleme. Bu sayfaların bağlantıları Ayrıca bakın bölümünde verilmiştir.

Kod örneği — hızlı başlangıç

Her çerçeve için en küçük indirme eylemi aşağıdadır. Belge çağrıları aynı çekirdek API yüzeyini kullanır. Yalnızca denetleyici iskeleti değişir.

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Illuminate\Http\Response;
use NextPDF\Contracts\DocumentFactoryInterface;
use NextPDF\Laravel\Http\PdfResponse;

final class ReportController extends Controller
{
    public function download(): Response
    {
        $document = app(DocumentFactoryInterface::class)->create();
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

        return PdfResponse::download($document, 'report.pdf');
    }
}

<?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 ReportController
{
    #[Route('/report', name: 'report_pdf')]
    public function download(PdfFactory $pdf): Response
    {
        $document = $pdf->create();
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

        return PdfResponse::download($document, 'report.pdf');
    }
}

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;
use NextPDF\CodeIgniter\Config\Services;

final class ReportController extends BaseController
{
    public function download(): DownloadResponse
    {
        $pdf = Services::pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, 'Monthly report');

        return $pdf->download('report.pdf');
    }
}

İndirmek yerine tarayıcıda önizleme yapmak için Laravel ve Symfony’de download(...) çağrısını inline(...) ile, CodeIgniter’da ise $pdf->inline('report.pdf') ile değiştirin. Disposition inline olarak değişir ve diğer tüm başlıklar aynı kalır.

Kod örneği — üretim

Bir üretim eylemi bağımlılıklarını enjekte eder, tümleştirmenin belgelediği en özgül özel durumu yakalar, izleme bilgisini sızdırmadan hata sınıfını günlüğe yazar ve tanımlanmış bir HTTP hatası döndürür. Aşağıdaki örnek Laravel yapıcı enjeksiyonunu kullanır. Symfony ve CodeIgniter karşılıkları aynı yapıyı izler ve her tümleştirmenin üretim kullanımı sayfasında yer alır.

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Illuminate\Http\Response;
use NextPDF\Contracts\DocumentFactoryInterface;
use NextPDF\Laravel\Http\PdfResponse;
use Psr\Log\LoggerInterface;
use Throwable;

final class InvoiceController extends Controller
{
    public function __construct(
        private readonly DocumentFactoryInterface $documents,
        private readonly LoggerInterface $logger,
    ) {}

    public function show(int $invoiceId): Response
    {
        try {
            $document = $this->documents->create();
            $document->addPage();
            $document->cell(0, 10, "Invoice #{$invoiceId}", newLine: true);

            return PdfResponse::download(
                $document,
                "invoice-{$invoiceId}.pdf",
            );
        } catch (Throwable $exception) {
            // Log the exception class, never the message or a stack trace,
            // so internal detail does not leak into the log sink.
            $this->logger->error('Invoice PDF generation failed', [
                'invoice_id' => $invoiceId,
                'exception'  => $exception::class,
            ]);

            return new Response('Could not generate the invoice PDF.', 500);
        }
    }
}

Her eylemde DocumentFactoryInterface arabirimini enjekte edin ve create() çağırın. Bu, yeni bir NextPDF\Core\Document döndürür — Laravel PdfResponse fabrikalarının kabul ettiği somut tür. Her istek için yeni bir belge çözümlemek, fabrikanın testlerde değiştirilebilir kalmasını sağlar. Tek bir uzun süre çalışan işçi sürecinde, birbiriyle ilgisiz iki belge için aynı denetleyici örneğini yeniden kullanmayın.

Çok büyük belgelerde en yüksek bellek kullanımını sınırlamak için arabelleğe alan fabrikayı akış sağlayan bir fabrikayla değiştirin. Akış varyantı bir StreamedResponse (Laravel ve Symfony) döndürür ve gövdeyi sabit parçalar hâlinde gönderir. Bu varyant, Content-Length başlığını kasıtlı olarak atlar; böylece indirme ilerleme çubukları ve uzunluğa duyarlı ara sunucular bilinen bir boyut görmez. Küçük ve gecikmeye duyarlı yanıtlar için arabelleğe alan download() / inline() yöntemlerini tercih edin.

$document = $this->documents->create();
// ... emit content onto $document ...
return PdfResponse::streamDownload($document, 'annual-report.pdf');

Sınır durumlar ve tuzaklar

Çağrı başına yeni belge. Üç tümleştirmenin tümünde belge fabrikadan üretilir ve her çözümlemede yenidir. Çözümlenmiş bir belgeyi mantıksal belgeler arasında veya uzun süre çalışan bir işçide istekler arasında önbelleğe almayın. Eski içerik durumu sonraki belgeye taşınır.
Boş dosya adı. Bir PdfResponse fabrikasına geçirilen boş dosya adı, boş bir disposition üretmek yerine varsayılan bir ada (document.pdf) döner. Açık ve anlamlı bir dosya adı geçirin.
ASCII dışı dosya adları. Laravel yanıtı, ASCII dışı adlar için otomatik olarak bir RFC 5987 filename*= parametresi ekler; ASCII adlar ise düz parametreyi kullanır. Dosya adını elle kodlamayın.
Arabelleğe alan bir ara sunucunun arkasındaki akış yanıtları. Gövdenin tamamını arabelleğe alan bir ara sunucu, akışın bellek avantajını ortadan kaldırır. Ara sunucuyu PDF yanıtlarını akışla iletecek biçimde yapılandırın veya o yolda arabelleğe alınmış bir yanıt kullanın.
Symfony akış geri çağırması. Akış sağlayan Symfony varyantı, geri çağırması çıktıyı boşaltan bir StreamedResponse döndürür. Yanıtı döndürdükten sonra yanıt gövdesine kendiniz yazmayın.

Başarım

Bir denetleyici içinde eşzamanlı oluşturma, PDF derlemesinin tamamı boyunca isteği engeller. Tek sayfalık bir belge genellikle tipik bir istek bütçesinin rahatça içinde kalır. Çok sayfalı veya toplu çıktı için, oluşturmayı kuyruğa alınmış bir işle istek iş parçacığından çıkarın — bkz. Kuyruğa alınmış bir işte PDF oluşturma. Akış varyantları, bilinmeyen bir Content-Length pahasına büyük belgelerde en yüksek bellek kullanımını azaltır. Bellek kısıtlı olduğunda ve ilerleme çubuğu gerekmediğinde bunları seçin.

Güvenlik notları

Tüm PdfResponse fabrikaları, her tümleştirmede sabit bir yanıt sıkılaştırma başlığı kümesi uygular ve indirme dosya adını temizler. Bu başlıkları kendiniz eklemeyin.
Doğrulanmamış kullanıcı girdisini, fabrikaya geçirdiğiniz bir dosya adına asla doğrudan eklemeyin. Denetiminizde olan bir değer geçirin ve ikinci bir katman olarak fabrikanın onu temizlemesine izin verin.
catch bloğunda, özel durum iletisini veya izlemesini değil; özel durum sınıfını ve bir ilişkilendirme tanımlayıcısını günlüğe yazın. Günlük havuzundaki ham izleme bilgisi bir bilgi sızıntısıdır.
Asla boş bir catch bloğu yazmayın. Buradaki her örnek günlüğe yazar ve tanımlı bir hata yanıtı döndürür.

Her tümleştirmenin güvenlik ve işletim sayfası, o tümleştirmenin tehdit modelini belgeler: başlık kümesi, dosya adı temizleme kuralları ve belge bağlama ömrü.

Uygunluk

Bu kılavuz hiçbir normatif standart iddiasında bulunmaz. Gösterilen her API çağrısı, adı geçen tümleştirmenin doğrulanmış genel yüzeyidir ve her paketin hızlı başlangıç ile üretim kullanımı sayfalarıyla çapraz denetlenmiştir. Ayrıca bakın bölümünde bağlantısı verilen üst kaynak niteliğindeki üretim kullanımı sayfaları, tümleştirmelerin dayandığı başlık anlambilimini ve kapsayıcı bağlama davranışını PSR alıntılarıyla birlikte belgeler. Bu Cookbook sayfası, kullanımı yeniden açıklar ve normatif alıntıları o sayfalara bırakır.

Ayrıca bakın

Kuyruğa alınmış bir işte PDF oluşturma — bu işi istek iş parçacığından çıkarın.
Laravel üretim kullanımı — DI ile bağlı denetleyici, başlık kümesi ve PSR-11 bağlama sözleşmesi.
Symfony hızlı başlangıç — denetleyici, satır içi, akış ve yanıt modeli.
CodeIgniter hızlı başlangıç — Services::pdf(), pdf() yardımcısı ve PdfResponse.
Bir tümleştirme seçme — doğru çerçeve paketini seçin.