Referensi API Symfony

Sekilas

Paket Symfony mengekspos registrasi bundle, pohon konfigurasi, factory yang dapat diinjeksi untuk dokumen baru, helper respons untuk Hypertext Transfer Protocol (HTTP), dan tipe Messenger untuk pembuatan asinkron. Sebagian besar kode aplikasi hanya memakai dua simbol: layanan PdfFactory yang Anda injeksi untuk membangun Document, dan helper PdfResponse yang mengubah dokumen tersebut menjadi respons HTTP yang aman. Simbol lainnya (bundle, extension, compiler pass, pohon konfigurasi, objek transfer data (DTO) Messenger, dan handler) merupakan wiring yang Anda konfigurasi sekali atau dikelola oleh framework untuk Anda.

Mulai di sini: Injeksikan NextPDF\Symfony\Service\PdfFactory, panggil create() untuk mendapatkan Document baru, lalu kembalikan dengan NextPDF\Symfony\Http\PdfResponse::download(). Contoh pertama menunjukkan alur tersebut.

Tugas umum

Gunakan tiga cuplikan siap dijalankan ini untuk tugas yang paling umum. Setiap cuplikan hanya memakai simbol terverifikasi yang didokumentasikan dalam tabel berikut.

Mengembalikan unduhan Portable Document Format (PDF) dari controller: injeksikan factory, bangun dokumen, lalu teruskan ke helper respons:

<?php

declare(strict_types=1);

namespace App\Controller;

use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class InvoiceController
{
    #[Route('/invoice/{number}', name: 'invoice_pdf')]
    public function download(PdfFactory $pdf, string $number): Response
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, "Invoice #{$number}");

        return PdfResponse::download($doc, "invoice-{$number}.pdf");
    }
}

Cara kerjanya: PdfFactory::create() mengembalikan Document baru yang telah dikonfigurasi sebelumnya. PdfResponse::download() mengirimkannya dengan Content-Type: application/pdf, disposisi attachment, dan header keamanan tetap dari bundle.

Melakukan streaming PDF besar agar penggunaan memori puncak tetap rendah: gunakan helper streamed dan kembalikan StreamedResponse:

<?php

declare(strict_types=1);

namespace App\Controller;

use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;
use Symfony\Component\HttpFoundation\StreamedResponse;
use Symfony\Component\Routing\Attribute\Route;

final class ReportController
{
    #[Route('/report', name: 'report_pdf')]
    public function report(PdfFactory $pdf): StreamedResponse
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->setFont('dejavusans', '', 12);
        $doc->cell(0, 10, 'Annual report');

        return PdfResponse::streamDownload($doc, 'annual-report.pdf');
    }
}

Cara kerjanya: PdfResponse::streamDownload() mengirimkan PDF yang telah dimaterialisasi dalam potongan-potongan dan menghapus Content-Length; gunakan streamInline() untuk padanan inline-nya.

Mengirim PDF untuk pembuatan asinkron: kirim GeneratePdfMessage ke transport Messenger agar proses rendering berjalan pada worker:

<?php

declare(strict_types=1);

namespace App\Controller;

use App\Pdf\InvoicePdfBuilder;
use NextPDF\Symfony\Message\GeneratePdfMessage;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Messenger\MessageBusInterface;
use Symfony\Component\Routing\Attribute\Route;

final class QueueController
{
    #[Route('/invoice/{id}/queue', name: 'invoice_queue')]
    public function queue(MessageBusInterface $bus, int $id): Response
    {
        $bus->dispatch(new GeneratePdfMessage(
            builderClass: InvoicePdfBuilder::class,
            outputPath: '/var/storage/invoices/' . $id . '.pdf',
            builderContext: ['invoice_id' => $id],
        ));

        return new Response('PDF generation queued.', 202);
    }
}

Cara kerjanya: DTO membawa class-string builder dan jalur keluaran yang tervalidasi. Handler mengambil builder, membangun dokumen, lalu menyimpannya di worker. Kelas builder mengimplementasikan PdfBuilderInterface dan didaftarkan di service locator (lihat quickstart Symfony untuk wiring locator dan worker).

Factory

Gunakan tabel ini untuk memilih konstruktor yang tepat dan memahami kontrak create() dari layanan yang dapat diinjeksi yang menghasilkan dokumen baru.

