Ikhtisar integrasi Laravel NextPDF

Sekilas pandang

Paket nextpdf/laravel menghubungkan mesin PDF NextPDF ke aplikasi Laravel 12 Anda dan mendaftarkan binding kontainer secara otomatis. Paket ini menyertakan facade Pdf, helper HTTP PdfResponse, dan GeneratePdfJob berbasis antrean. Laravel mendeteksi paket ini secara otomatis, sehingga Anda tidak perlu mendaftarkannya secara manual.

Instalasi

composer require nextpdf/laravel

Batasan Composer-nya adalah nextpdf/core: ^3.0 || ^5.2. Paket ini juga membutuhkan laravel/framework: ^12.0 dan php: >=8.4 <9.0. Untuk prosedur lengkap, termasuk publikasi konfigurasi dan ekstensi opsional, lihat /integrations/laravel/install/.

Ikhtisar konseptual

Paket ini berada di antara service container Laravel dan inti NextPDF yang tidak terikat framework. Paket ini tidak mengimplementasikan ulang pembuatan PDF. Sebaliknya, paket ini mengadaptasi model inti NextPDF\Core\Document ke siklus hidup, konfigurasi, antrean, dan lapisan HTTP Laravel.

Diagram di bawah ini menelusuri alur sebuah permintaan dari kode aplikasi Anda, melalui paket, hingga registri inti bersama.

NextPDF Laravel request and render flow

Peta autoload memiliki satu entri PSR-4. PSR-4 adalah PHP Standard Recommendation untuk autoloading, dan prefiks NextPDF\Laravel\ dipetakan ke src/Laravel/. Berdasarkan PSR-4, sebuah prefiks namespace berpadanan dengan satu direktori dasar, dan bagian nama kelas yang tersisa dipetakan ke jalur berkas di bawah direktori tersebut (PSR-4 §3). Empat kelas produksi berada di bawah prefiks ini:

• NextPDF\Laravel\NextPdfServiceProvider — mendaftarkan binding dan mempublikasikan konfigurasi.
• NextPDF\Laravel\Facades\Pdf — proksi statis yang me-resolve dokumen baru dari kontainer.
• NextPDF\Laravel\Http\PdfResponse — membuat respons PDF inline, unduhan, dan streamed dengan kumpulan header keamanan tetap.
• NextPDF\Laravel\Jobs\GeneratePdfJob — job yang dapat diantrekan untuk membangun dan menyimpan PDF pada worker.

Service provider mengimplementasikan DeferrableProvider, sehingga binding-nya baru didaftarkan ketika Anda me-resolve salah satu entri yang dideklarasikan. Penangguhan ini menjaga jalur boot framework tetap ramping. Metode provides() milik provider mencantumkan entri yang ditangguhkan, dan kontainer membaca daftar ini untuk memetakan setiap kunci kembali ke provider.

Resolusi mengikuti kontrak kontainer: ketika sebuah binding tersedia, proses me-resolve identifier mengembalikan entri yang terdaftar. PSR-11 adalah PHP Standard Recommendation untuk interoperabilitas kontainer, dan spesifikasi ini mencatat bahwa dua panggilan get() berturut-turut dengan identifier yang sama dapat mengembalikan nilai yang berbeda, bergantung pada strategi binding (PSR-11 §1.1.2). NextPDF secara sengaja mengandalkan perilaku ini. Registri bersifat singleton, sehingga setiap resolusi mengembalikan instance yang sama. Dokumen bersifat factory-bound, sehingga setiap resolusi mengembalikan instance baru. Untuk tabel masa hidup binding selengkapnya, lihat /integrations/laravel/boot-and-discovery/.

Arsitekturnya dirancang untuk worker berumur panjang, seperti Octane, RoadRunner, dan Swoole. Registri fon adalah singleton dengan masa hidup proses: paket melakukan warm-up sekali lalu menguncinya, sehingga tidak ada permintaan yang dapat mengubah keadaan fon bersama. Registri gambar adalah singleton dengan masa hidup proses yang memiliki cache least-recently-used (LRU) yang dibatasi. Karena paket selalu membuat setiap dokumen dari DocumentFactory, keadaan mutable per permintaan tidak pernah bocor antarpermintaan.

Mengapa dokumen dibuat baru per permintaan

Binding factory mengembalikan Document baru pada setiap resolusi, sementara registri fon dan gambar bersama tetap digunakan di seluruh proses. Pemisahan ini menjaga proses worker berumur panjang (Octane, RoadRunner, Swoole) terbebas dari kebocoran keadaan antarpermintaan, sambil tetap mengamortisasi penguraian fon di berbagai permintaan.

Permukaan API

Kelas	Titik masuk publik	Mengembalikan	Tujuan
NextPdfServiceProvider	register(), boot(), provides()	void / array	Binding kontainer, publikasi config, dan daftar entri yang ditangguhkan
Facades\Pdf	proksi statis (addPage(), cell(), save(), …)	static / mixed	Me-resolve PdfDocumentInterface per panggilan
Http\PdfResponse	inline(), download(), streamInline(), streamDownload()	Response / StreamedResponse	Respons HTTP dengan header Open Worldwide Application Security Project (OWASP)
Jobs\GeneratePdfJob	dispatch(), handle(), then(), catch(), failed()	PendingDispatch / void / self	Pembuatan PDF berbasis antrean

Kunci kontainer yang di-bind oleh provider:

