NextPDF Laravel entegrasyonuna genel bakış

Bir bakışta

NextPDF PDF motorunu Laravel 12 uygulamanıza nextpdf/laravel paketi bağlar ve container bağlamalarını sizin için kaydeder. Bir Pdf facade’ı, PdfResponse HTTP yardımcısı ve kuyruğa alınan GeneratePdfJob içerir. Laravel paketi otomatik olarak keşfeder; bu nedenle paketi elle kaydetmeniz gerekmez.

Kurulum

composer require nextpdf/laravel

Composer kısıtlaması nextpdf/core: ^3.0 || ^5.2 şeklindedir. Paket ayrıca laravel/framework: ^12.0 ve php: >=8.4 <9.0 gerektirir. Yapılandırmanın yayımlanması ve isteğe bağlı uzantılar dahil eksiksiz prosedür için /integrations/laravel/install/ sayfasına bakın.

Kavramsal genel bakış

Paket, Laravel hizmet container’ı ile çerçeveden bağımsız NextPDF çekirdeği arasında konumlanır. PDF üretimini yeniden uygulamaz. Bunun yerine, çekirdek NextPDF\Core\Document modelini Laravel’in yaşam döngüsüne, yapılandırmasına, kuyruklarına ve HTTP katmanına uyarlar.

Aşağıdaki diyagram, bir isteğin uygulama kodunuzdan paket aracılığıyla paylaşılan çekirdek kayıtlarına nasıl ulaştığını gösterir.

NextPDF Laravel request and render flow

Otomatik yükleme haritası tek bir PSR-4 girdisi içerir. PSR-4, otomatik yükleme için PHP Standart Önerisi’dir ve NextPDF\Laravel\ önekini src/Laravel/ dizinine eşler. PSR-4 kapsamında bir ad alanı öneki bir temel dizine karşılık gelir ve kalan sınıf adı o dizinin altındaki bir dosya yoluna eşlenir (PSR-4 §3). Bu önekin altında dört üretim sınıfı bulunur:

• NextPDF\Laravel\NextPdfServiceProvider — bağlamaları kaydeder ve yapılandırmayı yayımlar.
• NextPDF\Laravel\Facades\Pdf — container’dan yeni bir belge çözen statik vekil.
• NextPDF\Laravel\Http\PdfResponse — sabit bir güvenlik üst bilgisi kümesiyle satır içi, indirme ve akışlı PDF yanıtları oluşturur.
• NextPDF\Laravel\Jobs\GeneratePdfJob — bir iş parçacığında PDF oluşturup kaydeden, kuyruğa alınabilir bir iş.

Hizmet sağlayıcı DeferrableProvider arayüzünü uygular; bu nedenle bağlamalarını yalnızca bildirdiği girdilerden birini çözdüğünüzde kaydeder. Bu erteleme, çerçevenin başlatma yolunu hafif tutar. Sağlayıcının provides() yöntemi ertelenmiş girdileri listeler; container da bu listeyi okuyarak her anahtarı sağlayıcıya geri eşler.

Çözümleme, container sözleşmesini izler: bir bağlama mevcut olduğunda, tanımlayıcının çözülmesi kayıtlı girdiyi döndürür. PSR-11, container birlikte çalışabilirliği için PHP Standart Önerisi’dir ve aynı tanımlayıcıyla yapılan ardışık iki get() çağrısının, bağlama stratejisine bağlı olarak farklı değerler döndürebileceğini belirtir (PSR-11 §1.1.2). NextPDF bilinçli olarak bu davranışa dayanır. Kayıtlar singleton’dır; bu nedenle her çözümleme aynı örneği döndürür. Belgeler fabrika üzerinden bağlanır; bu nedenle her çözümleme yeni bir örnek döndürür. Tam bağlama yaşam süresi tablosu için /integrations/laravel/boot-and-discovery/ sayfasına bakın.

Mimari, Octane, RoadRunner ve Swoole gibi uzun ömürlü iş parçacıkları için tasarlanmıştır. Yazı tipi kaydı süreç ömrü boyunca yaşayan bir singleton’dır: paket bunu bir kez ısıtır ve ardından kilitler; böylece hiçbir istek paylaşılan yazı tipi durumunu değiştiremez. Görüntü kaydı, süreç ömrü boyunca yaşayan ve sınırlı bir en az kullanılan (LRU) önbelleğine sahip bir singleton’dır. Paket her belgeyi her zaman DocumentFactory üzerinden oluşturduğundan, istek başına değiştirilebilir durum hiçbir zaman istekler arasında sızmaz.

