Referensi API CodeIgniter

Sekilas

Paket CodeIgniter menyediakan API kecil yang digunakan dari controller. Paket ini menyertakan pembungkus pustaka Pdf untuk satu dokumen (Services::pdf() dan helper global pdf()), helper respons yang mengubah dokumen yang sudah dibangun menjadi DownloadResponse (PdfResponse), factory Services yang mendasarinya (registry fon dan gambar, factory dokumen, serta penanda tangan opsional dan klien otoritas penanda waktu (TSA)), kelas konfigurasi NextPdf, dan GeneratePdfJob untuk pembuatan asinkron melalui callable builder statis.

Mulailah dari alur controller utama: panggil Services::pdf() (atau helper pdf()), tambahkan konten ke $pdf->document(), lalu kembalikan $pdf->download('file.pdf'). Alur tersebut mencakup kasus umum. Tabel referensi disusun berdasarkan area API; Tugas umum menampilkan contoh yang siap dijalankan terlebih dahulu.

Tugas umum

Berikut adalah alur produksi yang paling umum. Setiap contoh telah diverifikasi terhadap kode sumber nextpdf/codeigniter.

Gunakan alur render kanonis untuk mengembalikan berkas Portable Document Format (PDF) yang dapat diunduh dari controller:

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;
use NextPDF\CodeIgniter\Config\Services;

