NextPDF Laravel paketini üretimde kullanma

Bir bakışta

Üretimde belge sözleşmesini yapıcı enjeksiyonuyla çözümleyin. PDF yazma hatalarını özel bir istisna ile işleyin. Ağır veya toplu oluşturma işlemlerini GeneratePdfJob işine taşıyın ve açık başarı ile başarısızlık geri çağırmalarını bağlayın.

Kurulum

composer require nextpdf/laravel
php artisan vendor:publish --tag=nextpdf-config

Kuyruk bağlantısını config/nextpdf.php dosyasında yapılandırın. queue.connection, queue.queue ve queue.timeout değerlerini ayarlayın. Ardından, yapılandırılan bağlantı üzerinde bir işçinin çalıştığından emin olun.

Kavramsal genel bakış

Konteyner, NextPDF\Contracts\PdfDocumentInterface arabirimini bir fabrika bağlaması olarak sunar. Her çözümleme, yeni bir NextPDF\Core\Document üretir. PSR-11, bağlama stratejisine bağlı olarak bir konteynerin ardışık get() çağrılarından farklı değerler döndürmesine izin verir (PSR-11 §1.1.2). Bu paket bir fabrika bağlaması kullanır; böylece istek kapsamındaki değiştirilebilir durum hiçbir zaman istekler arasında taşınmaz. Yazı tipi ve görüntü kayıtları tekildir (singleton). Bu, bağlanmış bir tanımlayıcının kayıtlı girdisine çözümlenmesi sözleşmesini korur (PSR-11 §1.1.2); aynı zamanda maliyetli kaynakları işçi genelinde paylaşmaya devam eder.

Üretim kodunda facade yerine yapıcı enjeksiyonunu tercih edin. Bu, bağımlılığı açık hale getirir ve facade kökünü başlatmadan denetleyicinin birim olarak test edilebilir kalmasını sağlar.

Kod örneği — Üretim

Tür belirtilmiş hata işlemeli DI bağlamalı denetleyici