Simbol	Parameter	Perilaku standar	Mengembalikan	Memunculkan atau gagal dengan	Catatan
new PdfFactory(DocumentFactoryInterface $factory, array $defaults, ?string $pdfa, array $artisanConfig)	factory: factory inti; defaults: creator, author, language, margin; pdfa: profil PDF/A opsional; artisanConfig: konfigurasi renderer Chrome opsional.	Nilai standar diterapkan hanya ketika dikonfigurasi.	PdfFactory	Kesalahan pada wiring container.	Layanan dapat dibuat singleton karena create() mengembalikan dokumen baru.
PdfFactory::create()	tidak ada.	Menerapkan creator dan language; menerapkan author hanya ketika tidak kosong; menerapkan konfigurasi PDF/A dan Artisan hanya ketika tersedia.	NextPDF\Core\Document	Kesalahan konfigurasi inti.	Gunakan sekali per request, command, atau message.
PdfFactory::setArtisanAvailable(bool $available)	available: flag ketersediaan pada waktu kompilasi.	Dinonaktifkan hingga compiler pass mengaktifkannya.	void	tidak ada yang diharapkan.	Hook internal yang dipanggil oleh compiler pass extension opsional.
PdfFactory::setProAvailable(bool $available)	available: flag ketersediaan pada waktu kompilasi.	Dinonaktifkan hingga compiler pass mengaktifkannya.	void	tidak ada yang diharapkan.	Hook internal untuk ketersediaan Premium.

Bundle, extension, dan konfigurasi

Gunakan tabel pertama untuk lapisan wiring: registrasi bundle, pohon konfigurasi nextpdf, dan deteksi extension opsional. Tabel kedua mencantumkan key konfigurasi.

Simbol	Parameter	Perilaku standar	Mengembalikan	Memunculkan atau gagal dengan	Catatan
NextPdfBundle::build(ContainerBuilder $container)	Container builder Symfony.	Memanggil metode build induk dan mendaftarkan OptionalExtensionPass.	void	Kesalahan registrasi compiler pass.	Mengaktifkan deteksi fitur Artisan dan Premium opsional.
NextPdfBundle::getPath()	tidak ada.	Mengembalikan jalur root paket.	string	tidak ada yang diharapkan.	Digunakan oleh discovery bundle Symfony dan pemuatan resource.
NextPdfExtension::load(array $configs, ContainerBuilder $container)	Array konfigurasi pengguna dan container builder.	Memproses konfigurasi nextpdf, menyimpan parameter yang telah diselesaikan, memuat definisi layanan, dan memeriksa extension yang diperlukan.	void	Kesalahan validasi konfigurasi, pemuatan layanan, atau extension yang hilang.	Extension yang diperlukan adalah mbstring dan zlib.
NextPdfExtension::getAlias()	tidak ada.	Memakai nextpdf sebagai kunci konfigurasi root.	string	tidak ada yang diharapkan.	Konfigurasikan bundle di bawah nextpdf:.
Configuration::getConfigTreeBuilder()	tidak ada.	Mendefinisikan pohon konfigurasi nextpdf yang tervalidasi.	TreeBuilder	Kesalahan definisi konfigurasi Symfony.	Mencerminkan bentuk konfigurasi Laravel jika memungkinkan.
OptionalExtensionPass::process(ContainerBuilder $container)	Container builder Symfony.	Mendeteksi layanan Artisan dan Premium opsional serta mengubah flag ketersediaan factory.	void	Kesalahan wiring compiler pass.	Berjalan selama kompilasi container.

Kunci konfigurasi	Tipe	Perilaku standar	Catatan
page_format	enum	A4; nilai yang diizinkan mencakup A3, A5, Letter, Legal, dan Tabloid.	Berlaku untuk pembuatan dokumen standar.
orientation	enum	P; nilai yang diizinkan adalah P dan L.	Gunakan panggilan dokumen eksplisit ketika sebuah halaman memerlukan orientasi yang berbeda.
unit	enum	mm; nilai yang diizinkan adalah pt, mm, cm, dan in.	Menjaga nilai standar framework tetap selaras dengan unit inti.
pdfa	`string	null`	null; nilai yang diizinkan adalah 4, 4e, dan 4f.
fonts_path / cache_path	string	Jalur font proyek dan jalur cache kernel.	Pastikan setiap jalur dapat dibaca atau ditulis sesuai peran runtime-nya.
signature.*	array	Dinonaktifkan secara standar dengan level tanda tangan B-B.	Menyediakan sertifikat, kunci, kata sandi, sertifikat tambahan, dan level.
tsa.*	array	Dinonaktifkan ketika Uniform Resource Locator (URL) bernilai null; timeout standarnya 30 detik.	Mendukung kredensial, berkas mutual Transport Layer Security (mTLS), pin kunci publik, dan kebijakan HTTP.
ocsp_cache.*	array	Diaktifkan dengan time to live (TTL) 86400 detik.	Digunakan oleh alur validasi dan tanda tangan jangka panjang ketika tersedia.
messenger.*	array	Transport async, timeout 120, percobaan ulang 3.	Digunakan oleh alur kerja pembuatan asinkron.
artisan.*	array	Renderer Chrome dinonaktifkan kecuali dikonfigurasi dan terpasang.	Memetakan ke ChromeRendererConfig ketika renderer opsional tersedia.
defaults.*	array	Creator NextPDF, author kosong, language en, margin, dan font standar.	Diterapkan oleh PdfFactory::create().