final class InvoiceController extends BaseController
{
    public function download(int $id): DownloadResponse
    {
        $pdf = Services::pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, "Invoice #{$id}");

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

Fungsinya: menyiapkan Pdf baru di sekitar Document baru, menulis satu sel, lalu mengembalikan DownloadResponse dengan disposisi attachment dan header keamanan paket.

Pratinjau PDF secara inline di peramban dengan pembungkus yang sama dan inline() alih-alih download():

<?php

declare(strict_types=1);

namespace App\Controllers;

use CodeIgniter\HTTP\DownloadResponse;

final class ReportController extends BaseController
{
    public function preview(): DownloadResponse
    {
        $pdf = pdf();
        $pdf->document()->addPage();
        $pdf->document()->cell(0, 10, 'Monthly Report');

        return $pdf->inline('report.pdf');
    }
}

Fungsinya: menggunakan helper global pdf() (setara dengan Services::pdf()) dan mengembalikan DownloadResponse dengan disposisi inline sehingga peramban menampilkan PDF alih-alih mengunduhnya.

Hasilkan PDF secara asinkron di antrean dengan GeneratePdfJob dan builder statis:

<?php

declare(strict_types=1);

use NextPDF\CodeIgniter\Jobs\GeneratePdfJob;

service('queue')->push('pdf', GeneratePdfJob::class, [
    'builder'    => 'App\PdfBuilders\InvoiceBuilder::build',
    'outputPath' => WRITEPATH . 'pdfs/invoice-42.pdf',
    'context'    => ['invoice_id' => 42],
]);

Fungsinya: memasukkan pembuatan ke antrean. Worker memvalidasi builder (harus berupa callable statis App\PdfBuilders\...::method) dan jalur keluaran (harus berada di bawah WRITEPATH/pdfs/ dan berakhiran .pdf), membangun dokumen baru, lalu menyimpannya.

Pembungkus pustaka

Gunakan tabel ini ketika Anda memiliki pembungkus Pdf dan membutuhkan metode respons atau penyimpanan.

Simbol	Parameter	Perilaku standar	Mengembalikan	Melempar atau gagal dengan	Catatan
`NextPDF\CodeIgniter\Libraries\Pdf` / `new Pdf(Document $document)`	`document`: dokumen inti baru.	Membungkus dokumen yang diberikan untuk satu operasi respons atau penyimpanan.	`Pdf`	Tidak ada yang diharapkan.	Jangan gunakan ulang pembungkus setelah keluaran dihasilkan.
`Pdf::document()`	tidak ada.	Mengembalikan dokumen yang dibungkus.	`NextPDF\Core\Document`	Tidak ada yang diharapkan.	Gunakan ini untuk memanggil API penulisan inti.
`Pdf::inline(string $filename = 'document.pdf')`	`filename`: nama berkas respons.	Menggunakan disposisi inline peramban.	`CodeIgniter\HTTP\DownloadResponse`	Galat serialisasi inti.	Mendelegasikan ke `PdfResponse::inline()`.
`Pdf::download(string $filename = 'document.pdf')`	`filename`: nama berkas respons.	Menggunakan disposisi attachment peramban.	`DownloadResponse`	Galat serialisasi inti.	Mendelegasikan ke `PdfResponse::download()`.
`Pdf::streamInline(string $filename = 'document.pdf')`	`filename`: nama berkas respons.	Menyediakan kesetaraan API dengan paket framework lainnya.	`DownloadResponse`	Galat serialisasi inti.	CodeIgniter menangani keluaran biner secara native.
`Pdf::streamDownload(string $filename = 'document.pdf')`	`filename`: nama berkas respons.	Menyediakan kesetaraan API dengan paket framework lainnya.	`DownloadResponse`	Galat serialisasi inti.	Gunakan kontrol ukuran yang sama seperti pada respons non-streaming.
`Pdf::save(string $path)`	`path`: target sistem berkas.	Menulis dokumen yang dibungkus.	`void`	Galat penulisan sistem berkas atau inti.	Validasi root penyimpanan sebelum menyimpan.

Layanan dan helper

Gunakan tabel ini ketika Anda membutuhkan factory layanan tertentu atau fungsi helper global, termasuk perilaku shared-service dan tipe kembaliannya.

Simbol	Parameter	Perilaku standar	Mengembalikan	Melempar atau gagal dengan	Catatan
`Services::fontRegistry(bool $getShared = true)`	`getShared`: flag layanan bersama (shared-service) CodeIgniter.	Mengembalikan registry bersama, memuatnya dengan fon yang dikonfigurasi, lalu menguncinya.	`FontRegistryInterface`	`RuntimeException` untuk ekstensi yang hilang atau jalur fon yang tidak aman.	Menolak stream wrapper dan null byte pada `fontsPath`.
`Services::imageRegistry(bool $getShared = true)`	`getShared`: flag layanan bersama (shared-service).	Mengembalikan registry gambar bersama dengan batas least recently used (LRU).	`ImageRegistry`	Tidak ada yang diharapkan.	Ukuran cache dikontrol oleh `imageCacheMb`.
`Services::documentFactory(bool $getShared = true)`	`getShared`: flag layanan bersama (shared-service).	Mengembalikan factory bersama yang menggunakan registry bersama.	`DocumentFactoryInterface`	Galat penyiapan registry.	Factory dapat digunakan ulang; dokumen tidak.
`Services::tsaClient(bool $getShared = true)`	`getShared`: flag layanan bersama (shared-service).	Mengembalikan `null` ketika `tsa.url` kosong.	`TsaClient	null`	Galat klien Hypertext Transfer Protocol (HTTP) atau konfigurasi TSA.
`Services::pdfSigner(bool $getShared = false)`	`getShared`: flag layanan bersama (shared-service).	Mengembalikan `null` ketika penandatanganan dinonaktifkan.	`SignerInterface	null`	Galat sertifikat atau galat tingkat tanda tangan.
`Services::pdfDocument(bool $getShared = false)`	`getShared`: flag layanan bersama (shared-service).	Membuat dokumen baru, menerapkan nilai standar, dan secara opsional mengonfigurasi PDF/A atau Artisan.	`Document`	Galat ekstensi opsional atau konfigurasi dokumen.	Pertahankan nilai standar `false` demi keamanan permintaan.
`Services::pdf(bool $getShared = false)`	`getShared`: flag layanan bersama (shared-service).	Membuat pembungkus `Pdf` baru di sekitar dokumen baru.	`NextPDF\CodeIgniter\Libraries\Pdf`	Galat penyiapan dokumen.	Layanan utama yang menghadap ke controller.
`Services::eInvoiceEmbedder()`	tidak ada.	Mengembalikan `null` kecuali kelas embedder e-invoice Premium Pro tersedia.	`EmbedderInterface	null`	Galat konstruksi paket opsional.
`Services::eInvoiceValidator()`	tidak ada.	Mengembalikan `null` kecuali kelas validator Premium Enterprise tersedia.	`ValidatorInterface	null`	Galat konstruksi paket opsional.
`Services::eInvoiceProfile()`	tidak ada.	Mengembalikan profil EN16931 ketika Premium Pro terpasang.	`ProfileInterface	null`	Galat paket opsional.
`Services::schematronRunner()`	tidak ada.	Mengembalikan `null` kecuali validator Schematron Premium Enterprise tersedia.	`SchematronRunnerInterface	null`	Galat konstruksi paket opsional.
`Registrar::Autoload()`	tidak ada.	Menambahkan helper paket ke konfigurasi autoload CodeIgniter.	`array`	Tidak ada yang diharapkan.	Mengaktifkan `pdf()` dan `pdf_document()` ketika modul dimuat.
`pdf()`	tidak ada.	Memanggil `Services::pdf(false)`.	`Pdf`	Galat penyiapan dokumen.	Helper praktis untuk controller.
`pdf_document()`	tidak ada.	Memanggil `Services::pdfDocument(false)`.	`Document`	Galat penyiapan dokumen.	Helper praktis ketika API dokumen inti lebih dipilih.

Respons HTTP

Gunakan tabel ini ketika Anda sudah memiliki Document yang telah dibangun dan ingin membuat DownloadResponse sendiri alih-alih menggunakan pembungkus Pdf.

Simbol	Parameter	Perilaku standar	Mengembalikan	Melempar atau gagal dengan	Catatan
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: dokumen yang sudah dibangun; `filename`: nama berkas respons.	Memastikan ekstensi `.pdf` dan disposisi inline.	`DownloadResponse`	Galat serialisasi inti.	Menambahkan tipe konten PDF dan header defensif.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	Sama seperti `inline`; disposisinya adalah attachment.	Memastikan ekstensi `.pdf`.	`DownloadResponse`	Sama seperti `inline`.	Gunakan untuk unduhan peramban.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	Sama seperti `inline`.	Perilaku sama seperti `inline` pada CodeIgniter 4 (CI4).	`DownloadResponse`	Sama seperti `inline`.	Ada untuk kesetaraan API lintas framework.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	Sama seperti `download`.	Perilaku sama seperti `download` pada CI4.	`DownloadResponse`	Sama seperti `download`.	Ada untuk kesetaraan API lintas framework.

Job antrean

Gunakan tabel ini ketika Anda mengatur pembuatan asinkron dan membutuhkan kunci data job serta kontrak callable builder yang tepat.

Simbol	Parameter	Perilaku standar	Mengembalikan	Melempar atau gagal dengan	Catatan
`GeneratePdfJob::process()`	Kunci data job: `builder`, `outputPath`, dan `context` opsional.	Menggunakan array context kosong ketika tidak disertakan.	`void`	`InvalidArgumentException` untuk builder atau jalur keluaran yang tidak aman; galat penulisan inti.	Builder harus berupa `App\PdfBuilders\...\*::method`.
Callable builder	`Document $doc`, `array $context`.	Tidak ada context standar di luar data job.	`Document`	Eksepsi spesifik builder.	Memerlukan callable statis karena payload antrean CI4 adalah data terserialisasi.

Konfigurasi

Gunakan tabel ini ketika Anda mengubah nilai standar untuk format halaman, jalur, penandatanganan, TSA, atau metadata dokumen pada kelas konfigurasi NextPdf.

Properti	Tipe	Perilaku standar	Catatan
`pageFormat`	`string`	`A4`.	Menetapkan format halaman standar.
`orientation`	`string`	`P`.	Menetapkan orientasi standar.
`unit`	`string`	`mm`.	Menetapkan unit standar.
`pdfa`	`string	null`	`null`.
`fontsPath` / `cachePath`	`string`	`WRITEPATH . 'fonts'` dan `WRITEPATH . 'cache/nextpdf'`.	Pertahankan jalur di dalam penyimpanan yang dikontrol aplikasi.
`signature`	`array`	Dinonaktifkan dengan level `B-B`.	Sertifikat, kunci, kata sandi, sertifikat tambahan, dan level.
`tsa`	`array`	Dinonaktifkan ketika Uniform Resource Locator (URL) bernilai `null`; batas waktu 30 detik.	Kredensial, berkas mutual Transport Layer Security (mTLS), pin kunci publik, dan kebijakan HTTP.
`ocspCache`	`array`	Diaktifkan dengan time to live (TTL) selama 86400 detik.	Digunakan oleh alur validasi tanda tangan ketika tersedia.
`preloadFonts`	`list<string>`	Kosong.	Dimuat sebelum registry dikunci.
`imageCacheMb`	`int`	`50`.	Mengontrol cache gambar selama masa hidup proses.
`fontCacheLocking`	`bool`	`true`.	Menjaga mutasi registry fon agar berada di luar penanganan permintaan.
`artisan`	`array`	Penyaji Chrome dinonaktifkan kecuali dikonfigurasi dan terpasang.	Dipetakan ke `ChromeRendererConfig::fromArray()`.
`defaults`	`array`	Pembuat `NextPDF`, penulis kosong, bahasa `en`, margin standar, dan fon standar.	`Services::pdfDocument()` hanya menerapkan `creator`, `language`, dan (jika tidak kosong) `author`; `margin_top`/`right`/`bottom`/`left`, `font_family`, `font_size`, `trim_box`, dan `bleed_box` adalah nilai standar yang terdefinisi, tetapi saat ini belum diterapkan.

Catatan pengembangan

GeneratePdfJob membatasi keluaran ke WRITEPATH . 'pdfs' dan mensyaratkan .pdf.
Callable builder di luar App\PdfBuilders ditolak untuk mencegah eksekusi kode arbitrer dari payload antrean yang dimodifikasi.
Gunakan service('pdf') atau helper paket untuk alur controller; gunakan job antrean untuk pembuatan yang membutuhkan waktu lama.