Referensi API Laravel

Sekilas

Paket nextpdf/laravel menghubungkan inti NextPDF yang independen dari framework ke aplikasi Laravel. Ada empat titik masuk yang Anda panggil secara langsung: facade Pdf untuk alur penulisan ringkas, binding container PdfDocumentInterface untuk pembuatan dokumen yang dapat di-inject, pembantu PdfResponse untuk respons HTTP dari dokumen yang sudah selesai, dan queue job GeneratePdfJob untuk pembuatan di luar request. NextPdfServiceProvider mendaftarkan setiap binding dan ditemukan otomatis, sehingga Anda tidak memerlukan penyiapan manual. Konfigurasi di config/nextpdf.php mengontrol pengaturan baku, fon, queue, serta fitur penandatanganan dan otoritas stempel waktu (TSA) opsional.

Mulai dari sini: untuk mengirim berkas Portable Document Format (PDF) langsung dari controller, bangun dokumen lalu kembalikan PdfResponse::download($document, 'file.pdf'). Contoh pertama di bawah menunjukkan alur ini.

Tugas umum

Cuplikan di bawah mencakup tiga alur yang paling sering Anda gunakan di awal. Setiap cuplikan sudah diverifikasi terhadap sumber paket; tabel lengkap per simbol menyusul.

Kembalikan PDF yang dapat diunduh dari controller. Ini tugas paling umum:

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

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

Yang dilakukan: meng-inject dokumen baru, menulis satu baris, lalu mengembalikan respons attachment dengan Content-Type: application/pdf dan header keamanan Open Worldwide Application Security Project (OWASP). Gunakan inline() alih-alih download() untuk pratinjau di browser.

Tulis dan simpan dengan facade Pdf. Ini jalur tersingkat untuk skrip dan alur ringkas:

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

Yang dilakukan: facade me-resolve dokumen baru dari container, menulis satu sel, lalu menyimpan PDF yang sudah selesai ke disk.

Hasilkan PDF di luar thread request dengan GeneratePdfJob:

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

Yang dilakukan: mengantrekan proses pembuatan ke worker. Closure builder menerima dokumen yang di-resolve oleh container, lalu mengembalikannya. Job memvalidasi jalur keluaran .pdf sebelum menyimpannya. Nama queue, timeout, dan koneksi berasal dari config('nextpdf.queue.*').

Facade

Facade Pdf mem-proxy Document inti baru secara statis. Gunakan pada alur controller yang ringkas ketika gaya statis sudah jelas. Setiap baris mencantumkan satu metode dokumen yang di-proxy.

Simbol	Parameter	Perilaku baku	Mengembalikan	Melempar atau gagal dengan	Catatan
`NextPDF\Laravel\Facades\Pdf`	tidak ada; aksesor facade statis me-resolve `NextPDF\Contracts\PdfDocumentInterface`	Laravel me-resolve binding container saat ini untuk antarmuka dokumen.	API fluent dari dokumen inti yang mendasarinya.	Kegagalan binding container Laravel jika provider belum terdaftar.	Gunakan untuk alur controller ringkas. Utamakan injeksi melalui konstruktor untuk service dan job.
`Pdf::setTitle(string $title)`	`title`: judul dokumen.	Mengganti judul yang sudah ada.	`static`	Kesalahan validasi inti atau saat penulisan.	Mem-proxy ke `Document` inti.
`Pdf::setAuthor(string $author)`	`author`: metadata penulis dokumen.	Mengganti penulis sebelumnya.	`static`	Kesalahan validasi metadata inti.	Utamakan pengaturan baku yang terkonfigurasi untuk metadata seluruh aplikasi.
`Pdf::addPage(?PageSize $size = null, Orientation $orientation = Portrait)`	`size`: ukuran halaman opsional; `orientation`: `Portrait` secara baku.	Menggunakan ukuran halaman terkonfigurasi atau baku ketika `size` dihilangkan.	`static`	Kesalahan validasi halaman inti.	Gunakan `PageSize` eksplisit ketika ukuran keluaran penting.
`Pdf::setFont(string $family, string $style = '', float $size = 12.0)`	Keluarga fon, gaya, dan ukuran dalam poin.	Menggunakan gaya kosong dan ukuran 12 pt.	`static`	Kesalahan registry fon atau encoding.	Pramuat fon produksi melalui `nextpdf.preload_fonts` ketika latensi menjadi faktor penting.
`Pdf::cell(float $width, float $height, string $text = '', bool $border = false, bool $newLine = false, Alignment $align = Left)`	Kotak sel, teks, flag border, flag pindah baris, dan perataan.	Menggunakan teks kosong, tanpa border, tanpa pindah baris, dan perataan kiri.	`static`	Kesalahan tata letak atau encoding teks.	Gunakan untuk keluaran tata letak tetap yang sederhana.
`Pdf::multiCell(float $width, float $height, string $text, bool $border = false, Alignment $align = Left)`	Lebar sel, tinggi baris, teks, flag border, dan perataan.	Tanpa border dan perataan kiri.	`static`	Kesalahan tata letak atau encoding teks.	Gunakan ketika teks harus dibungkus dalam lebar tetap.
`Pdf::writeHtml(string $html)`	`html`: fragmen HTML.	Merender pada halaman saat ini dan membuat halaman baru bila diperlukan.	`static`	Kesalahan rendering HTML inti.	Terapkan kebijakan ukuran masukan dan sumber daya sebelum menerima HTML yang tidak tepercaya.
`Pdf::image(string $file, ?float $x = null, ?float $y = null, ?float $width = null, ?float $height = null)`	Jalur berkas dan area penempatan opsional.	Membiarkan dokumen inti memilih posisi saat ini dan ukuran intrinsik ketika koordinat dihilangkan.	`static`	Kesalahan dekode gambar, jalur, atau tata letak.	Validasi kebijakan sumber gambar sebelum menerima jalur yang disediakan pengguna.
`Pdf::output(?string $filename = null, OutputDestination $dest = Inline)`	`filename`: nama opsional; `dest`: tujuan keluaran.	Mengeluarkan secara inline ketika tujuan dihilangkan.	`string`	Kesalahan serialisasi inti.	Utamakan `PdfResponse` untuk respons HTTP Laravel.
`Pdf::save(string $path)`	`path`: target sistem berkas.	Menulis PDF yang sudah selesai ke disk.	`void`	Kesalahan sistem berkas atau penulisan inti.	Validasi direktori keluaran di dalam kode aplikasi.
`Pdf::getPdfData()`	tidak ada.	Membentuk byte PDF di memori.	`string`	Kesalahan serialisasi inti.	Gunakan ketika objek framework lain harus memiliki body respons.

