Template — Referensi Mendalam

Sekilas pandang

Referensi mendalam ini mendokumentasikan skema templat JSON yang diterima, setiap aturan validasi, dan perilaku pemformatan per-tipe yang persis dari data binder. Modul ini mem-parse sebuah definisi templat, lalu mengikat data pemanggil ke placeholder bertipe. Modul memancarkan string yang diformat; modul tidak menggambar objek PDF.

Ketersediaan & lisensi

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

Permukaan API publik

Modul ini mengekspos dua layanan entry-point dan empat immutable value object. Setiap simbol di bawah ini bersifat publik dan stabil.

Simbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
TemplateParser::parse	string $json	Memvalidasi, lalu membangun definisi	TemplateDefinition	InvalidArgumentException ketika ada error validasi	Mendelegasikan ke validate terlebih dahulu.
TemplateParser::validate	string $json	Mengumpulkan semua error struktural dalam satu lintasan	list<string> (kosong bila valid)	Tidak pernah melempar; kegagalan decode JSON dikembalikan sebagai pesan	Gerbang otoritatif untuk batas panjang dan presisi.
TemplateDataBinder::bind	TemplateDefinition $template, array<string,mixed> $data	Mencocokkan placeholder tanpa membedakan huruf besar-kecil dan memformat berdasarkan tipe	BindingResult	Tidak pernah melempar; anomali menjadi peringatan atau field yang hilang	Menggunakan nilai default placeholder ketika kunci tidak ada.
TemplateDefinition::__construct	string $name, string $pageSize, string $orientation, list<TemplatePlaceholder> $placeholders, string $backgroundPdf = ''	Menyimpan definisi yang telah di-parse	TemplateDefinition	TypeError saat tipe argumen tidak cocok	Final readonly value object.
TemplateDefinition::getPlaceholder	string $name	Pencarian berdasarkan nama tanpa membedakan huruf besar-kecil	TemplatePlaceholder|null	Tidak ada kegagalan; mengembalikan null bila tidak ada	—
TemplateDefinition::requiredFields	tidak ada	Mengumpulkan nama placeholder yang tidak memiliki nilai default	list<string>	Tidak ada kegagalan	Default yang tidak kosong menandai placeholder sebagai opsional.
TemplatePlaceholder::__construct	string $name, PlaceholderType $type, float $x, float $y, float $width, float $height, string $defaultValue = '', string $format = ''	Menyimpan satu region placeholder	TemplatePlaceholder	TypeError saat tipe argumen tidak cocok	Koordinat adalah titik dari sudut kiri-atas.
TemplatePlaceholder::matches	string $key	Perbandingan nama tanpa membedakan huruf besar-kecil	bool	Tidak ada kegagalan	—
BindingResult::__construct	list<BoundPlaceholder> $bindings, list<string> $missingFields, list<string> $warnings	Menyimpan hasil binding	BindingResult	TypeError saat tipe argumen tidak cocok	Final readonly value object.
BindingResult::isComplete	tidak ada	Melaporkan apakah setiap field wajib telah terikat	bool	Tidak ada kegagalan	True ketika missingFields kosong.
BindingResult::count	tidak ada	Menghitung placeholder yang berhasil terikat	int	Tidak ada kegagalan	—
BoundPlaceholder::__construct	TemplatePlaceholder $placeholder, string $formattedValue, mixed $rawValue	Memasangkan sebuah placeholder dengan nilai terformatnya	BoundPlaceholder	TypeError saat tipe argumen tidak cocok	Final readonly value object.
PlaceholderType	case enum Text, Image, Barcode, Date, Number, Currency, Conditional	Taksonomi placeholder berbasis-string	instance enum	ValueError dari from() pada nilai yang tidak dikenal	tryFrom() mengembalikan null sebagai gantinya.
PlaceholderType::requiresFormatting	tidak ada	Melaporkan apakah tipe tersebut mengonsumsi string format	bool	Tidak ada kegagalan	True untuk Date, Number, Currency.

final class TemplateParser
{
    public function parse(string $json): TemplateDefinition;
    public function validate(string $json): array;
}

final class TemplateDataBinder
{
    public function bind(TemplateDefinition $template, array $data): BindingResult;
}

Kontrak perilaku

Bentuk JSON yang diterima:

