NextPDF Laravel entegrasyonu

Bir bakışta

Bu nasıl yapılır kılavuzu, NextPDF’i bir Laravel 12 uygulamasında kurmayı gösterir. Altı aşamayı tamamlarsınız: paketi yükleme, Laravel’in paketi otomatik olarak keşfetmesine izin verme, yapılandırmayı yayımlama, kapsayıcı bağlamalarını çözümleme, bir Hypertext Transfer Protocol (HTTP) yanıtı döndürme ve kuyruğa alınan bir işi çalıştırma. Her aşamada ilgili alanın ayrıntılı başvuru belgesine bağlantı verilir.

Yükleme

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

Önyükleme/otomatik keşif

Laravel, hizmet sağlayıcısını ve cephe takma adını paketin composer.jsonextra.laravel bloğundan otomatik olarak keşfeder. config/app.php dosyasını düzenlemeniz gerekmez. Otomatik yükleme eşlemesi tek bir PSR-4 girdisi kullanır. NextPDF\Laravel\ öneki, PSR-4 önek-taban dizin kuralı uyarınca src/Laravel/ dizinine çözümlenir (PSR-4 §3). Sağlayıcı ertelenmiş olduğundan, yalnızca provides() girdilerinden biri ilk kez çözümlendiğinde önyüklenir. Keşfin tüm iç işleyişi için bkz.: /integrations/laravel/boot-and-discovery/.

Kapsayıcı bağlamaları

Belge sözleşmesini kapsayıcıdan çözümleyin. Bağlı bir tanımlayıcı, kayıtlı girdisine çözümlenir (PSR-11 §1.1.2). Belge bağlaması bir fabrikadır; bu nedenle her çözümleme yeni bir belge döndürür. Yazı tipi ve görüntü kayıt defterleri tekildir; bu nedenle her çözümleme aynı paylaşılan örneği döndürür. Tam bağlama ve yaşam süresi tablosu için bkz. /integrations/laravel/overview/ ve /integrations/laravel/boot-and-discovery/.

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;

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

Yapılandırmayı yayımlama

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

Bu komut, config/nextpdf.php dosyasını yazar. Yapılandırma başvurusu, her anahtarı, ortam değişkenini ve varsayılan değerini şurada açıklar: /integrations/laravel/configuration/.

Hizmet sağlayıcısı/paket duman testi

Paket, sağlayıcıyı uçtan uca test eden Testbench tabanlı bir test takımı içerir. Bu asgari duman testini, paketi kullanan bir uygulamaya ekleyin:

<?php

declare(strict_types=1);

namespace Tests\Feature;

use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Typography\FontRegistry;
use Tests\TestCase;

final class NextPdfIntegrationTest extends TestCase
{
    public function test_document_is_factory_bound(): void
    {
        $a = app(PdfDocumentInterface::class);
        $b = app(PdfDocumentInterface::class);

        self::assertNotSame($a, $b);
    }

    public function test_font_registry_is_singleton_and_locked(): void
    {
        $registry = app(FontRegistryInterface::class);

        self::assertInstanceOf(FontRegistry::class, $registry);
        self::assertTrue($registry->isLocked());
    }
}

Bu iki doğrulama, paketin EInvoiceServiceProviderIntegrationTest içindeki tek seferlik kullanım uygunluğu denetimlerini yansıtır. Belgenin fabrika olarak bağlandığını ve yazı tipi kayıt defterinin kilitli bir tekil olduğunu doğrularlar.

Genel API giriş noktaları

Giriş noktası	Amaç	Başvuru
`NextPDF\Laravel\Facades\Pdf`	Yeni belge için statik vekil	/integrations/laravel/quickstart/
`app(NextPDF\Contracts\PdfDocumentInterface::class)`	Kapsayıcı tarafından çözümlenen belge	/integrations/laravel/production-usage/
`NextPDF\Laravel\Http\PdfResponse`	Satır içi, indirme ve akış biçiminde HTTP yanıtları	/integrations/laravel/security-and-operations/
`NextPDF\Laravel\Jobs\GeneratePdfJob`	Kuyruğa alınmış oluşturma işlemi	/integrations/laravel/production-usage/

Kod örneği — üretim

Tam denetleyici örneği, bağımlılık enjeksiyonunu ve hata işlemeyi şurada gösterir: /integrations/laravel/production-usage/. Aynı sayfada, kuyruğa alınan iş ile başarı ve başarısızlık geri çağrıları da ele alınır.

Sınır durumları ve dikkat edilecek noktalar

Şunu çözümleyin: PdfDocumentInterface — somut Document sınıfını değil; böylece bağlama test edilebilir ve değiştirilebilir kalır.
SignerInterface ve TsaClient, yapılandırılana kadar null değerine çözümlenir. Her zaman null denetimi gerçekleştirin.
E-fatura sözleşmeleri nextpdf/premium paketini gerektirir. Bunlar bağlanmıştır; ancak paket olmadan ilk çözümlemede hata verir.

Performans

Sağlayıcı ertelenmiş olduğundan, uçtan uca bağlantı kurulumu önyüklemeye ek maliyet getirmez. İlk çözümleme sırasındaki oluşturma maliyetleri ve yazı tipi ısınma maliyetleri şurada ele alınır: /integrations/laravel/boot-and-discovery/.

Güvenlik notları

PdfResponse, sabit bir Open Worldwide Application Security Project (OWASP) başlık kümesi uygular. GeneratePdfJob, çıktı yolunu çalışan üzerinde doğrular. Tehdit modeli için bkz. /integrations/laravel/security-and-operations/.

Uygunluk

İddia	Kaynak	Madde	reference_id
Bağlı tanımlayıcı, kayıtlı girdisine çözümlenir	PSR-11 Container	§1.1.2
PSR-4 öneki taban dizine eşlenir	PSR-4 Autoloader	§3

Ticari bağlam

nextpdf/premium yüklendiğinde imzalama, PDF/A ve e-fatura sözleşmeleri aynı sağlayıcı üzerinden tümleşir. Bu belgede anlatılan Core paketi, bu isteğe bağlı Enterprise yeteneğini devreye almak 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/overview/ — mimari ve bağlama tablosu
/integrations/laravel/install/ — yükleme ve isteğe bağlı uzantılar
/integrations/laravel/quickstart/ — ilk çalıştırılabilir örnek
/integrations/laravel/production-usage/ — bağımlılık enjeksiyonu, hata işleme ve kuyruk
/integrations/laravel/boot-and-discovery/ — keşif ve yaşam süreleri