resource: NextPDF\Contracts\PdfDocumentInterface + src/Laravel/Http/PdfResponse.php

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

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

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

    public function show(int $invoiceId): Response
    {
        try {
            $this->document->addPage();
            $this->document->cell(0, 10, "Invoice #{$invoiceId}", newLine: true);
            $this->document->cell(0, 10, 'Thank you for your business.');

            return PdfResponse::download(
                $this->document,
                "invoice-{$invoiceId}.pdf",
            );
        } catch (Throwable $exception) {
            // Rethrow as an HTTP-meaningful failure; never swallow.
            $this->logger->error('Invoice PDF generation failed', [
                'invoice_id' => $invoiceId,
                'exception'  => $exception::class,
            ]);

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

Bağımlılık olarak PdfDocumentInterface arabirimini enjekte edin; somut Document sınıfını değil. Böylece testlerde bağlamayı değiştirebilirsiniz. Konteyner, her denetleyici örneklemesi için yeni bir belge döndürür. Tek bir işlem içinde, birbiriyle ilgisiz iki belge için aynı denetleyici örneğini yeniden kullanmayın.

Bu catch bloğu, istisna sınıfını günlüğe kaydeder ve yığın izlemesini sızdırmak yerine tanımlı bir HTTP hatası döndürür. Konteynerin framework günlükleyicisine çözümlediği Psr\Log\LoggerInterface arabirimini kullanın. PSR-3, yer tutucu kaçışını uygulayıcıya bırakır ve çağıranların bağlam değerlerini önceden kaçırmamasını belirtir (PSR-3 §1.2). Aradeğerlenmiş dizeler değil, yapılandırılmış bağlam aktarın.

Başarı ve başarısızlık geri çağırmalı kuyruklanmış oluşturma

GeneratePdfJob, bir ShouldQueue işidir. Varsayılan olarak üç deneme, 120 saniyelik bir zaman aşımı ve 10 saniyelik bir geri çekilme süresi kullanır. Üçünü de config/nextpdf.php dosyasında geçersiz kılabilirsiniz. Oluşturucu kapanışı, konteyner tarafından çözümlenen belgeyi alır ve yapılandırılmış bir belge döndürmelidir.

resource: src/Laravel/Jobs/GeneratePdfJob.php

<?php

declare(strict_types=1);

namespace App\Jobs;

use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Jobs\GeneratePdfJob;
use Psr\Log\LoggerInterface;
use Throwable;

final class DispatchMonthlyStatement
{
    public function __construct(private readonly LoggerInterface $logger) {}

    public function __invoke(int $accountId): void
    {
        // Dispatchable::dispatch() is `public static`: it constructs the
        // job from the arguments it receives and returns a PendingDispatch.
        // Pass every constructor argument — including the callbacks — to
        // the static call. Building an instance and then calling
        // `$job->dispatch(...)` would discard that instance (and its
        // callbacks) and queue a different job from only the static args.
        GeneratePdfJob::dispatch(
            storage_path("app/statements/{$accountId}.pdf"),
            static fn (PdfDocumentInterface $document): PdfDocumentInterface => $document
                ->addPage()
                ->cell(0, 10, "Statement for account {$accountId}", newLine: true),
            function (string $path) use ($accountId): void {
                $this->logger->info('Statement PDF written', [
                    'account_id' => $accountId,
                    'path'       => $path,
                ]);
            },
            function (Throwable $exception) use ($accountId): void {
                $this->logger->error('Statement PDF failed', [
                    'account_id' => $accountId,
                    'exception'  => $exception::class,
                ]);
            },
        );
    }
}

GeneratePdfJob::dispatch(), bağımsız değişkenlerini doğrudan (string $outputPath, callable $builder, ?callable $onSuccess, ?callable $onFailure) yapıcısına iletir. Sonuç olarak, başarı ve başarısızlık geri çağırmaları kuyruğa alınan aynı işe bağlanır. Bu kullanım, /integrations/laravel/quickstart/. sayfasındaki konumsal GeneratePdfJob::dispatch($path, $builder) biçimiyle eşleşir. Başarı geri çağırması çıktı yolunu, başarısızlık geri çağırması ise Throwable nesnesini alır. İş ayrıca, zincirleme için işi döndüren akıcı then() ve catch() ayarlayıcılarını da sunar. Bu ayarlayıcıları yalnızca aynı örneği koruyarak gönderdiğinizde, örneğin dispatch() yardımcısı aracılığıyla kullanın. İş ayrıca, kuyruk çalıştırıcısının nihai başarısızlıkta çağırdığı bir failed() yöntemini de sunar. Geri çağırmalar serileştirilebilir kapanışlara sarılır; böylece kuyruk aktarımı sonrasında da korunurlar.

Kuyruk davranışını ayarlama

Özellik	Varsayılan	Yapılandırma anahtarı
tries	3	yapılandırma tabanlı değil; değiştirmek için alt sınıf oluşturun
timeout	120	nextpdf.queue.timeout
backoff	10	yapılandırma tabanlı değil; değiştirmek için alt sınıf oluşturun
kuyruk adı	pdf	nextpdf.queue.queue
bağlantı	varsayılan	nextpdf.queue.connection

tries ve backoff, iş örneğinden okunan genel özelliklerdir. Paketle gelen iş, bunları yapılandırmadan okumaz. Yeniden deneme politikanız farklıysa, bunları geçersiz kılmak için GeneratePdfJob sınıfından alt sınıf oluşturun.

Uç durumlar ve dikkat edilecek noktalar

• Oluşturucu kapanışı bir PdfDocumentInterface döndürmelidir. İş, başlangıçta çözümlenen örneği değil, bu dönüş değerini kaydeder. İş testi bu sözleşmeyi açıkça doğrular.
• Çözümlenen SignerInterface bağımlılığı null döndürür; bunun istisnası, imzalamanın etkinleştirilmesi, bir sertifikanın yapılandırılması ve nextpdf/premium paketinin kurulmasıdır. İmzalamadan önce her zaman null denetimi yapın.
• Uzun ömürlü işçiler (Octane/RoadRunner/Swoole) kilitli yazı tipi kaydını paylaşır. Isınmanın ilk istekte değil, işçi başlatılırken bir kez çalışmasını sağlamak için preload_fonts ayarını yapılandırın.
• Başarısız bir iş, failed() yöntemini tries tükendikten sonra çağırır. Her denemedeki başarısızlık, kuyruk çalıştırıcısı nihai başarısızlığı bildirene kadar onFailure’ı çağırmaz.

Performans

Eşzamanlı denetleyici oluşturma, isteği PDF’nin tüm derlemesi boyunca engeller. Çok sayfalı veya toplu çıktı için GeneratePdfJob işini gönderin ve hemen geri dönün. Tekil kayıtlar, yazı tipi ayrıştırma ve görüntü kod çözmeyi işçinin yaşam süresine yayar. Bu durumda istek başına maliyet, belge oluşturma ve içerik üretimiyle sınırlı kalır.

Güvenlik notları

Bağımlılık enjeksiyonlu denetleyici, dahili ayrıntıların günlüklere sızmasını önlemek için istisnanın iletisini veya izini değil, istisna sınıfını günlüğe kaydeder. GeneratePdfJob, kuyruk aktarımında kurcalanmış serileştirilmiş yükleri hafifletmek için çıktı yolunu işçide doğrular. Ayrıntılı kapsam /integrations/laravel/security-and-operations/. sayfasındadır.

Uyumluluk

İddia	Kaynak	Madde	reference_id
Bağlanmış tanımlayıcı, kayıtlı girdisine çözümlenir	PSR-11 Container	§1.1.2
Ardışık çözümlemeler bağlama stratejisine göre farklılık gösterebilir (fabrika bağlaması)	PSR-11 Container	§1.1.2

PSR-3 günlükleme yönergesi PSR-3 belirtiminde yer alır. Bu yönerge, yer tutucu kaçışını uygulayıcıya bırakır ve çağıranları yapılandırılmış bağlam aktarmaya yönlendirir. psr_3_logger §1.2 belgesine bakın.

Ticari bağlam

nextpdf/premium aracılığıyla imzalı PAdES B-B çıktısı ve PDF/A arşivlemesi, aynı bağımlılık enjeksiyonu (DI) yüzeyini kullanır. Bu, isteğe bağlı bir Enterprise yeteneğidir. Burada belgelenen Core paketi, bunu benimsemek için kod değişikliği gerektirmez. Bkz. https://nextpdf.dev/get-license/?intent=laravel-signing.

Ayrıca bkz.

• /integrations/laravel/quickstart/ — minimal ilk örnek
• /integrations/laravel/configuration/ — kuyruk, imza ve yazı tipi anahtarları
• /integrations/laravel/security-and-operations/ — tehdit modeli ve sıkılaştırma
• /integrations/laravel/troubleshooting/ — sık görülen üretim hataları