Mengonfigurasi NextPDF untuk CodeIgniter 4

Sekilas

Konfigurasi NextPDF dikelola oleh NextPDF\CodeIgniter\Config\NextPdf, sebuah subkelas BaseConfig milik CodeIgniter. Anda dapat mengganti nilainya dengan memperluas kelas tersebut di app/Config/ atau menetapkan kunci .env berawalan nextpdf.. Nilai standarnya berfungsi tanpa konfigurasi tambahan.

Gambaran konsep

NextPdf merupakan BaseConfig bertipe. Kelas ini sengaja dibuat tidak final. Di CodeIgniter, konfigurasi aplikasi memperluas kelas paket agar aplikasi Anda dapat mengganti nilai standar. Saat CodeIgniter membangun konfigurasi, BaseConfig menerapkan penggantian dari lingkungan untuk setiap properti publik, termasuk kunci array bersarang.

Jalur standar untuk fon dan cache menggunakan konstanta WRITEPATH milik CodeIgniter: WRITEPATH . 'fonts' dan WRITEPATH . 'cache/nextpdf'.

Kunci konfigurasi

Semua kunci di bawah ini adalah properti publik dari NextPdf. Nilai standarnya diverifikasi terhadap sumber paket.

Nilai standar halaman dan dokumen

Kunci	Tipe	Standar	Deskripsi
`pageFormat`	`string`	`A4`	Format halaman.
`orientation`	`string`	`P`	`P` potret atau `L` lanskap.
`unit`	`string`	`mm`	Satuan ukuran.
`defaults.creator`	`string`	`NextPDF`	Metadata pembuat Portable Document Format (PDF).
`defaults.author`	`string`	`''`	Metadata penulis; dilewati jika kosong.
`defaults.language`	`string`	`en`	Tag bahasa dokumen.
`defaults.margin_top`	`float`	`10.0`	Margin atas.
`defaults.margin_right`	`float`	`10.0`	Margin kanan.
`defaults.margin_bottom`	`float`	`10.0`	Margin bawah.
`defaults.margin_left`	`float`	`10.0`	Margin kiri.
`defaults.font_family`	`string`	`dejavusans`	Famili fon standar.
`defaults.font_size`	`float`	`12.0`	Ukuran fon standar.
`defaults.trim_box`	`list<float>\|null`	`null`	Trim box, jika ditetapkan.
`defaults.bleed_box`	`list<float>\|null`	`null`	Bleed box, jika ditetapkan.

Paket menerapkan defaults.creator dan defaults.language pada setiap dokumen. Paket hanya menerapkan defaults.author jika nilainya tidak kosong.

Jalur dan cache

Kunci	Tipe	Standar	Deskripsi
`fontsPath`	`string`	`WRITEPATH/fonts`	Direktori berkas fon.
`cachePath`	`string`	`WRITEPATH/cache/nextpdf`	Direktori cache.
`preloadFonts`	`list<string>`	`[]`	Jalur fon absolut yang dipramuat saat boot.
`imageCacheMb`	`int`	`50`	Anggaran cache citra least recently used (LRU) dalam megabita (MB).
`fontCacheLocking`	`bool`	`true`	Kunci cache fon setelah pemanasan awal.

