Laravel API başvurusu

Bir bakışta

Çerçeveden bağımsız NextPDF çekirdeğini bir Laravel uygulamasına nextpdf/laravel paketi bağlar. Dört giriş noktasını doğrudan çağırırsınız: kısa yazma akışları için Pdf cephesi, enjekte edilebilir belge oluşturma için PdfDocumentInterface kapsayıcı bağlaması, tamamlanmış belgelerden HTTP yanıtları oluşturmak için PdfResponse yardımcısı ve istek dışı oluşturma için GeneratePdfJob kuyruk işi. NextPdfServiceProvider her bağlamayı kaydeder ve otomatik olarak keşfedilir; bu nedenle elle kurulum yapmanız gerekmez. config/nextpdf.php içindeki yapılandırma; varsayılanları, yazı tiplerini, kuyrukları ve isteğe bağlı imzalama ile zaman damgası yetkilisi (TSA) özelliklerini denetler.

Buradan başlayın: bir denetleyiciden doğrudan taşınabilir belge biçimi (PDF) dosyası göndermek için bir belge oluşturun ve PdfResponse::download($document, 'file.pdf') döndürün. Aşağıdaki ilk örnek bu akışı gösterir.

Sık yapılan işlemler

Aşağıdaki kod parçacıkları, genellikle ilk kullanacağınız üç akışı kapsar. Her kod parçacığı paket kaynaklarına göre doğrulanmıştır; ayrıntılı simge tabloları aşağıdadır.

Bir denetleyiciden indirilebilir PDF döndürün. Bu, en sık yapılan işlemdir:

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

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

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

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

Yaptığı iş: yeni bir belge alır, bir satır yazar ve attachment türünde, Content-Type: application/pdf ve Open Worldwide Application Security Project (OWASP) güvenlik başlıklarını içeren bir yanıt döndürür. Tarayıcıda önizleme yapmak için inline() işlevini download() yerine kullanın.

Yazıp kaydetmek için Pdf cephesini kullanın. Bu, betikler ve kısa akışlar için en kısa yoldur:

<?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'));

Yaptığı iş: cephe, kapsayıcıdan yeni bir belge çözer, bir hücre yazar ve tamamlanmış PDF’yi diske kaydeder.

İstek iş parçacığının dışında GeneratePdfJob ile bir PDF oluşturun:

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Jobs\GeneratePdfJob;

GeneratePdfJob::dispatch(
    storage_path('app/reports/january-2026.pdf'),
    static fn (PdfDocumentInterface $document): PdfDocumentInterface => $document
        ->addPage()
        ->cell(0, 10, 'January report', newLine: true),
);

Yaptığı iş: oluşturma işlemini bir çalışan üzerinde kuyruğa alır. Oluşturucu kapanışı (closure), kapsayıcı tarafından çözümlenen bir belge alır ve aynı belgeyi döndürür. İş, kaydetmeden önce .pdf çıktı yolunu doğrular. Kuyruk adı, zaman aşımı ve bağlantı config('nextpdf.queue.*') değerinden okunur.

Cephe (facade)

Statik olarak Pdf cephesi, yeni bir çekirdek Document nesnesine vekillik eder. Statik stilin uygun olduğu kısa denetleyici akışlarında kullanın. Her satır, vekillik edilen bir belge yöntemini listeler.

