Template

Sekilas pandang

NextPDF\Pro\Template mengurai sebuah definisi template JSON menjadi value object bertipe dan mengikat sebuah array data asosiatif ke placeholder-nya dengan pemformatan yang sadar-tipe. Modul ini menghasilkan hasil binding terstruktur; modul ini tidak merender PDF itu sendiri.

Ketersediaan & lisensi

Kapabilitas ini disertakan dalam NextPDF Pro (nextpdf/pro) dan aktif dengan sebuah envelope lisensi tier Pro. Sebuah deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Tidak ada flag kapabilitas runtime tambahan yang menggerbang modul ini di luar lisensi tier. Bandingkan edisi dan dapatkan lisensi.

Pemasangan

composer require nextpdf/pro:^3

Tinjauan konseptual

Sebuah template adalah dokumen JSON yang mendeskripsikan setup halaman dan sebuah daftar placeholder berposisi. TemplateParser memvalidasi JSON dan menghasilkan sebuah TemplateDefinition imutabel. Validasi bersifat ketat: ia memeriksa ukuran halaman terhadap daftar-izin (A3–A6, B4, B5, Letter, Legal, Tabloid), orientasi (P atau L), serta nama, tipe, dan koordinat numerik setiap placeholder, dan ia menolak nama placeholder duplikat.

TemplateDataBinder mengikat sebuah array data (dicocokkan tanpa membedakan huruf besar-kecil dengan nama placeholder) dan memformat setiap nilai berdasarkan PlaceholderType:

• Text / Image / Barcode — nilai diteruskan apa adanya sebagai string.
• Date — diformat dengan format placeholder (default Y-m-d), menerima string, timestamp Unix, atau DateTimeInterface.
• Number — number_format dengan desimal dari format (default 2).
• Currency — angka diformat dengan string format sebagai prefiks (default $).
• Conditional — "true" atau "false" berdasarkan kebenaran (truthiness).

Hasilnya adalah sebuah BindingResult yang membawa nilai yang di-bind, daftar field wajib yang hilang, dan peringatan pemformatan apa pun. Mengubah nilai yang di-bind menjadi PDF yang dirender adalah tanggung jawab pemanggil, menggunakan API document dan writer Core serta referensi backgroundPdf opsional.

Mengapa dirancang demikian

Parser adalah satu-satunya gerbang otoritatif. Ia mengubah JSON tak-tepercaya menjadi TemplateDefinition yang imutabel dan sepenuhnya bertipe, lalu binding berjalan sebagai fungsi murni dari value tersebut. Setiap field yang kelak mencapai sink pemformatan telah masuk daftar-izin dan dibatasi panjangnya pada waktu parse. Ukuran halaman, orientasi, presisi angka, dan karakter kontrol semua gagal di sini, bukan di tengah render. String tanggal dicocokkan terhadap sekumpulan format kanonis yang tetap, sehingga nilai seperti now atau +1 year tidak dapat membuat output bergantung pada wall clock. Modul ini berhenti secara sengaja pada sebuah BindingResult dan menyerahkan perenderan, resolusi path, dan kompositing latar ke pemanggil, yang menjaga batas kepercayaan tetap eksplisit.

Latar belakang desain: Invoice dan e-invoicing.

Kontrak perilaku

• Input. Sebuah string JSON (TemplateParser) dan sebuah array data (TemplateDataBinder).
• Output. TemplateDefinition dari penguraian; BindingResult dari binding.
• Validasi. validate() mengembalikan daftar galat yang dapat dibaca manusia dan tidak pernah melempar; parse() melempar InvalidArgumentException ketika validasi gagal.
• Data hilang. Sebuah placeholder tanpa data dan dengan default kosong dilaporkan dalam missingFields; placeholder dengan default tidak-kosong menggunakan default.
• Determinisme. Penguraian dan binding adalah fungsi murni dari inputnya.

Permukaan API publik