Kunci	Masa hidup	Di-resolve ke
NextPDF\Contracts\FontRegistryInterface (alias FontRegistry)	singleton, terkunci	NextPDF\Typography\FontRegistry
NextPDF\Graphics\ImageRegistry	singleton, dibatasi LRU	ImageRegistry
NextPDF\Contracts\DocumentFactoryInterface (alias DocumentFactory)	singleton	NextPDF\Core\DocumentFactory
Psr\Http\Client\ClientInterface	singleton	SecurityAwareHttpClient yang membungkus CurlHttpClient
NextPDF\Security\Timestamp\TsaClient	scoped	TsaClient atau null ketika tidak ada URL timestamp authority (TSA)
NextPDF\Contracts\SignerInterface	factory	DigitalSigner atau null ketika penandatanganan dinonaktifkan
NextPDF\Contracts\PdfDocumentInterface (alias nextpdf)	factory	NextPDF\Core\Document
NextPDF\Contracts\EInvoice\{Embedder,Validator,Profile,SchematronRunner}Interface	factory	di-resolve hanya ketika nextpdf/premium terpasang

Contoh kode — Mulai cepat

resource: README.md Quick Start (verified against src/Laravel/Facades/Pdf.php)

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

Untuk contoh yang dapat dijalankan dalam satu controller, lihat /integrations/laravel/quickstart/.

Contoh kode — Produksi

Pola produksi me-resolve kontrak dokumen dari kontainer, bukan dari facade, sehingga lokasi pemanggilan tetap eksplisit dan dapat diuji. Untuk controller lengkap, termasuk dependency injection (DI) dan penanganan kesalahan, lihat /integrations/laravel/production-usage/.

resource: src/Laravel/Http/PdfResponse.php (download factory)

<?php

declare(strict_types=1);

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

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

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

Kasus tepi & jebakan

• Provider ini ditangguhkan, sehingga me-resolve kunci kontainer yang tidak terkait tidak akan mem-boot NextPDF. Binding muncul hanya ketika Anda meminta salah satu entri provides().
• SignerInterface dan TsaClient di-resolve ke null secara desain ketika Anda belum mengonfigurasi penandatanganan atau timestamp authority. Kode Anda harus melakukan null-check terhadap hasilnya; jangan berasumsi bahwa instance selalu tersedia.
• Binding kontrak e-invoice selalu terdaftar, tetapi binding tersebut di-resolve ke kelas konkret Premium yang hanya ada ketika nextpdf/premium terpasang. Me-resolve binding tersebut tanpa Premium memunculkan kesalahan class-not-found, dan kesalahan itu muncul pada resolusi pertama, bukan saat boot.
• Facade mengembalikan dokumen baru per resolusi. Jika dua panggilan statis Pdf:: dalam permintaan yang sama dipisahkan oleh Pdf::clearResolvedInstances(), keduanya beroperasi pada dokumen yang berbeda.

Lakukan null-check pada layanan penandatanganan opsional

SignerInterface dan TsaClient bernilai null sampai Anda mengonfigurasi penandatanganan dan timestamp authority, sehingga setiap kode yang me-resolve kunci-kunci ini harus menangani kasus null. Null-check yang terlewat akan menyebabkan kegagalan saat runtime, bukan saat boot.

Performa

Registrasi provider berjalan dalam waktu O(1). Provider mem-bind closure dan tidak mengonstruksi objek berat, sehingga biaya konstruksi ditangguhkan hingga resolusi pertama. Warm-up registri fon berjalan dalam waktu O(f), dengan f adalah jumlah berkas fon yang dipramuat, dan dilakukan sekali per proses worker. Hal ini mengamortisasi latensi permintaan pertama pada worker berumur panjang. Anggaran memori per halaman untuk ikhtisar ini dicatat dalam field frontmatter performance_budget.

Catatan keamanan

PdfResponse menerapkan kumpulan header Open Worldwide Application Security Project (OWASP) yang tetap. Kumpulan tersebut mencakup X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Content-Security-Policy: default-src 'none', X-Robots-Tag, dan Referrer-Policy: no-referrer. GeneratePdfJob memvalidasi jalur keluarannya di sisi worker, yang memitigasi payload terserialisasi yang telah dirusak. Untuk model ancaman lengkap dan konfigurasi penyebaran, lihat /integrations/laravel/security-and-operations/.

Payload antrean adalah input yang tidak tepercaya

GeneratePdfJob memvalidasi ulang jalur keluaran di dalam handle() pada worker, bukan hanya saat dispatch. Karena payload terserialisasi dapat dirusak pada transport antrean (Redis atau basis data) sebelum worker mengambilnya, pemeriksaan sisi-worker menolak path traversal, stream wrapper, byte null, dan target non-PDF.

Konformitas

Klaim	Sumber	Klausa	reference_id
Resolusi kontainer / semantik masa hidup	PSR-11 Container	§1.1.2
Pemetaan prefiks autoload PSR-4	PSR-4 Autoloader	§3

Konteks komersial

Ketika nextpdf/premium terpasang, provider yang sama mengekspos lebih banyak kapabilitas: penandatanganan digital (PAdES B-B), pengarsipan PDF/A, dan binding kontrak e-invoice. Provider mengeksposnya melalui kunci kontainer yang sama, sehingga paket Core yang didokumentasikan di sini tidak memerlukan perubahan kode untuk mengadopsinya. Untuk detailnya, lihat https://nextpdf.dev/get-license/?intent=laravel-signing.

Lihat juga

• /integrations/laravel/install/ — prosedur instalasi dan ekstensi opsional
• /integrations/laravel/quickstart/ — contoh controller yang dapat dijalankan
• /integrations/laravel/configuration/ — setiap kunci config, diverifikasi terhadap config/nextpdf.php
• /integrations/laravel/production-usage/ — controller berbasis DI, penanganan kesalahan, antrean
• /integrations/laravel/boot-and-discovery/ — penemuan otomatis dan masa hidup binding
• /integrations/laravel/security-and-operations/ — model ancaman dan konfigurasi penyebaran