Registri fon menolak setiap fontsPath yang berisi stream wrapper (://) atau null byte, lalu melempar kesalahan runtime. Lihat /integrations/codeigniter/security-and-operations/.

Pengarsipan dan warna (NextPDF Pro)

Kunci	Tipe	Standar	Deskripsi
`pdfa`	`string\|null`	`null`	Versi PDF/A: `4`, `4e`, `4f`.
`iccProfile.rgb`	`string\|null`	`null`	Jalur profil International Color Consortium (ICC) untuk ruang warna merah, hijau, dan biru (RGB).
`iccProfile.cmyk`	`string\|null`	`null`	Jalur profil ICC untuk ruang warna cyan, magenta, kuning, dan key (CMYK).

pdfa hanya berlaku jika NextPDF Pro terpasang dan kapabilitas pengarsipan tersedia. Jika hanya core yang terpasang, kunci ini diabaikan.

Tanda tangan digital (NextPDF Pro / Enterprise)

Kunci	Tipe	Standar	Deskripsi
`signature.enabled`	`bool`	`false`	Aktifkan layanan penanda tangan.
`signature.certificate`	`string\|null`	`null`	Jalur berkas sertifikat.
`signature.private_key`	`string\|null`	`null`	Jalur berkas kunci privat.
`signature.password`	`string`	`''`	Kata sandi kunci privat.
`signature.extra_certs`	`list<string>`	`[]`	Jalur sertifikat rantai tambahan.
`signature.level`	`string`	`B-B`	Pengidentifikasi tingkat tanda tangan.

Services::pdfSigner() mengembalikan null kecuali signature.enabled bernilai true dan signature.certificate tidak kosong. Tingkat standar adalah B-B. NextPDF Pro menyediakan tanda tangan baseline B-B. Tingkat validasi jangka panjang merupakan kapabilitas Enterprise terpisah dan didokumentasikan dalam referensi Premium, bukan di sini.

PDF Advanced Electronic Signatures (PAdES) B-T dihasilkan oleh mesin Core. Integrasi CodeIgniter sendiri tidak menambahkan B-T, dan Pro hanya menyediakan baseline B-B. Dokumentasi ini akan diperbarui jika dan ketika Pro B-T dirilis.

Time Stamp Authority

Kunci	Tipe	Standar	Deskripsi
`tsa.url`	`string\|null`	`null`	URL endpoint Time Stamp Authority (TSA).
`tsa.username`	`string`	`''`	Nama pengguna untuk autentikasi dasar TSA.
`tsa.password`	`string`	`''`	Kata sandi autentikasi dasar TSA.
`tsa.cert`	`string\|null`	`null`	Jalur sertifikat klien.
`tsa.key`	`string\|null`	`null`	Jalur kunci klien.
`tsa.timeout`	`int`	`30`	Batas waktu permintaan dalam detik.
`tsa.pinned_public_keys`	`list<string>`	`[]`	Kunci publik TSA yang di-pin.
`tsa.warn_on_key_rotation`	`bool`	`true`	Peringatkan saat rotasi kunci TSA.
`tsa.allow_insecure_http`	`bool`	`false`	Izinkan HTTP teks polos ke TSA.

Services::tsaClient() mengembalikan null saat tsa.url bernilai null atau string kosong. Jika Anda memilih tingkat tanda tangan yang memerlukan stempel waktu, penanda tangan melampirkan klien TSA secara otomatis.

Cache OCSP

Kunci	Tipe	Standar	Deskripsi
`ocspCache.enabled`	`bool`	`true`	Aktifkan cache respons Online Certificate Status Protocol (OCSP).
`ocspCache.ttl`	`int`	`86400`	Time to live (TTL) cache dalam detik.
`ocspCache.directory`	`string\|null`	`null`	Direktori cache; standar mesin jika null.

Perender HTML Chrome (NextPDF Artisan)

Kunci	Tipe	Standar	Deskripsi
`artisan.chrome_binary`	`string\|null`	`null`	Jalur biner Chrome/Chromium.
`artisan.render_timeout`	`int`	`30`	Batas waktu render dalam detik.
`artisan.default_css`	`string`	`''`	Lembar gaya standar.
`artisan.no_sandbox`	`bool`	`false`	Teruskan `--no-sandbox` ke Chrome.
`artisan.max_html_size`	`int`	`5000000`	Ukuran maksimum HTML masukan dalam bita.

Perender Chrome hanya dikonfigurasi untuk dokumen jika artisan.chrome_binary sudah ditetapkan dan nextpdf/artisan terpasang.

Penggantian dengan `.env`

BaseConfig menerapkan penggantian dari lingkungan per properti. Kunci yang dicari adalah nama kelas pendek dalam huruf kecil, nextpdf, diikuti jalur properti. Gunakan titik untuk mengakses kunci array bersarang. Bentuk bertitik maupun bergaris bawah sama-sama diterima.

nextpdf.fontsPath = /var/www/writable/fonts
nextpdf.imageCacheMb = 100
nextpdf.signature.enabled = true
nextpdf.signature.certificate = /etc/nextpdf/cert.pem
nextpdf.signature.private_key = /etc/nextpdf/key.pem
nextpdf.tsa.url = https://tsa.example.com/timestamp
nextpdf.artisan.chrome_binary = /usr/bin/chromium
nextpdf.defaults.creator = Acme Billing
nextpdf.defaults.language = zh-TW

Awalannya berupa nama kelas pendek dalam huruf kecil. Awalan ini tetap nextpdf meskipun kelasnya ditulis NextPdf. Anda juga dapat menggunakan bentuk yang sepenuhnya terkualifikasi (NextPDF\CodeIgniter\Config\NextPdf.fontsPath).

Penggantian dengan memperluas kelas

Untuk konfigurasi yang bertipe dan terkontrol versi, perluas kelas paket di app/Config/. CodeIgniter memuat kelas aplikasi alih-alih nilai standar paket. Berkas ini mendeklarasikan sebuah kelas dan tidak menimbulkan efek samping. Hal ini menjaganya tetap selaras dengan ekspektasi PSR-1 bahwa sebuah berkas mendeklarasikan simbol atau menjalankan logika berefek samping, tetapi tidak keduanya (PSR-1 §x1.x1.p3).

<?php

declare(strict_types=1);

namespace Config;

use NextPDF\CodeIgniter\Config\NextPdf as BaseNextPdf;

final class NextPdf extends BaseNextPdf
{
    public int $imageCacheMb = 100;

    public string $fontsPath = WRITEPATH . 'fonts';

    /** @var array{creator: string, author: string, language: string, margin_top: float, margin_right: float, margin_bottom: float, margin_left: float, font_family: string, font_size: float, trim_box: list<float>|null, bleed_box: list<float>|null} */
    public array $defaults = [
        'creator' => 'Acme Billing',
        'author' => 'Acme, Inc.',
        'language' => 'en',
        'margin_top' => 12.0,
        'margin_right' => 12.0,
        'margin_bottom' => 12.0,
        'margin_left' => 12.0,
        'font_family' => 'dejavusans',
        'font_size' => 11.0,
        'trim_box' => null,
        'bleed_box' => null,
    ];
}

Kasus khusus & jebakan

Mengganti satu kunci bersarang dengan .env hanya mengubah kunci itu saja; sisa array mempertahankan nilai standarnya.
Nilai .env berupa string. CodeIgniter mengonversi true/false dan string numerik. Beri tanda kutip pada nilai yang harus tetap menjadi string literal.
Jika Anda memperluas kelas dengan array defaults parsial, seluruh array akan diganti. Sertakan setiap kunci, seperti ditunjukkan di atas.

Catatan keamanan

Jauhkan jalur sertifikat dan kunci dari kendali sumber. Sediakan melalui .env atau pengelola rahasia. tsa.allow_insecure_http harus tetap false di produksi. Lihat /integrations/codeigniter/security-and-operations/.

Konformitas

Berkas ekstensi konfigurasi aplikasi mendeklarasikan satu kelas dan tidak memiliki efek samping (PSR-1 §x1.x1.p3).

Konteks komersial

Core NextPDF berlisensi Apache-2.0. Kunci signature.* dan pdfa hanya berlaku jika NextPDF Pro atau Enterprise terpasang. Paket CodeIgniter mengekspos metode layanan yang sesuai. Metode tersebut mengembalikan null hingga Anda memasang paket Premium yang sesuai. Lihat </get-license/?intent=codeigniter-signing>.

Lihat juga

/integrations/codeigniter/install/ — pasang paketnya.
/integrations/codeigniter/quickstart/ — PDF pertama.
/integrations/codeigniter/production-usage/ — kontroler dan job antrean yang terhubung melalui DI.
/integrations/codeigniter/security-and-operations/ — pengerasan konfigurasi penandatanganan dan jalur.