Panduan pengembang CodeIgniter

Gambaran umum

Paket CodeIgniter menyediakan service factory, fungsi helper, dan pembungkus pustaka Pdf yang ringan untuk satu dokumen Portable Document Format (PDF). Gunakan pembungkus tersebut di controller. Job antrean menggunakan callable builder statis karena payload antrean CodeIgniter harus berupa data yang dapat diserialisasi.

Gunakan panduan ini untuk merancang alur controller, service, builder antrean, dan pengujian seputar nextpdf/codeigniter.

Batasan arsitektur

Lapisan	Dimiliki oleh	Tanggung jawab	Jangan tempatkan di sini
Controller	Aplikasi	Melakukan otorisasi, memanggil builder atau service, lalu mengembalikan sebuah DownloadResponse.	Logika tata letak bersama.
Pembungkus pustaka	nextpdf/codeigniter	Membungkus satu Document serta menyediakan helper untuk response dan save.	Penyimpanan dokumen berumur panjang.
Service factory	nextpdf/codeigniter	Membuat registry bersama dan dokumen baru.	Root penyimpanan khusus bisnis.
Builder antrean	Aplikasi	Membangun dokumen dari input callable statis.	Objek request atau state yang tidak dapat diserialisasi.
Mesin inti	nextpdf/nextpdf	Membangun dan menyerialisasi PDF.	Kebijakan response atau antrean CodeIgniter.

Siklus hidup runtime

Tahap	Perilaku	Tindakan pengembang
Registrasi autoload	Registrar::Autoload() mendaftarkan pemuatan helper untuk modul.	Muat modul melalui konfigurasi CodeIgniter.
Resolusi service	Secara default, Services::pdf() mengembalikan pembungkus untuk dokumen baru.	Lakukan resolusi satu kali per request.
Penyusunan	Kode aplikasi menggunakan Pdf::document() untuk panggilan ke dokumen inti.	Tempatkan kode pembangun dokumen di dalam service atau builder.
Response	PdfResponse mengembalikan sebuah DownloadResponse.	Biarkan paket mengatur header PDF.
Eksekusi antrean	GeneratePdfJob::process() memvalidasi builder dan jalur output, lalu menyimpan.	Tempatkan builder antrean di bawah App\PdfBuilders.

Struktur aplikasi yang direkomendasikan