Simge	Parametreler	Varsayılan davranış	Döndürür	Şu durumda hata verir veya başarısız olur	Notlar
NextPDF\Laravel\Facades\Pdf	yok; statik cephe erişimcisi şunu çözer: NextPDF\Contracts\PdfDocumentInterface	Laravel, belge arayüzü için geçerli kapsayıcı bağlamasını çözer.	Alttaki çekirdek belgenin akıcı (fluent) API’si.	Sağlayıcı kayıtlı değilse Laravel kapsayıcı bağlaması hatası.	Kısa denetleyici akışları için kullanın. Servisler ve işler için kurucu enjeksiyonunu tercih edin.
Pdf::setTitle(string $title)	title: belge başlığı.	Mevcut başlığı değiştirir.	static	Çekirdek doğrulama veya yazma sırasında oluşan hatalar.	Çekirdek Document nesnesine vekillik eder.
Pdf::setAuthor(string $author)	author: belge yazarı üst verisi.	Önceki yazarı değiştirir.	static	Çekirdek üst veri doğrulama hataları.	Uygulama genelindeki üst veri için yapılandırılmış varsayılanları tercih edin.
Pdf::addPage(?PageSize $size = null, Orientation $orientation = Portrait)	size: isteğe bağlı sayfa boyutu; orientation: varsayılan olarak Portrait.	Yapılandırılmış veya varsayılan sayfa boyutunu, size belirtilmediğinde kullanır.	static	Çekirdek sayfa doğrulama hataları.	Çıktı boyutu önemliyse açık bir PageSize kullanın.
Pdf::setFont(string $family, string $style = '', float $size = 12.0)	Yazı tipi ailesi, stili ve punto boyutu.	Boş stil ve 12 pt boyut kullanır.	static	Yazı tipi kaydı veya kodlama hataları.	Gecikme önemliyse üretim yazı tiplerini nextpdf.preload_fonts aracılığıyla önceden yükleyin.
Pdf::cell(float $width, float $height, string $text = '', bool $border = false, bool $newLine = false, Alignment $align = Left)	Hücre kutusu, metin, kenarlık bayrağı, satır sonu bayrağı ve hizalama.	Boş metin kullanır; kenarlık ve satır sonu eklemez, sola hizalar.	static	Yerleşim veya metin kodlama hataları.	Basit, sabit yerleşimli çıktı için kullanın.
Pdf::multiCell(float $width, float $height, string $text, bool $border = false, Alignment $align = Left)	Hücre genişliği, satır yüksekliği, metin, kenarlık bayrağı, hizalama.	Kenarlık eklemez ve sola hizalar.	static	Yerleşim veya metin kodlama hataları.	Metnin sabit bir genişlik içinde kaydırılması gerektiğinde kullanın.
Pdf::writeHtml(string $html)	html: HTML parçası.	Geçerli sayfada işler ve gerektiğinde sayfa oluşturur.	static	Çekirdek HTML işleme hataları.	Güvenilmeyen HTML’yi kabul etmeden önce giriş boyutu ve kaynak ilkelerini uygulayın.
Pdf::image(string $file, ?float $x = null, ?float $y = null, ?float $width = null, ?float $height = null)	Dosya yolu ve isteğe bağlı yerleştirme dikdörtgeni.	Koordinatlar belirtilmediğinde çekirdek belgenin geçerli konumu ve doğal boyutu seçmesine izin verir.	static	Görüntü çözme, yol veya yerleşim hataları.	Kullanıcının sağladığı yolları kabul etmeden önce görüntü kaynağı ilkesini doğrulayın.
Pdf::output(?string $filename = null, OutputDestination $dest = Inline)	filename: isteğe bağlı ad; dest: çıktı hedefi.	Hedef belirtilmediğinde satır içi çıktı üretir.	string	Çekirdek serileştirme hataları.	Laravel HTTP yanıtları için PdfResponse tercih edin.
Pdf::save(string $path)	path: dosya sistemi hedefi.	Tamamlanmış PDF’yi diske yazar.	void	Dosya sistemi veya çekirdek yazma hataları.	Çıktı dizinlerini uygulama kodunda doğrulayın.
Pdf::getPdfData()	yok.	PDF baytlarını bellekte somutlaştırır.	string	Çekirdek serileştirme hataları.	Yanıt gövdesini başka bir çerçeve nesnesi yönetmeliyse kullanın.

Servis sağlayıcı ve bağlamalar

Bir DocumentFactoryInterface nesnesini bir servise enjekte etmek veya provides() yönteminin hangi servisleri ertelediğini denetlemek gibi durumlarda, bir kapsayıcı girdisini doğrudan çözmeniz ya da geçersiz kılmanız gerektiğinde bu tabloyu kullanın.