{
  "name": "string (required, non-empty)",
  "pageSize": "A3|A4|A5|A6|B4|B5|Letter|Legal|Tabloid",
  "orientation": "P|L",
  "backgroundPdf": "optional path string",
  "placeholders": [
    { "name": "string", "type": "text|image|barcode|date|number|currency|conditional",
      "x": number, "y": number, "width": number, "height": number,
      "defaultValue": "optional", "format": "optional" }
  ]
}

Aturan validasi, semuanya dimunculkan oleh validate sebagai pesan dan diagregasi oleh parse menjadi satu exception:

• name yang hilang atau kosong.
• pageSize di luar daftar-izin, atau orientation bukan P atau L.
• placeholders yang hilang, atau nilai non-array.
• Per placeholder: nama yang hilang atau kosong; tipe tidak valid; x, y, width, height yang hilang atau non-numerik; nama duplikat (tanpa membedakan huruf besar-kecil).
• defaultValue: non-string, lebih panjang dari 4096 byte, atau membawa karakter kontrol ASCII.
• format: non-string, lebih panjang dari 256 byte, atau membawa karakter kontrol ASCII.
• format placeholder number yang bukan integer non-negatif, atau yang melebihi 30.

Semantik binding (TemplateDataBinder::bind):

• Kunci data dijadikan huruf kecil untuk pencocokan tanpa membedakan huruf besar-kecil terhadap nama placeholder.
• Kunci yang tidak ada dengan default tidak-kosong mengikat default tersebut; kunci yang tidak ada tanpa default dilaporkan dalam missingFields.
• Nilai text, image, dan barcode di-cast menjadi string tanpa perubahan.
• Binding date menerima DateTimeInterface, timestamp Unix integer, atau string dalam salah satu dari empat format eksplisit. Format output default adalah Y-m-d.
• Binding number menggunakan number_format(value, decimals, '.', ','). Jumlah desimal berasal dari format, default-nya 2, dan dibatasi pada rentang 0 hingga 30.
• Binding currency memberi prefiks pada angka yang diformat dengan format, dengan prefiks default $.
• Binding conditional memancarkan "true" atau "false" dari cast boolean.

Kasus tepi & mode kegagalan

• backgroundPdf tidak pernah dibuka atau didereferensi oleh modul ini. Ini adalah string opaque yang diserahkan ke perender.
• Sebuah nilai non-numerik yang diikat ke placeholder Number atau Currency menghasilkan peringatan; nilai tersebut di-cast menjadi string, bukan ditolak.
• String date di-parse secara ketat. Token relatif dan bahasa-alami (“now”, “+1 year”, “tomorrow”) tidak cocok dengan format mana pun yang diterima, sehingga memberi peringatan dan nilai mentahnya diteruskan tanpa perubahan.
• Nilai date integer dibaca sebagai timestamp Unix melalui bentuk epoch @.
• Presisi format Number di luar 0 hingga 30 yang sampai ke binder ditolak dengan peringatan; binder kembali ke presisi default 2.
• Tidak ada operasi kriptografis yang terjadi pada modul ini, sehingga tidak ada perilaku spesifik mode FIPS.

Kesesuaian

Tidak ada permukaan spesifikasi-PDF langsung. Kosakata ukuran-halaman dan orientasi adalah konvensi NextPDF, dan modul ini memancarkan nilai yang diformat, bukan objek PDF. Daftar-izin string-date yang ketat menerima profil tanggal/waktu Internet dari ISO 8601 yang didefinisikan dalam RFC 3339 §5.6, di samping tanggal kalender Y-m-d dan dua bentuk date-time lokal. NextPDF mendokumentasikan kapabilitas untuk membaca format-format ini; ia tidak mengklaim sertifikasi apa pun terhadap RFC 3339 atau ISO 8601.

Catatan pengembangan

• TemplateParser dan TemplateDataBinder bersifat stateless. Satu instance dapat digunakan ulang dan aman untuk dibagikan lintas binding.
• Keempat value object bersifat final readonly; bangun melalui parser alih-alih secara manual untuk input produksi.
• validate melaporkan setiap error struktural dalam satu lintasan, sementara parse memanggil validate terlebih dahulu dan melempar pada pesan yang teragregasi. Gunakan validate untuk umpan balik bergaya-formulir dan parse untuk ingesti fail-fast.
• Batas panjang dan presisi ditegakkan di parser sebagai gerbang otoritatif. TemplateDataBinder memeriksa ulang presisi number sebagai penjaga sisi-sink terhadap amplifikasi memori number_format.

Batas publikasi

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

Lihat juga

• Template (panduan kapabilitas)
• Toc
• Merge