Service provider dan binding

Gunakan tabel ini ketika Anda perlu me-resolve atau mengganti entri container secara langsung, seperti meng-inject DocumentFactoryInterface ke dalam service atau memeriksa apa saja yang ditangguhkan oleh provides().

Simbol	Parameter	Perilaku baku	Mengembalikan	Melempar atau gagal dengan	Catatan
`NextPdfServiceProvider::register()`	tidak ada.	Menggabungkan `config/nextpdf.php`; mendaftarkan registry, document factory, binding dokumen, klien HTTP, klien TSA, signer, dan kontrak e-invoice opsional.	`void`	Kesalahan resolusi container atau kelas opsional ketika fitur digunakan.	`FontRegistryInterface` dan `ImageRegistry` dibagikan; dokumen selalu baru.
`NextPdfServiceProvider::boot()`	tidak ada.	Memvalidasi ekstensi PHP yang diperlukan dan mempublikasikan `nextpdf-config` dalam mode konsol.	`void`	`RuntimeException` jika ekstensi yang diperlukan tidak tersedia.	Ekstensi yang diperlukan adalah `mbstring` dan `zlib`.
`NextPdfServiceProvider::provides()`	tidak ada.	Melaporkan ID service yang ditangguhkan.	`array<string>`	tidak ada yang diharapkan.	Mencakup `PdfDocumentInterface`, `DocumentFactoryInterface`, `FontRegistryInterface`, `SignerInterface`, `TsaClient`, `ClientInterface`, dan `nextpdf`.
`PdfDocumentInterface` / `nextpdf`	di-resolve dari container Laravel.	Membuat `Document` sekali pakai melalui `DocumentFactoryInterface`, lalu menerapkan pengaturan baku terkonfigurasi serta setelan PDF/A atau Artisan opsional.	`NextPDF\Core\Document`	Kesalahan ekstensi opsional ketika dikonfigurasi tetapi tidak tersedia.	Resolve dokumen baru untuk setiap request atau job.
`DocumentFactoryInterface`	di-resolve dari container Laravel.	Factory singleton yang berbagi registry fon dan gambar selama masa hidup proses.	`DocumentFactoryInterface`	Kesalahan penyiapan registry.	Gunakan ini untuk injeksi dependensi yang eksplisit.
`SignerInterface`	di-resolve dari container Laravel.	Mengembalikan `null` kecuali `nextpdf.signature.enabled` diset dan jalur sertifikat sudah dikonfigurasi.	`SignerInterface	null`	Kesalahan pemuatan sertifikat atau validasi level tanda tangan.

Konfigurasi

Gunakan tabel ini untuk mencari kunci nextpdf.* yang dibaca oleh binding dan digunakan pada runtime. Referensi lengkap untuk setiap kunci, termasuk variabel lingkungan dan nilai baku, ada di /integrations/laravel/configuration/.

