NextPDF Laravel hızlı başlangıç

Genel bakış

Bu öğreticide, bir denetleyiciden indirilebilir bir PDF dosyası oluşturursunuz. Ardından aynı işi kuyruğa alınmış bir işe taşırsınız. Her kod parçacığı, paketin test paketinin doğruladığı davranışla eşleşir.

Kurulum

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

Kavramsal genel bakış

Üç giriş noktası, neredeyse her Laravel kullanım senaryosunu kapsar. Cephe (facade), en hızlı başlangıç yolunu sağlar. PdfResponse bir belgeyi HTTP yanıtına dönüştürür. Kuyruğa alınmış bir iş, ağır oluşturma işlemini istek iş parçacığının dışına taşır; böylece bunun bitmesini beklemek zorunda kalmazsınız. Bu öğretici, her giriş noktasını sırayla ele alır. Üretim düzeyindeki sürümler hata işleme ekler; ayrıntılar /integrations/laravel/production-usage/ adresindedir.

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

1. Cephe (facade)

Cephe (facade), her çağrıda kapsayıcıdan yeni bir belge örneği çözümler. Kapsayıcı, Laravel’in hizmet kayıt mekanizmasıdır. Bu kod parçacığı, tests/Unit/Laravel/Facades/PdfTest.php dosyasının doğruladığı davranışla eşleşir.

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

2. Bir denetleyiciden indirme yanıtı

PdfResponse::download(), Illuminate\Http\Response türünde bir yanıt döndürür; bu yanıt Content-Type: application/pdf başlığını, attachment düzenini ve Open Worldwide Application Security Project (OWASP) güvenlik başlıklarını içerir. tests/Unit/Laravel/Http/PdfResponseTest.php durum kodunu, içerik türünü, düzen önekini ve başlıkları denetler.

<?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(): Response
    {
        $document = app(PdfDocumentInterface::class);
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

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

Tarayıcıda satır içi önizleme göstermek için download() yerine inline() kullanın. Büyük belgeler için streamInline() veya streamDownload() kullanın. Bu yöntemler, PDF’i belirlenimci 64 KB’lik parçalar halinde gönderir.

3. Kuyruğa alınmış oluşturma

GeneratePdfJob, kuyruk çalışanında bir PDF oluşturur ve kaydeder. Oluşturucu kapanış (closure), kapsayıcıdan çözümlenen belgeyi alır ve yapılandırılmış belgeyi döndürür. tests/Unit/Laravel/Jobs/GeneratePdfJobTest.php, işin dosyayı belirtilen tam çıktı yolunda oluşturduğunu doğrular.

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

Çıktı yolu .pdf ile bitmelidir. İş, yazmadan önce yolu çalışanda doğrular.

Kod örneği — üretim

Üretim sürümleri açık hata işleme, iş üzerinde başarı ve başarısızlık geri çağrıları ve türlenmiş bir özel durum stratejisi ekler. Bunların tamamı /integrations/laravel/production-usage/ adresinde belgelenmiştir.

Sınır durumları ve dikkat edilecek noktalar

Cephe (facade), her çözümlemede farklı bir belge örneği döndürür. Pdf::getFacadeRoot() sonucunu mantıksal belgeler arasında önbelleğe almayın.
Herhangi bir PdfResponse fabrikasına boş bir dosya adı geçirirseniz, varsayılan olarak document.pdf kullanılır. Yanıt testleri bu varsayılanı doğrular.
ASCII olmayan dosya adları, otomatik olarak bir RFC 5987 filename*= parametresi alır. ASCII adlarında bu parametre bulunmaz.
GeneratePdfJob yol gezinmesini, akış sarmalayıcılarını, boş baytları ve .pdf dışındaki herhangi bir uzantıyı reddeder. Çalışanda InvalidArgumentException fırlatır.

Performans

Tek sayfalık bir belge, ön bilgide listelenen sayfa başına süre bütçesinin oldukça altında bir sürede oluşturulur. Oluşturma işlemini GeneratePdfJob’a taşımak, PDF oluşturma süresini HTTP isteğinden tamamen kaldırır. İş gönderildikten sonra istek tamamlanır.

Güvenlik notları

PdfResponse fabrikaları sabit bir OWASP başlık kümesi uygular. Ayrıca indirme dosya adını temizler. Kuyruğa alınmış iş, çıktı yolunu doğrular. Ayrıntılı tehdit kapsamı /integrations/laravel/security-and-operations/ adresinde bulunur.

Uygunluk

Bu öğretici için bağlayıcı herhangi bir normatif standart yoktur. Her kod parçacığı, paket kaynağına ve tests/ altındaki ilgili teste göre doğrulanır.

Ticari bağlam

İmzalı ve PDF/A çıktısı, isteğe bağlı bir Enterprise özelliği olarak nextpdf/premium ile kullanılabilir. Burada belgelenen Core paketi, bunu benimsemek için herhangi bir kod değişikliği gerektirmez. Bkz. https://nextpdf.dev/get-license/?intent=laravel-signing.

Ayrıca bakınız

/integrations/laravel/install/ — kurulum ve yapılandırmayı yayımlama
/integrations/laravel/production-usage/ — bağımlılık enjeksiyonu ve hata işleme ile yapılandırılmış denetleyici ve iş
/integrations/laravel/configuration/ — burada kullanılan yapılandırma anahtarları
/integrations/laravel/overview/ — mimari ve bağlama yaşam süreleri