Simge	Parametreler	Varsayılan davranış	Döndürür	Şu durumda hata verir veya başarısız olur	Notlar
NextPdfServiceProvider::register()	yok.	Şu dosyayı birleştirir: config/nextpdf.php; kayıtları, belge fabrikasını, belge bağlamasını, HTTP istemcisini, TSA istemcisini, imzalayıcıyı ve isteğe bağlı e-fatura sözleşmelerini kaydeder.	void	Özellik kullanıldığında kapsayıcı hataları veya isteğe bağlı sınıf çözümleme hataları.	FontRegistryInterface ve ImageRegistry paylaşılır; belgeler her zaman yenidir.
NextPdfServiceProvider::boot()	yok.	Gerekli PHP uzantılarını doğrular ve konsol modunda nextpdf-config yayımlar.	void	RuntimeException, gerekli bir uzantı kullanılamadığında oluşur.	Gerekli uzantılar mbstring ve zlib uzantılarıdır.
NextPdfServiceProvider::provides()	yok.	Ertelenmiş servis kimliklerini bildirir.	array<string>	Beklenmez.	Şunları içerir: PdfDocumentInterface, DocumentFactoryInterface, FontRegistryInterface, SignerInterface, TsaClient, ClientInterface ve nextpdf.
PdfDocumentInterface / nextpdf	Laravel kapsayıcısından çözümlenir.	Tek kullanımlık bir Document nesnesini DocumentFactoryInterface aracılığıyla oluşturur; ardından yapılandırılmış varsayılanları ve isteğe bağlı PDF/A veya Artisan ayarlarını uygular.	NextPDF\Core\Document	Yapılandırılmış olup kullanılamayan isteğe bağlı uzantı hataları.	Her istek veya iş için yeni bir belge çözün.
DocumentFactoryInterface	Laravel kapsayıcısından çözümlenir.	Yazı tipi ve görüntü kayıtlarını süreç ömrü boyunca paylaşan tekil (singleton) fabrika.	DocumentFactoryInterface	Kayıt kurulum hataları.	Açık bağımlılık enjeksiyonu için bunu kullanın.
SignerInterface	Laravel kapsayıcısından çözümlenir.	Varsayılan olarak null döndürür; bunun istisnası, nextpdf.signature.enabled ayarlandığında ve sertifika yolları yapılandırıldığındadır.	`SignerInterface	null`	Sertifika yükleme veya imza düzeyi doğrulama hataları.

Yapılandırma

Bağlamaların okuduğu çalışma zamanına dönük nextpdf.* anahtarlarını aramak için bu tabloyu kullanın. Ortam değişkenleri ve varsayılanlar dâhil olmak üzere her anahtarın tam başvurusu /integrations/laravel/configuration/ adresindedir.

Anahtar	Tür	Varsayılan davranış	Notlar
nextpdf.fonts_path	string	Belirtilmediğinde Laravel kaynak yazı tiplerini kullanır.	Özel yazı tipleri ve ön ısıtma dizini.
nextpdf.cache_path	string	Uygulama önbellek yolu.	PHP çalışanı tarafından yazılabilir tutun.
nextpdf.preload_fonts	list<string>	Boş liste.	Kayıt oluşturma sırasında ön ısıtılır, ardından kayıt kilitlenir.
nextpdf.image_cache_mb	int	Sınırlandırılmış görüntü önbelleği boyutu.	Süreç ömrü boyunca görüntü önbellek belleğini sınırlar.
nextpdf.defaults.*	array	Oluşturan değeri NextPDF, dil en, isteğe bağlı yazar ve yerleşim varsayılanları.	Her yeni belgeye uygulanır.
nextpdf.artisan.*	array	Chrome işleyici, kurulup yapılandırılmadığı sürece devre dışıdır.	Şu yönteme eşlenir: ChromeRendererConfig::fromArray().
nextpdf.signature.*	array	İmzalama varsayılan olarak devre dışıdır.	Sertifika, özel anahtar, parola, ek sertifikalar ve imza düzeyi.
nextpdf.tsa.*	array	Tekdüzen kaynak konumlandırıcı (URL) boş olduğunda TSA devre dışıdır.	Kimlik bilgilerini, karşılıklı aktarım katmanı güvenliği (mTLS) dosyalarını, zaman aşımını, ortak anahtar sabitlemelerini ve HTTP ilkesini destekler.
nextpdf.ocsp_cache.*	array	Çevrim içi sertifika durumu protokolü (OCSP) önbelleği yapılandırılmış TTL ile etkindir.	Kullanılabilir olduğunda imza doğrulama akışları tarafından kullanılır.

HTTP yanıtları

Tamamlanmış bir belgeyi HTTP üzerinden döndürürken satır içi görüntüleme, ek (attachment) olarak indirme ya da akış çıktısı arasında seçim yapmanız gerektiğinde bu tabloyu kullanın.

