Boot dan penemuan otomatis NextPDF di Laravel

Sekilas pandang

Laravel menemukan NextPdfServiceProvider secara otomatis dari composer.json paket ini. Provider ini mendaftarkan binding container yang ditangguhkan dan, saat berjalan di konsol, menerbitkan berkas konfigurasi. Halaman ini menjelaskan cara kerja penemuan serta masa hidup setiap binding.

Instalasi

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

Cara kerja penemuan otomatis Laravel

Paket ini mendeklarasikan provider dan alias facade-nya di blok extra.laravel dalam composer.json paketnya sendiri:

resource: composer.json (extra.laravel)

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

Saat Anda menjalankan composer require, Laravel membaca blok ini, lalu mendaftarkan provider dan aliasnya. Anda tidak perlu menyunting config/app.php atau bootstrap/providers.php secara manual. Array extra.laravel.providers mendaftarkan service provider secara otomatis, sedangkan extra.laravel.aliases mendaftarkan alias facade secara otomatis (panduan pengembangan paket Laravel 12, https://laravel.com/docs/12.x/packages, diakses 2026-05-18).

Urutan boot

NextPdfServiceProvider mengimplementasikan DeferrableProvider serta mengikuti siklus hidup standar register() / boot().

1. register() menggabungkan konfigurasi paket di bawah kunci nextpdf. Setelah itu, ia melakukan binding pada entri container: registri fon, registri gambar, document factory, klien Hypertext Transfer Protocol (HTTP) PHP Standards Recommendation 18 (PSR-18), klien timestamp, signer, document, dan kontrak e-invoice. Setiap binding berupa closure, sehingga belum ada objek berat yang dibangun di sini.
2. boot() memeriksa apakah ekstensi PHP mbstring dan zlib telah dimuat. Ia mendaftarkan konfigurasi yang dapat diterbitkan di bawah tag nextpdf-config hanya ketika runningInConsole() bernilai true.

Karena provider ditangguhkan, register() baru berjalan ketika Anda me-resolve salah satu entri yang dikembalikan oleh provides(). Me-resolve kunci container yang tidak terkait tidak akan mem-boot NextPDF.

Binding container dan masa hidupnya

PHP Standards Recommendation 11 (PSR-11) mengizinkan dua panggilan get() berturut-turut dengan identifier yang sama untuk mengembalikan nilai yang berbeda, bergantung pada strategi binding-nya (PSR-11 §1.1.2). Provider ini sengaja mengandalkan perilaku tersebut:

Kunci binding	Masa hidup	Catatan
FontRegistryInterface (+ alias FontRegistry)	singleton, dikunci setelah warmup	Diinisialisasi saat warmup dari preload_fonts; dikunci agar tidak ada request yang dapat mengubahnya
ImageRegistry	singleton	Cache least recently used (LRU) dengan batas ukuran yang ditentukan oleh image_cache_mb; tidak dikunci
DocumentFactoryInterface (+ alias DocumentFactory)	singleton	Tanpa state; berbagi kedua registri
Psr\Http\Client\ClientInterface	singleton	Klien yang sadar terhadap request faking dan membungkus klien curl; dibangun dari tsa.*
TsaClient	scoped	null ketika tsa.url kosong
SignerInterface	factory	null ketika penandatanganan dinonaktifkan atau sertifikat kosong
PdfDocumentInterface (+ alias nextpdf)	factory	NextPDF\Core\Document baru pada setiap resolve, dengan metadata standar diterapkan
EmbedderInterface, ValidatorInterface, ProfileInterface, SchematronRunnerInterface	factory	Resolve ke konkret Premium; error saat resolve pertama tanpa nextpdf/premium

Binding document menerapkan defaults.creator, defaults.language, dan, jika tidak kosong, defaults.author ke setiap document baru. Ketika pdfa tidak null, ia mengaktifkan PDF/A (Premium). Ketika bagian artisan ada dan kelas browser-factory Chrome tersedia, ia menerapkan konfigurasi renderer Chrome.

has() pada container menerima satu identifier string (PSR-11 §1.1.2). Kontrak e-invoice di-bind, sehingga has() mengembalikan true untuk kontrak tersebut bahkan ketika Premium tidak ada. Konkret yang hilang baru memicu error saat konstruksi.

Menonaktifkan penemuan otomatis

Tambahkan paket ke array dont-discover aplikasi, lalu daftarkan provider secara manual:

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,
];

Urutan resolusi konfigurasi

Setiap kunci di-resolve dalam urutan ini: variabel lingkungan → nilai config/nextpdf.php yang diterbitkan → nilai default paket yang digabungkan pada register(). Sebagian besar kunci menerima nama NEXTPDF_* maupun nama lingkungan lama TCPDF_*. Utamakan NEXTPDF_*.

Diagnostik

php artisan package:discover --ansi

Baris yang mencantumkan nextpdf/laravel mengonfirmasi bahwa penemuan berhasil. Karena provider ditangguhkan, binding itu sendiri tidak muncul hingga resolve pertama. Baris penemuan adalah indikator keberhasilan yang tepat.

Kasus tepi & jebakan

• Penerbitan konfigurasi hanya didaftarkan dalam konteks konsol, sehingga request berbasis web saja tidak pernah memicunya. Jalankan vendor:publish dari command-line interface (CLI).
• Selain kunci registry, factory, klien HTTP, signer, timestamp, dan document, provides() juga menyertakan empat kunci kontrak e-invoice.
• Instalasi baru dapat terlihat pasif hingga resolve relevan yang pertama. Ini adalah desain provider yang ditangguhkan, bukan kesalahan.

Performa

register() bersifat O(1) karena hanya membuat closure. Warmup registri fon bersifat O(f) terhadap fon yang dimuat sebelumnya dan berjalan satu kali per proses worker. Provider yang ditangguhkan menjaga biaya konstruksi NextPDF tetap di luar alur boot framework hingga sebuah binding benar-benar digunakan.

Catatan keamanan

Desain yang ditangguhkan mempersempit permukaan serangan saat boot. Registri fon yang terkunci mencegah satu request mengubah status fon untuk request lain pada worker yang berumur panjang. Untuk cakupan ancaman lengkap, lihat /integrations/laravel/security-and-operations/.

Konformitas

Klaim	Sumber	Klausa	reference_id
Resolusi berturut-turut dapat berbeda menurut strategi binding	PSR-11 Container	§1.1.2
has() menerima satu identifier string	PSR-11 Container	§1.1.2

Dokumentasi paket resmi Laravel 12 mengonfirmasi nama-nama kunci penemuan Laravel (https://laravel.com/docs/12.x/packages, diakses 2026-05-18).

Konteks komersial

Konkret Premium di-resolve melalui kunci binding yang ditangguhkan yang sama. Kapabilitas Enterprise opsional ini tidak memerlukan perubahan kode pada paket Core yang didokumentasikan di sini. Lihat https://nextpdf.dev/get-license/?intent=laravel-signing.

Lihat juga

• /integrations/laravel/install/ — instalasi dan penerbitan
• /integrations/laravel/overview/ — arsitektur paket
• /integrations/laravel/integration/ — panduan integrasi menyeluruh
• /integrations/laravel/configuration/ — setiap kunci konfigurasi