Kunci	Tipe	Perilaku baku	Catatan
`nextpdf.fonts_path`	`string`	Menggunakan resource fon Laravel ketika dihilangkan.	Direktori untuk fon kustom dan proses pemanasan.
`nextpdf.cache_path`	`string`	Jalur cache aplikasi.	Jaga agar tetap dapat ditulis oleh worker PHP.
`nextpdf.preload_fonts`	`list<string>`	Daftar kosong.	Dimuat di awal saat registry dibuat, lalu registry dikunci.
`nextpdf.image_cache_mb`	`int`	Ukuran cache gambar yang dibatasi.	Membatasi memori cache gambar berumur sepanjang proses.
`nextpdf.defaults.*`	`array`	Pembuat `NextPDF`, bahasa `en`, penulis, dan pengaturan baku tata letak opsional.	Diterapkan pada setiap dokumen baru.
`nextpdf.artisan.*`	`array`	Renderer Chrome dinonaktifkan kecuali terpasang dan dikonfigurasi.	Dipetakan ke `ChromeRendererConfig::fromArray()`.
`nextpdf.signature.*`	`array`	Penandatanganan dinonaktifkan secara baku.	Sertifikat, kunci privat, kata sandi, sertifikat tambahan, dan level tanda tangan.
`nextpdf.tsa.*`	`array`	TSA dinonaktifkan ketika Uniform Resource Locator (URL) kosong.	Mendukung kredensial, berkas mutual Transport Layer Security (mTLS), timeout, pin kunci publik, dan kebijakan HTTP.
`nextpdf.ocsp_cache.*`	`array`	Cache Online Certificate Status Protocol (OCSP) diaktifkan dengan TTL yang terkonfigurasi.	Digunakan oleh alur validasi tanda tangan ketika tersedia.

Respons HTTP

Gunakan tabel ini ketika Anda mengembalikan dokumen yang sudah selesai melalui HTTP dan perlu memilih tampilan inline, unduhan attachment, atau keluaran streaming.

Simbol	Parameter	Perilaku baku	Mengembalikan	Melempar atau gagal dengan	Catatan
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: dokumen yang sudah dibangun; `filename`: nama berkas Content-Disposition.	Menormalkan nama berkas kosong menjadi `document.pdf`.	`Illuminate\Http\Response`	Kesalahan serialisasi inti atau konstruksi respons.	Menyetel tipe konten PDF dan header defensif.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	Sama seperti `inline`; disposisinya attachment.	Mengembalikan respons unduhan browser.	`Illuminate\Http\Response`	Sama seperti `inline`.	Gunakan untuk unduhan berkas eksplisit.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	Sama seperti `inline`.	Membentuk byte PDF, lalu mengirimkan potongan 64 KB.	`Symfony\Component\HttpFoundation\StreamedResponse`	Sama seperti `inline`.	Ini adalah keluaran HTTP yang dialirkan, bukan rendering zero-copy.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	Sama seperti `streamInline`; disposisinya attachment.	Respons unduhan yang dialirkan.	`StreamedResponse`	Sama seperti `streamInline`.	Berlakukan batas ukuran masukan dan keluaran sebelum rendering.

Queue job

Gunakan tabel ini ketika Anda memindahkan pembuatan ke luar thread request. Tabel ini mencakup konstruksi, dispatch, serta callback keberhasilan atau kegagalan untuk GeneratePdfJob.

Simbol	Parameter	Perilaku baku	Mengembalikan	Melempar atau gagal dengan	Catatan
`new GeneratePdfJob(string $outputPath, callable $builder, ?callable $onSuccess = null, ?callable $onFailure = null)`	`outputPath`: target `.pdf`; `builder`: menerima sebuah `PdfDocumentInterface`; callback bersifat opsional.	Nama queue, timeout, dan koneksi dibaca dari `config('nextpdf.queue.*')`.	Instance job.	Kesalahan serialisasi jika builder atau callback tidak dapat diserialisasi.	Builder harus mengembalikan dokumen yang sudah dikonfigurasi.
`GeneratePdfJob::handle()`	tidak ada.	Me-resolve `PdfDocumentInterface`, menerapkan builder, memvalidasi jalur keluaran, lalu menyimpan.	`void`	`InvalidArgumentException` untuk jalur keluaran yang tidak aman; kesalahan penulisan inti.	Menolak stream wrapper, null byte, segmen `..`, dan jalur non-`.pdf`.
`GeneratePdfJob::failed(Throwable $exception)`	`exception`: penyebab kegagalan.	Memanggil callback kegagalan yang dikonfigurasi bila ada.	`void`	Kegagalan callback.	Jaga agar callback bersifat idempoten.
`GeneratePdfJob::then(callable $callback)`	`callback`: menerima jalur keluaran.	Mengganti callback keberhasilan.	`self`	Kesalahan closure yang dapat diserialisasi.	Pembantu fluent untuk penyiapan dispatch.
`GeneratePdfJob::catch(callable $callback)`	`callback`: menerima `Throwable` yang dilemparkan.	Mengganti callback kegagalan.	`self`	Kesalahan closure yang dapat diserialisasi.	Gunakan untuk pemberitahuan atau pembersihan kompensatif.

Catatan pengembangan

PdfResponse selalu memanggil getPdfData() sebelum mengonstruksi sebuah respons. Ini bukan pembangun dokumen lazy.
Payload queue dapat dimanipulasi pada transport bersama; jaga agar jalur keluaran tetap berada dalam direktori milik aplikasi.
Gunakan dokumen baru untuk setiap request atau job. Jangan gunakan ulang dokumen lintas request.