Simge	Parametreler	Varsayılan davranış	Döndürür	Şu durumda hata verir veya başarısız olur	Notlar
PdfResponse::inline(Document $document, string $filename = 'document.pdf')	document: oluşturulmuş belge; filename: Content-Disposition dosya adı.	Boş dosya adlarını document.pdf olarak normalleştirir.	Illuminate\Http\Response	Çekirdek serileştirme veya yanıt oluşturma hataları.	PDF içerik türünü ve savunmacı başlıkları ayarlar.
PdfResponse::download(Document $document, string $filename = 'document.pdf')	Şununla aynıdır: inline; içerik düzeni (disposition) ek (attachment) olur.	Bir tarayıcı indirme yanıtı döndürür.	Illuminate\Http\Response	Şununla aynıdır: inline.	Açık dosya indirmeleri için kullanın.
PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')	Şununla aynıdır: inline.	PDF baytlarını somutlaştırır; ardından 64 KB’lik parçalar gönderir.	Symfony\Component\HttpFoundation\StreamedResponse	Şununla aynıdır: inline.	Bu, sıfır kopyalı işleme değil, akışla gönderilen HTTP çıktısıdır.
PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')	Şununla aynıdır: streamInline; içerik düzeni (disposition) ek (attachment) olur.	Akışla indirme yanıtı.	StreamedResponse	Şununla aynıdır: streamInline.	İşlemeden önce giriş ve çıkış boyutu sınırlarını zorunlu kılın.

Kuyruk işi

Oluşturma işlemini istek iş parçacığının dışına taşıdığınızda bu tabloyu kullanın. Tablo, GeneratePdfJob için oluşturmayı, gönderimi ve başarı ya da başarısızlık geri çağırmalarını kapsar.

Simge	Parametreler	Varsayılan davranış	Döndürür	Şu durumda hata verir veya başarısız olur	Notlar
new GeneratePdfJob(string $outputPath, callable $builder, ?callable $onSuccess = null, ?callable $onFailure = null)	outputPath: hedef .pdf; builder: bir PdfDocumentInterface alır; geri çağırmalar isteğe bağlıdır.	Kuyruk adı, zaman aşımı ve bağlantı config('nextpdf.queue.*') değerinden okunur.	Bir iş örneği.	Oluşturucu veya geri çağırmalar serileştirilemiyorsa serileştirme hataları.	Oluşturucu, yapılandırılmış belgeyi döndürmelidir.
GeneratePdfJob::handle()	yok.	Önce PdfDocumentInterface çözer, oluşturucuyu çalıştırır, çıktı yolunu doğrular ve ardından kaydeder.	void	InvalidArgumentException, güvenli olmayan çıktı yolları için; çekirdek yazma hataları.	Akış sarmalayıcılarını, null baytları, .. bölümlerini ve .pdf dışındaki yolları reddeder.
GeneratePdfJob::failed(Throwable $exception)	exception: başarısızlık nedeni.	Varsa, yapılandırılmış başarısızlık geri çağırmasını çağırır.	void	Geri çağırma başarısızlıkları.	Geri çağırmaları etkisiz-tekrarlanabilir (idempotent) tutun.
GeneratePdfJob::then(callable $callback)	callback: çıktı yolunu alır.	Başarı geri çağırmasını değiştirir.	self	Serileştirilebilir kapanış (closure) hataları.	Gönderimi yapılandırmak için akıcı yardımcı.
GeneratePdfJob::catch(callable $callback)	callback: fırlatılan Throwable nesnesini alır.	Başarısızlık geri çağırmasını değiştirir.	self	Serileştirilebilir kapanış (closure) hataları.	Uyarı vermek veya telafi edici temizlik yapmak için kullanın.

Geliştirme notları

• PdfResponse bir yanıt oluşturmadan önce her zaman getPdfData() çağırır. Tembel (lazy) bir belge oluşturucusu değildir.
• Kuyruk yükleri, paylaşılan aktarımlarda kurcalanabilir; çıktı yollarını uygulamaya ait bir dizinle sınırlı tutun.
• Her istek veya iş için yeni bir belge kullanın. Bir belgeyi istekler arasında yeniden kullanmayın.