NextPDF Laravel'de başlatma ve otomatik keşif

Bir bakışta

Laravel, NextPdfServiceProvider sınıfını paketin composer.json dosyasından otomatik olarak keşfeder. Sağlayıcı, ertelenmiş container bağlarını kaydeder ve konsol bağlamında yapılandırma dosyasının yayımlanmasını sağlar. Bu sayfa, keşfin nasıl çalıştığını ve her bağın yaşam süresini açıklar.

Kurulum

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

Laravel otomatik keşfi nasıl çalışır

Paket, sağlayıcısını ve facade takma adını kendi extra.laravel bloğunda bildirir; bu blok paketin composer.json dosyasında yer alır:

resource: composer.json (extra.laravel)

{
  "extra": {
    "laravel": {
      "providers": [
        "NextPDF\\Laravel\\NextPdfServiceProvider"
      ],
      "aliases": {
        "Pdf": "NextPDF\\Laravel\\Facades\\Pdf"
      }
    }
  }
}

Siz composer require komutunu çalıştırdığınızda Laravel bu bloğu okur, ardından sağlayıcıyı ve takma adı kaydeder. config/app.php veya bootstrap/providers.php dosyasını elle düzenlemeniz gerekmez. extra.laravel.providers dizisi servis sağlayıcılarını, extra.laravel.aliases ise facade takma adlarını otomatik olarak kaydeder (Laravel 12 paket geliştirme kılavuzu, https://laravel.com/docs/12.x/packages, erişim tarihi 2026-05-18).

Başlatma sırası

NextPdfServiceProvider sınıfı, DeferrableProvider arayüzünü ve standart register() / boot() yaşam döngüsünü uygular.

1. register() paket yapılandırmasını nextpdf anahtarı altında birleştirir. Ardından şu container girişlerini bağlar: yazı tipi kaydı, görüntü kaydı, belge fabrikası, PHP Standards Recommendation 18 (PSR-18) Hypertext Transfer Protocol (HTTP) istemcisi, zaman damgası istemcisi, imzalayıcı, belge ve e-fatura sözleşmeleri. Her bağ bir closure olduğundan bu aşamada ağır nesne oluşturulmaz.
2. boot() mbstring ve zlib PHP eklentilerinin yüklü olup olmadığını denetler. Yayımlanabilir yapılandırmayı nextpdf-config etiketi altında yalnızca runningInConsole() true olduğunda kaydeder.

Sağlayıcı ertelendiği için register(), yalnızca provides() tarafından döndürülen girişlerden birini çözümlediğinizde çalışır. İlgisiz bir container anahtarının çözümlenmesi NextPDF’yi başlatmaz.

Container bağları ve yaşam süreleri

PHP Standards Recommendation 11 (PSR-11), aynı tanımlayıcıyla yapılan ardışık iki get() çağrısının bağ stratejisine bağlı olarak farklı değerler döndürmesine izin verir (PSR-11 §1.1.2). Sağlayıcı, tasarımı gereği bu davranışa dayanır:

Bağ anahtarı	Yaşam süresi	Notlar
FontRegistryInterface (+ FontRegistry takma adı)	singleton, ön ısıtmadan sonra kilitli	Ön ısıtma preload_fonts değerinden yapılır; kilitli olduğundan hiçbir istek bu kaydı değiştiremez
ImageRegistry	singleton	Boyutu image_cache_mb ile belirlenen sınırlı, en uzun süredir kullanılmayanı çıkaran (LRU) önbellek; kilitli değil
DocumentFactoryInterface (+ DocumentFactory takma adı)	singleton	Durumsuzdur; iki kaydı paylaşır
Psr\Http\Client\ClientInterface	singleton	İstek sahteciliğine duyarlı, curl istemcisini saran istemci; şu değerlerden oluşturulur: tsa.*
TsaClient	scoped	null olur (tsa.url boş olduğunda)
SignerInterface	factory	null olur (imzalama devre dışı bırakıldığında veya sertifika boş olduğunda)
PdfDocumentInterface (+ nextpdf takma adı)	factory	Her çözümlemede varsayılan meta verilerin uygulandığı yeni bir NextPDF\Core\Document örneği
EmbedderInterface, ValidatorInterface, ProfileInterface, SchematronRunnerInterface	factory	Premium somut sınıflarına çözümlenir; ilk çözümlemede şu paket olmadan hata verir: nextpdf/premium

Belge bağı, her yeni belgeye defaults.creator, defaults.language ve boş olmadığında defaults.author değerlerini uygular. pdfa null olmadığında PDF/A’yı (Premium) etkinleştirir. artisan bölümü mevcutsa ve bir Chrome tarayıcı fabrikası sınıfı bulunuyorsa Chrome işleyici yapılandırmasını uygular.

has(), container üzerinde tek bir dize tanımlayıcı alır (PSR-11 §1.1.2). E-fatura sözleşmeleri bağlandığından, Premium bulunmasa bile has() bunlar için true döndürür. Eksik somut sınıf yalnızca örnek oluşturma sırasında hata verir.

Otomatik keşfi devre dışı bırakma

Paketi uygulamanın dont-discover dizisine ekleyin ve ardından sağlayıcıyı elle kaydedin:

resource: application composer.json

{
  "extra": {
    "laravel": {
      "dont-discover": ["nextpdf/laravel"]
    }
  }
}

resource: bootstrap/providers.php

<?php

declare(strict_types=1);

return [
    App\Providers\AppServiceProvider::class,
    NextPDF\Laravel\NextPdfServiceProvider::class,
];

Yapılandırma çözümleme sırası

Her anahtar şu sırayla çözümlenir: ortam değişkeni → yayımlanan config/nextpdf.php değeri → register() sırasında birleştirilen paket varsayılanı. Anahtarların çoğu, bir NEXTPDF_* adını veya eski TCPDF_* ortam adını kabul eder. NEXTPDF_* kullanmayı tercih edin.

Tanılama

php artisan package:discover --ansi

Çıktıda nextpdf/laravel değerini listeleyen bir satır varsa keşif doğrulanmış olur. Sağlayıcı ertelendiği için bağların kendileri ilk çözümlemeye kadar görünmez. Doğru başarı sinyali keşif satırıdır.

Uç durumlar ve dikkat edilmesi gereken noktalar

• Yapılandırma yayımlaması yalnızca konsol bağlamında kaydedilir; bu nedenle tek başına web isteği bunu hiçbir zaman tetiklemez. vendor:publish komutunu komut satırı arayüzünden (CLI) çalıştırın.
• Kayıt, fabrika, HTTP istemcisi, imzalayıcı, zaman damgası ve belge anahtarlarının yanı sıra provides() dört e-fatura sözleşme anahtarını da içerir.
• Yeni bir kurulum, ilgili ilk çözümlemeye kadar atıl görünebilir. Bu bir hata değil, ertelenmiş sağlayıcı tasarımıdır.

Performans

register() yalnızca closure oluşturduğu için O(1) karmaşıklığındadır. Yazı tipi kaydının ön ısıtması, önceden yüklenen yazı tipleri açısından O(f) karmaşıklığındadır ve her işçi sürecinde bir kez çalışır. Sağlayıcının ertelenmesi, bir bağ gerçekten kullanılana kadar NextPDF yapım maliyetini framework başlatma yolundan uzak tutar.

Güvenlik notları

Ertelenmiş tasarım, başlatma sırasındaki saldırı yüzeyini daraltır. Kilitli yazı tipi kaydı, uzun ömürlü işçilerde bir isteğin başka bir isteğe ait yazı tipi durumunu değiştirmesini önler. Tam tehdit kapsamı için bkz. /integrations/laravel/security-and-operations/.

Uyumluluk

İddia	Kaynak	Madde	reference_id
Ardışık çözümlemeler bağ stratejisine göre farklı değerler döndürebilir	PSR-11 Container	§1.1.2
has() tek bir dize tanımlayıcı alır	PSR-11 Container	§1.1.2

Resmi Laravel 12 paket belgeleri, Laravel keşif anahtarlarının adlarını doğrular (https://laravel.com/docs/12.x/packages, erişim tarihi 2026-05-18).

Ticari bağlam

Premium somut sınıfları, aynı ertelenmiş bağ anahtarları aracılığıyla çözümlenir. Bu isteğe bağlı Enterprise özelliği, burada belgelenen Core paketinde kod değişikliği gerektirmez. Bkz. https://nextpdf.dev/get-license/?intent=laravel-signing.

Ayrıca bkz.

• /integrations/laravel/install/ — kurulum ve yayımlama
• /integrations/laravel/overview/ — paket mimarisi
• /integrations/laravel/integration/ — uçtan uca bağlama uygulama kılavuzu
• /integrations/laravel/configuration/ — her yapılandırma anahtarı