Tipe	Jenis	Anggota utama
NextPDF\Pro\Template\TemplateParser	final class	parse(string $json): TemplateDefinition, validate(string $json): list<string>
NextPDF\Pro\Template\TemplateDataBinder	final class	bind(TemplateDefinition $template, array $data): BindingResult
NextPDF\Pro\Template\TemplateDefinition	final readonly class	string $name, string $pageSize, string $orientation, array $placeholders, string $backgroundPdf, getPlaceholder(string $name): ?TemplatePlaceholder, requiredFields(): list<string>
NextPDF\Pro\Template\TemplatePlaceholder	final readonly class	nama, PlaceholderType $type, koordinat, default, format
NextPDF\Pro\Template\BindingResult	final readonly class	array $bindings, array $missingFields, array $warnings
NextPDF\Pro\Template\PlaceholderType	enum	Text, Image, Barcode, Date, Number, Currency, Conditional; requiresFormatting(): bool

Contoh kode — Mulai cepat

<?php

declare(strict_types=1);

use NextPDF\Pro\Template\TemplateDataBinder;
use NextPDF\Pro\Template\TemplateParser;

$json = '{"name":"Invoice","pageSize":"A4","orientation":"P","placeholders":'
 . '[{"name":"total","type":"currency","x":400,"y":700,"width":120,'
 . '"height":18,"format":"$"}]}';

$template = (new TemplateParser())->parse($json);
$result = (new TemplateDataBinder())->bind($template, ['total' => 1299.5]);

foreach ($result->bindings as $bound) {
 echo $bound->placeholder->name, ' => ', $bound->formattedValue, "\n";
}

Contoh kode — Produksi

<?php

declare(strict_types=1);

use NextPDF\Pro\Template\TemplateDataBinder;
use NextPDF\Pro\Template\TemplateParser;

function bindOrReject(string $json, array $data): array
{
 $parser = new TemplateParser();

 $errors = $parser->validate($json);
 if ($errors !== []) {
 throw new InvalidArgumentException(implode('; ', $errors));
 }

 $template = $parser->parse($json);
 $result = (new TemplateDataBinder())->bind($template, $data);

 if ($result->missingFields !== []) {
 throw new RuntimeException(
 'missing required fields: ' . implode(', ', $result->missingFields),
 );
 }

 return $result->bindings; // hand to the renderer
}

Kasus tepi & jebakan

• Sebuah string tanggal yang tidak dapat diurai menghasilkan peringatan dan string asli dipertahankan, alih-alih melempar.
• String format mata uang digunakan sebagai prefiks literal (misalnya "$" atau "EUR "), bukan sebagai pengenal locale.
• backgroundPdf adalah referensi path yang dibawa pada definisi; modul ini tidak membuka, memvalidasi, atau mengompositkannya — itu adalah tugas perender.
• Nama placeholder dicocokkan tanpa membedakan huruf besar-kecil; nama duplikat di dalam JSON adalah galat validasi.

Performa

Penguraian adalah satu decode JSON ditambah validasi struktural; binding bersifat linear terhadap jumlah placeholder. Lihat performance_budget.

Catatan keamanan

JSON di-decode dengan JSON_THROW_ON_ERROR dan divalidasi terhadap daftar-izin tetap sebelum sebuah TemplateDefinition dikonstruksi. Modul ini tidak melakukan I/O berkas atau jaringan; path backgroundPdf tidak didereferensi di sini, sehingga penanganan path dan kendali akses menjadi milik perender.

Kesesuaian

Modul ini tidak memiliki permukaan spesifikasi-PDF langsung: ia mengurai sebuah template JSON dan memformat nilai. Kosakata ukuran-halaman dan orientasi adalah konvensi NextPDF, bukan konstruksi PDF normatif.

Fallback / alternatif Core

Tidak ada lapisan definisi-template Core. Untuk konstruksi dokumen yang sepenuhnya imperatif, gunakan API document dan writer Core sumber terbuka secara langsung. Lihat /modules/core/document/.

Catatan batas Enterprise

Modul ini mendefinisikan dan mengikat template. Modul ini tidak melakukan orkestrasi mail-merge, penjadwalan batch job, atau perenderan; urusan itu berada di luar cakupan dan ditangani di tempat lain.

Batas publikasi

Halaman ini hanya mendokumentasikan perilaku yang dapat diamati dari luar dan permukaan API publik yang didukung. Jalur namespace internal, kelas helper, tabel mekanisme, nama berkas runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Template reference
• Toc
• Merge
• Model document Core