Belgeler neden her istekte yeniden oluşturulur

Fabrika bağlaması her çözümlemede yeni bir Document döndürür; paylaşılan yazı tipi ve görüntü kayıtları ise süreç çapında kalır. Bu ayrım, uzun ömürlü iş parçacığı süreçlerini (Octane, RoadRunner, Swoole) istekler arası durum sızıntılarından korurken yazı tipi ayrıştırma maliyetini de istekler arasında dağıtır.

API yüzeyi

Sınıf	Genel giriş noktası	Döndürür	Amaç
NextPdfServiceProvider	register(), boot(), provides()	void / array	Container bağlamaları, yapılandırmanın yayımlanması, ertelenmiş girdi listesi
Facades\Pdf	statik vekil (addPage(), cell(), save(), …)	static / mixed	Her çağrıda PdfDocumentInterface’i çözer
Http\PdfResponse	inline(), download(), streamInline(), streamDownload()	Response / StreamedResponse	Open Worldwide Application Security Project (OWASP) üst bilgilerini içeren HTTP yanıtları
Jobs\GeneratePdfJob	dispatch(), handle(), then(), catch(), failed()	PendingDispatch / void / self	Kuyruğa alınan PDF üretimi

Sağlayıcı tarafından bağlanan container anahtarları:

Anahtar	Yaşam süresi	Şuna çözülür
NextPDF\Contracts\FontRegistryInterface (FontRegistry diğer adı)	singleton, kilitli	NextPDF\Typography\FontRegistry
NextPDF\Graphics\ImageRegistry	singleton, LRU ile sınırlı	ImageRegistry
NextPDF\Contracts\DocumentFactoryInterface (DocumentFactory diğer adı)	singleton	NextPDF\Core\DocumentFactory
Psr\Http\Client\ClientInterface	singleton	SecurityAwareHttpClient sarmalayıcısı CurlHttpClient
NextPDF\Security\Timestamp\TsaClient	kapsamlı	TsaClient veya zaman damgası yetkilisi (TSA) URL’si olmadığında null değeri
NextPDF\Contracts\SignerInterface	fabrika	DigitalSigner veya imzalama devre dışıyken null değeri
NextPDF\Contracts\PdfDocumentInterface (nextpdf diğer adı)	fabrika	NextPDF\Core\Document
NextPDF\Contracts\EInvoice\{Embedder,Validator,Profile,SchematronRunner}Interface	fabrika	yalnızca nextpdf/premium kurulduğunda çözülür

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

resource: README.md Quick Start (verified against src/Laravel/Facades/Pdf.php)

<?php

declare(strict_types=1);

use NextPDF\Laravel\Facades\Pdf;

Pdf::addPage();
Pdf::cell(0, 10, 'Hello from Laravel', newLine: true);
Pdf::save(storage_path('app/hello.pdf'));

Bir denetleyiciyle sınırlandırılmış, çalıştırılabilir bir örnek için /integrations/laravel/quickstart/ sayfasına bakın.

Kod örneği — üretim

Üretim deseni, belge sözleşmesini facade yerine container’dan çözer; bu da çağrı noktasını açık ve test edilebilir tutar. Bağımlılık enjeksiyonu (DI) ve hata işleme dahil eksiksiz denetleyici için /integrations/laravel/production-usage/ sayfasına bakın.

resource: src/Laravel/Http/PdfResponse.php (download factory)

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

$document = app(PdfDocumentInterface::class);
$document->addPage();
$document->cell(0, 10, 'Invoice', newLine: true);

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

Uç durumlar ve tuzaklar