Jalur	Tujuan
app/PdfBuilders/*	Builder statis yang aman untuk antrean yang diterima oleh GeneratePdfJob.
app/Libraries/*	Pembungkus aplikasi opsional di sekitar alur kerja dokumen yang berulang.
app/Services/*	Pengambilan data domain dan kebijakan penyimpanan.
app/Config/NextPdf.php	Override aplikasi untuk konfigurasi paket.
tests/app/PdfBuilders/*	Pengujian builder dan payload antrean.

Gunakan helper paket untuk alur yang ringkas. Gunakan panggilan service eksplisit saat konstruksi dokumen berada di kelas yang dapat Anda uji langsung.

<?php

namespace App\Controllers;

final class InvoiceController extends BaseController
{
    public function download(int $id)
    {
        $pdf = pdf();
        $pdf->document()
            ->setTitle('Invoice ' . $id)
            ->addPage()
            ->writeHtml('<h1>Invoice ' . $id . '</h1>');

        return $pdf->download('invoice-' . $id . '.pdf');
    }
}

Pola builder antrean

Builder antrean sebaiknya statis, deterministik, dan ditempatkan di bawah App\PdfBuilders. Jaga agar array konteks tetap sederhana agar dapat diserialisasi dan diaudit.

<?php

namespace App\PdfBuilders;

use NextPDF\Core\Document;

final class InvoiceBuilder
{
    public static function build(Document $document, array $context): Document
    {
        $document->setTitle((string) $context['title'])
            ->addPage()
            ->writeHtml((string) $context['html']);

        return $document;
    }
}

Job tersebut membatasi output ke direktori PDF aplikasi yang telah dikonfigurasi. Jika aplikasi Anda memerlukan penyimpanan khusus per-tenant, letakkan kebijakan itu di satu service, lalu uji sebelum mengirim job.

Titik ekstensi

Titik ekstensi	Gunakan untuk	Batasan
Services::pdfDocument()	Sesuaikan pembuatan dokumen.	Harus mengembalikan dokumen baru.
Services::fontRegistry()	Lakukan pemanasan fon dan akses registry.	Tolak jalur yang tidak aman, dan pastikan registry tetap terkunci setelah pemanasan.
Services::pdfSigner()	Aktifkan penandatanganan digital opsional.	Kembalikan null ketika penandatanganan dinonaktifkan.
NextPDF\CodeIgniter\Libraries\Pdf	Membungkus pekerjaan dokumen untuk controller.	Satu pembungkus dipetakan ke satu dokumen.
App\PdfBuilders::*	Builder dokumen yang aman untuk antrean.	String callable statis diperlukan.
app/Config/NextPdf.php	Default aplikasi dan pengaturan integrasi.	Jaga agar nilai produksi tetap eksplisit.

Alur kerja pengembangan

1. Mulailah dengan controller yang memanggil pdf() atau service('pdf').
2. Pindahkan konstruksi dokumen yang berulang ke app/PdfBuilders atau service aplikasi.
3. Gunakan GeneratePdfJob saat proses pembuatan terlalu lambat untuk jalur request.
4. Jaga agar konteks antrean tetap dapat diserialisasi dan kecil.
5. Simpan output di bawah akar penyimpanan PDF yang disetujui, kecuali Anda sengaja memperluas kebijakan tersebut.
6. Tambahkan pengujian untuk helper, service, payload antrean, dan jalur yang tidak aman.

Penanganan kegagalan

Kegagalan	Tempat yang seharusnya menangani	Respons yang direkomendasikan
Ekstensi tidak tersedia atau jalur fon tidak aman	Service factory.	Fail fast saat resolusi service.
Callable builder tidak valid	Validasi job antrean.	Tolak job tersebut dan catat string builder tanpa rahasia.
Jalur output tidak aman	Service penyimpanan dan job antrean.	Tolak sebelum pengiriman, dan pertahankan validasi job.
Kesalahan serialisasi response	Penanganan kesalahan controller atau framework.	Jangan mengirim isi response parsial.
Kelas Premium opsional tidak tersedia	Nilai kembalian metode service.	Tangani null secara eksplisit sebelum menggunakan fitur e-invoice opsional.

Default yang aman

Aspek	Default	Kapan melakukan override
Namespace builder antrean	App\PdfBuilders.	Pertahankan default kecuali Anda juga memperbarui kebijakan keamanan.
Akar output	WRITEPATH/pdfs.	Lakukan override hanya dengan allowlist yang lebih kuat.
Nama berkas response	document.pdf.	Gunakan nama berkas bisnis yang sudah dibersihkan.
Metode stream	Paritas application programming interface (API) dengan framework lain.	Jangan mengandalkan streaming sebagai batasan memori di CodeIgniter.
Service dokumen	Dokumen baru secara default.	Jangan meminta dokumen bersama dari kode request.

Daftar periksa pengujian

• Pengujian service memverifikasi bahwa tiap resolusi Services::pdf() mengembalikan dokumen yang independen.
• Pengujian helper memverifikasi bahwa pdf() dan pdf_document() mengembalikan objek baru.
• Pengujian response memverifikasi header dan normalisasi nama berkas.
• Pengujian antrean mencakup kasus string builder tidak valid dan jalur output tidak aman.
• Pengujian builder menggunakan data konteks yang representatif.
• Pengujian konfigurasi mencakup status jalur fon, jalur cache, penandatanganan dinonaktifkan, dan Time-Stamp Authority (TSA) dinonaktifkan.