Respons HTTP

Gunakan tabel ini untuk memilih helper respons berdasarkan mode tampilan dan buffering: inline atau unduhan, buffered atau streamed. Tabel ini juga menunjukkan perilaku nama berkas dan header.

Simbol	Parameter	Perilaku standar	Mengembalikan	Memunculkan atau gagal dengan	Catatan
PdfResponse::inline(Document $document, string $filename = 'document.pdf')	document: dokumen yang telah dibangun; filename: nama berkas respons.	Menambahkan .pdf jika belum ada.	Symfony\Component\HttpFoundation\Response	Kesalahan serialisasi inti.	Menetapkan tipe konten PDF dan header defensif.
PdfResponse::download(Document $document, string $filename = 'document.pdf')	Sama seperti inline; disposisi adalah attachment.	Respons unduhan untuk browser.	Response	Sama seperti inline.	Gunakan untuk unduhan eksplisit.
PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')	Sama seperti inline.	Mengirimkan byte PDF yang telah dimaterialisasi dalam potongan-potongan.	StreamedResponse	Sama seperti inline.	Tidak menghindari materialisasi dokumen.
PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')	Sama seperti streamInline; disposisi adalah attachment.	Respons unduhan streamed.	StreamedResponse	Sama seperti streamInline.	Terapkan kebijakan ukuran keluaran sebelum render.

Messenger

Gunakan tabel ini untuk jalur asinkron: DTO message yang Anda kirim, antarmuka builder yang Anda implementasikan, dan handler yang berjalan di worker.

Simbol	Parameter	Perilaku standar	Mengembalikan	Memunculkan atau gagal dengan	Catatan
new GeneratePdfMessage(string $builderClass, string $outputPath, array $builderContext = [])	builderClass: class-string yang mengimplementasikan PdfBuilderInterface; outputPath: target .pdf; builderContext: data yang dapat diserialisasi.	Array konteks kosong.	DTO message.	InvalidArgumentException untuk fully qualified class name (FQCN) yang tidak valid, stream wrapper, null byte, traversal, jalur kosong, atau target non-.pdf.	Transport Messenger membawa data, bukan closure.
PdfBuilderInterface::build(Document $document, array $context): Document	document: dokumen baru yang telah dikonfigurasi; context: data message yang dapat diserialisasi.	Tidak ada konteks standar selain nilai message.	Document yang telah dikonfigurasi.	Pengecualian spesifik builder.	Buat builder yang deterministik dan idempoten.
new GeneratePdfHandler(PdfFactory $pdfFactory, ContainerInterface $builderLocator)	Factory PDF dan service locator untuk builder bertag.	Tidak ada dokumen yang dibuat saat konstruksi.	GeneratePdfHandler	Kesalahan wiring container.	Locator sebaiknya hanya mengekspos implementasi PdfBuilderInterface.
GeneratePdfHandler::__invoke(GeneratePdfMessage $message)	message: DTO message yang tervalidasi.	Mengambil builder dari container, membangun dokumen, lalu menyimpannya.	void	Layanan builder yang hilang, hasil builder yang tidak valid, kesalahan tulis inti.	Utamakan builder berbasis layanan ketimbang callback statis.

Catatan pengembangan

• Jangan menyimpan Document sebagai layanan. Simpan PdfFactory dan panggil create() untuk setiap unit kerja.
• Masukkan ke antrean hanya konteks yang dapat diserialisasi. Jangan memasukkan stream terbuka, closure, atau objek request ke dalam builderContext.
• Gunakan kebijakan jalur keluaran yang lebih ketat dari DTO ketika deployment memiliki root penyimpanan khusus tenant.