• Sağlayıcı ertelenmiştir; bu nedenle ilgisiz bir container anahtarını çözmek NextPDF’yi başlatmaz. Bağlamalar yalnızca provides() girdilerinden birini talep ettiğinizde görünür.
• SignerInterface ve TsaClient, imzalamayı veya zaman damgası yetkilisini yapılandırmadığınızda tasarım gereği null değerine çözülür. Kodunuz sonucun null olup olmadığını denetlemelidir; bir örneğin var olduğunu varsaymayın.
• E-fatura sözleşmesi bağlamaları her zaman kayıtlıdır; ancak yalnızca nextpdf/premium kurulduğunda mevcut olan Premium somut sınıflarına çözülür. Bunları Premium olmadan çözmek sınıf bulunamadı hatası verir; hata başlatma sırasında değil, ilk çözümlemede ortaya çıkar.
• Facade her çözümlemede yeni bir belge döndürür. Aynı istekte Pdf:: ile yapılan ve aralarında Pdf::clearResolvedInstances() bulunan iki statik çağrıyı düşünün: çağrılar farklı belgeler üzerinde işlem yapar.

İsteğe bağlı imzalama hizmetlerini null açısından denetleyin

SignerInterface ve TsaClient, siz imzalamayı ve bir zaman damgası yetkilisini yapılandırana kadar null değerindedir; bu nedenle bu anahtarları çözen tüm kodlar null durumunu işlemelidir. Eksik bir null denetimi, başlatma sırasında değil, çalışma zamanında başarısız olur.

Performans

Sağlayıcı kaydı O(1) sürede çalışır. Sağlayıcı kapanışları bağlar; ağır nesneler oluşturmaz. Bu nedenle oluşturma maliyeti ilk çözümlemeye ertelenir. Yazı tipi kaydının ısıtılması, f’nin önceden yüklenen yazı tipi dosyalarının sayısı olduğu O(f) sürede çalışır ve her iş parçacığı süreci başına bir kez çalışır. Bu, uzun ömürlü iş parçacıklarında ilk istek gecikmesini dağıtır. Bu genel bakış için sayfa başına bellek bütçesi, frontmatter’daki performance_budget alanında kaydedilir.

Güvenlik notları

PdfResponse, sabit bir Open Worldwide Application Security Project (OWASP) üst bilgisi kümesi uygular. Bu küme X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Content-Security-Policy: default-src 'none', X-Robots-Tag ve Referrer-Policy: no-referrer içerir. GeneratePdfJob çıktı yolunu iş parçacığı tarafında doğrular; böylece kurcalanmış serileştirilmiş yüklerin etkisi azalır. Tam tehdit modeli ve dağıtım yapılandırması için /integrations/laravel/security-and-operations/ sayfasına bakın.

Kuyruk yükü güvenilmeyen girdidir

GeneratePdfJob, çıktı yolunu yalnızca gönderim sırasında değil, iş parçacığındaki handle() içinde de yeniden doğrular. Serileştirilmiş yük, iş parçacığı onu alma fırsatı bulmadan önce kuyruk taşıma katmanında (Redis veya veritabanı) kurcalanabileceğinden, iş parçacığı tarafındaki denetim yol geçişlerini, akış sarmalayıcılarını, null baytları ve PDF olmayan hedefleri reddeder.

Uyumluluk

İddia	Kaynak	Madde	reference_id
Container çözümleme / yaşam süresi semantiği	PSR-11 Container	§1.1.2
PSR-4 otomatik yükleme öneki eşlemesi	PSR-4 Autoloader	§3

Ticari bağlam

Aynı sağlayıcı, nextpdf/premium kurulduğunda daha fazla yetenek sunar: dijital imzalama (PAdES B-B), PDF/A arşivleme ve e-fatura sözleşmesi bağlamaları. Bunları aynı container anahtarları aracılığıyla sunar; bu nedenle burada belgelenen Core paketinin bu yetenekleri benimsemek için herhangi bir kod değişikliğine ihtiyacı yoktur. Ayrıntılar için bkz. https://nextpdf.dev/get-license/?intent=laravel-signing.

Ayrıca bkz.

• /integrations/laravel/install/ — kurulum prosedürü ve isteğe bağlı uzantılar
• /integrations/laravel/quickstart/ — çalıştırılabilir denetleyici örneği
• /integrations/laravel/configuration/ — her yapılandırma anahtarı şu dosyaya göre doğrulanmıştır: config/nextpdf.php
• /integrations/laravel/production-usage/ — DI ile bağlanmış denetleyici, hata işleme ve kuyruğa alma
• /integrations/laravel/boot-and-discovery/ — otomatik keşif ve bağlama yaşam süreleri
• /integrations/laravel/security-and-operations/ — tehdit modeli ve dağıtım yapılandırması