Integrasi NextPDF untuk Laravel

Sekilas

Panduan ini membantu Anda menyiapkan NextPDF di aplikasi Laravel 12. Anda akan melalui enam tahap: memasang paket, membiarkan Laravel menemukannya secara otomatis, memublikasikan konfigurasi, melakukan resolve pada binding kontainer, mengembalikan respons Hypertext Transfer Protocol (HTTP), dan menjalankan job antrean. Setiap tahap ditautkan ke referensi terperinci untuk area terkait.

Pemasangan

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

Boot/penemuan otomatis

Laravel menemukan service provider dan alias facade secara otomatis dari blok composer.jsonextra.laravel pada paket. Anda tidak perlu menyunting config/app.php. Peta autoload menggunakan satu entri PSR-4. Prefiks NextPDF\Laravel\ di-resolve ke src/Laravel/ berdasarkan aturan PSR-4 untuk pemetaan prefiks ke direktori dasar (PSR-4 §3). Karena provider bersifat deferred, proses boot baru berjalan saat salah satu entri provides() pertama kali di-resolve. Untuk detail lengkap tentang mekanisme penemuan internal, lihat /integrations/laravel/boot-and-discovery/.

Binding kontainer

Lakukan resolve kontrak dokumen melalui kontainer. Identifier yang sudah di-bind akan di-resolve ke entri yang terdaftar (PSR-11 §1.1.2). Binding dokumen berupa factory, sehingga setiap resolve mengembalikan dokumen baru. Registri font dan gambar bersifat singleton, sehingga setiap resolve mengembalikan instance bersama yang sama. Untuk tabel lengkap masa hidup binding, lihat /integrations/laravel/overview/ dan /integrations/laravel/boot-and-discovery/.

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;

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

Publikasikan konfigurasi

php artisan vendor:publish --tag=nextpdf-config

Perintah ini menulis config/nextpdf.php. Referensi konfigurasi membahas setiap kunci, variabel lingkungan yang terkait, dan nilai standarnya di /integrations/laravel/configuration/.

Smoke test service provider/bundle

Paket ini menyertakan test suite berbasis Testbench untuk menguji provider secara menyeluruh. Tambahkan smoke test minimal berikut ke aplikasi yang menggunakan paket ini:

<?php

declare(strict_types=1);

namespace Tests\Feature;

use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Typography\FontRegistry;
use Tests\TestCase;

final class NextPdfIntegrationTest extends TestCase
{
    public function test_document_is_factory_bound(): void
    {
        $a = app(PdfDocumentInterface::class);
        $b = app(PdfDocumentInterface::class);

        self::assertNotSame($a, $b);
    }

    public function test_font_registry_is_singleton_and_locked(): void
    {
        $registry = app(FontRegistryInterface::class);

        self::assertInstanceOf(FontRegistry::class, $registry);
        self::assertTrue($registry->isLocked());
    }
}

Kedua assertion ini mencerminkan pemeriksaan konformansi khusus milik paket di EInvoiceServiceProviderIntegrationTest. Keduanya memastikan bahwa dokumen di-bind sebagai factory dan registri font merupakan singleton yang terkunci.

Titik masuk API publik

Titik masuk	Tujuan	Referensi
`NextPDF\Laravel\Facades\Pdf`	Proksi statis ke dokumen baru	/integrations/laravel/quickstart/
`app(NextPDF\Contracts\PdfDocumentInterface::class)`	Dokumen yang di-resolve oleh kontainer	/integrations/laravel/production-usage/
`NextPDF\Laravel\Http\PdfResponse`	Respons HTTP inline, unduh, dan streaming	/integrations/laravel/security-and-operations/
`NextPDF\Laravel\Jobs\GeneratePdfJob`	Pembuatan melalui antrean	/integrations/laravel/production-usage/

Contoh kode — Produksi

Controller lengkap yang menunjukkan dependency injection dan penanganan error tersedia di /integrations/laravel/production-usage/. Halaman yang sama membahas job antrean serta callback untuk kondisi berhasil dan gagal.

Kasus tepi & jebakan

Lakukan resolve pada PdfDocumentInterface, bukan Document konkret, agar binding tetap dapat diuji dan dapat ditukar.
SignerInterface dan TsaClient di-resolve menjadi null hingga dikonfigurasi. Selalu periksa apakah nilainya null.
Kontrak e-invoice memerlukan nextpdf/premium. Kontrak tersebut sudah di-bind, tetapi akan memunculkan error pada resolve pertama jika paket itu tidak tersedia.

Performa

Wiring menyeluruh tidak menambah biaya boot karena provider bersifat deferred. Biaya konstruksi saat resolve pertama dan biaya pemanasan font dibahas di /integrations/laravel/boot-and-discovery/.

Catatan keamanan

PdfResponse menerapkan set header Open Worldwide Application Security Project (OWASP) yang tetap. GeneratePdfJob memvalidasi path keluarannya pada worker. Lihat /integrations/laravel/security-and-operations/ untuk model ancamannya.

Konformansi

Klaim	Sumber	Klausa	reference_id
Identifier yang di-bind di-resolve ke entri yang terdaftar	PSR-11 Container	§1.1.2
Prefiks PSR-4 dipetakan ke direktori dasar	PSR-4 Autoloader	§3

Konteks komersial

Setelah nextpdf/premium dipasang, kontrak penandatanganan, PDF/A, dan e-invoice terintegrasi melalui provider yang sama. Paket Core yang didokumentasikan di sini tidak memerlukan perubahan kode untuk mengadopsi kapabilitas Enterprise opsional ini. Lihat https://nextpdf.dev/get-license/?intent=laravel-signing.

Lihat juga

/integrations/laravel/overview/ — arsitektur dan tabel binding
/integrations/laravel/install/ — pemasangan dan ekstensi opsional
/integrations/laravel/quickstart/ — contoh pertama yang dapat dijalankan
/integrations/laravel/production-usage/ — dependency injection, penanganan error, dan antrean
/integrations/laravel/boot-and-discovery/ — penemuan dan masa hidup