Panduan cepat NextPDF Laravel

Sekilas pandang

Dalam tutorial ini, Anda membuat berkas Portable Document Format (PDF) yang dapat diunduh dari sebuah controller. Setelah itu, Anda memindahkan pekerjaan yang sama ke queued job. Setiap cuplikan kode selaras dengan perilaku yang ditegaskan oleh test suite paket ini.

Pemasangan

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

Gambaran umum konseptual

Tiga titik masuk mencakup hampir semua kasus penggunaan Laravel. Facade adalah cara tercepat untuk memulai. PdfResponse mengubah dokumen menjadi respons Hypertext Transfer Protocol (HTTP). Queued job memindahkan proses pembuatan yang berat keluar dari thread permintaan, sehingga permintaan tidak perlu menunggu proses tersebut. Tutorial ini membahas setiap titik masuk secara bergiliran. Versi untuk produksi menambahkan penanganan kesalahan dan tersedia di /integrations/laravel/production-usage/.

Contoh kode — Mulai cepat

1. Facade

Facade mengambil dokumen baru dari container setiap kali dipanggil. Container adalah registri layanan milik Laravel. Cuplikan kode ini selaras dengan perilaku yang ditegaskan oleh tests/Unit/Laravel/Facades/PdfTest.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'));

2. Respons unduhan dari sebuah controller

PdfResponse::download() mengembalikan Illuminate\Http\Response dengan Content-Type: application/pdf, disposisi attachment, serta header keamanan Open Worldwide Application Security Project (OWASP). tests/Unit/Laravel/Http/PdfResponseTest.php memeriksa kode status, content type, prefiks disposisi, dan header.

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

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

Untuk menampilkan pratinjau inline di peramban, ganti download() dengan inline(). Untuk dokumen berukuran besar, gunakan streamInline() atau streamDownload(). Keduanya mengirim PDF dalam potongan deterministik berukuran 64 KB.

3. Pembuatan melalui antrean

GeneratePdfJob membuat dan menyimpan PDF di queue worker. Closure builder menerima dokumen yang diambil dari container dan mengembalikan dokumen yang telah dikonfigurasi. tests/Unit/Laravel/Jobs/GeneratePdfJobTest.php memastikan job tersebut membuat berkas pada path keluaran yang tepat.

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

Path keluaran harus diakhiri dengan .pdf. Job memvalidasi path tersebut di worker sebelum menulis.

Contoh kode — Produksi

Versi produksi menambahkan penanganan kesalahan secara eksplisit, callback keberhasilan dan kegagalan pada job, serta strategi exception yang bertipe. Semuanya didokumentasikan secara lengkap di /integrations/laravel/production-usage/.

Kasus tepi & jebakan

Facade mengembalikan instance dokumen yang berbeda pada setiap resolusi. Jangan menyimpan Pdf::getFacadeRoot() dalam cache di antara dokumen logis yang berbeda.
Jika Anda memberikan nama berkas kosong ke factory PdfResponse mana pun, nilainya akan menjadi document.pdf secara baku. Test suite respons menegaskan nilai baku ini.
Nama berkas non-ASCII otomatis menerima parameter RFC 5987 filename*=. Nama ASCII tidak.
GeneratePdfJob menolak path traversal, stream wrapper, byte null, dan ekstensi apa pun selain .pdf. Job ini melempar InvalidArgumentException pada worker.

Performa

Dokumen satu halaman dibuat jauh di bawah anggaran waktu nyata per halaman yang tercantum dalam front matter. Memindahkan proses pembuatan ke GeneratePdfJob menghilangkan waktu pembuatan PDF dari permintaan HTTP sepenuhnya. Permintaan segera kembali begitu job di-dispatch.

Catatan keamanan

Factory PdfResponse menerapkan kumpulan header OWASP yang tetap. Factory tersebut juga membersihkan nama berkas unduhan. Queued job memvalidasi path keluarannya. Cakupan ancaman terperinci tersedia di /integrations/laravel/security-and-operations/.

Kesesuaian

Tidak ada standar normatif yang mengatur tutorial ini. Setiap cuplikan kode diverifikasi terhadap kode sumber paket dan test yang sesuai di bawah tests/.

Konteks komersial

Keluaran bertanda tangan dan PDF/A tersedia melalui nextpdf/premium sebagai kemampuan Enterprise opsional. Paket Core yang didokumentasikan di sini tidak memerlukan perubahan kode untuk mengadopsinya. Lihat https://nextpdf.dev/get-license/?intent=laravel-signing.

Lihat juga

/integrations/laravel/install/ — memasang dan mempublikasikan konfigurasi
/integrations/laravel/production-usage/ — controller dan job yang disusun dengan dependency injection dan penanganan kesalahan
/integrations/laravel/configuration/ — kunci konfigurasi yang digunakan di sini
/integrations/laravel/overview/ — arsitektur dan masa hidup binding