Pro edisi

Form — Referensi Mendalam

Sekilas

Halaman ini adalah referensi mendalam untuk modul Pro Form. Halaman ini mencakup ekstraksi nilai AcroForm, baca dan tulis XFDF, pengikatan data, dan ekstraksi data XFA. Modul ini mengonsumsi nilai NextPDF\Form\FormField yang dihasilkan oleh Core form reader dan menambahkan serialisasi, penguraian, dan pengikatan di atasnya. Dukungan XFA berorientasi data: parser menstrukturkan paket template dan datasets. Ia tidak mengeksekusi skrip kalkulasi XFA atau merender tata letak XFA dinamis.

Ketersediaan & lisensi

Kapabilitas ini disertakan dalam NextPDF Pro (nextpdf/pro) dan aktif dengan envelope lisensi tier-Pro. Deployment tanpa entitlement tersebut tidak memuat class kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Tidak ada flag lisensi per-fitur. Ini adalah kapabilitas edisi Pro.

Permukaan API publik

Simbol	Parameter	Perilaku default	Mengembalikan	Melempar atau gagal dengan	Catatan
`FormDataExtractor::extract`	`list<FormField> $fields`	Membaca nama dan nilai setiap bidang	`XfdfData`	—	Menyertakan bidang yang nilainya kosong.
`FormDataExtractor::toArray`	`list<FormField> $fields`	Membangun map string nama-ke-nilai	`array<string, string>`	—	Nama duplikat berikutnya menimpa yang sebelumnya.
`FormDataExtractor::toXfdf`	`list<FormField> $fields`, `?string $pdfHref = null`	Mendelegasikan ke `XfdfWriter::fromFields`	`string` (XFDF XML)	—	Jalur praktis untuk ekspor satu panggilan.
`FormDataExtractor::extractNonEmpty`	`list<FormField> $fields`	Melewati bidang yang nilainya string kosong	`XfdfData`	—	—
`FormDataExtractor::getEmptyFieldNames`	`list<FormField> $fields`	Mendaftar nama bidang yang tidak memiliki nilai	`list<string>`	—	Komplemen dari `extractNonEmpty`.
`XfdfWriter::fromFields`	`list<FormField> $fields`, `?string $pdfHref = null`	Mengumpulkan pasangan nama-ke-nilai, mendelegasikan ke `fromArray`	`string` (XFDF XML)	—	—
`XfdfWriter::fromArray`	`array<string, string> $data`, `?string $pdfHref = null`	Membungkus map dalam `XfdfData`, mendelegasikan	`string` (XFDF XML)	—	—
`XfdfWriter::fromXfdfData`	`XfdfData $data`, `?string $pdfHref = null`	Menserialisasi ke XFDF; nama notasi-titik bersarang sebagai elemen `<field>` hierarkis	`string` (XFDF XML)	—	Menghapus karakter kontrol yang ilegal menurut XML 1.0; lihat kontrak perilaku.
`XfdfParser::parse`	`string $xfdfXml`	Memuat XML secara aman-XXE dan meratakan bidang ke notasi titik	`XfdfData`	`InvalidArgumentException`	Pagu masukan 10 MiB; menerima root ber-namespace dan tanpa namespace.
`XfdfParser::parseFile`	`string $filePath`	Menyelesaikan path, membaca berkas, mendelegasikan ke `parse`	`XfdfData`	`InvalidArgumentException`	Path yang hilang, bukan berkas, atau tidak terbaca memunculkan eksepsi.
`XfaParser::parse`	`string $pdfData`	Pemeriksaan marker, ekstraksi XML, penguraian paket	`XfaFormData`	`InvalidArgumentException`, `XfaParseException`	Tanpa marker `/XFA` mengembalikan hasil kosong, bukan error.
`XfaParser::hasXfa`	`string $pdfData`	Memindai byte untuk marker `/XFA`	`bool`	—	Pemindaian marker byte; kemunculan token apa pun cocok.
`XfaParser::extractXfaXml`	`string $pdfData`	Pemindaian stream untuk marker XFA, lalu pencarian `<xdp:xdp>` langsung	`string` (XFA XML atau `''`)	`RuntimeException` (dideklarasikan)	Memindai paling banyak 50 MiB pertama dari masukan.
`XfaParser::parseXml`	`string $xml`	Mengekstrak paket template dan datasets, mengurai elemen `<field>`	`XfaFormData`	`XfaParseException`	Pagu XML 10 MiB, ditegakkan sebelum pemuatan DOM.
`FormDataBinder::bind`	`list<FormField> $fields`, `XfdfData $data`	Membuat instance `FormField` baru dengan nilai yang terikat	`FormDataBindResult`	—	Asli tidak pernah diubah; check box dinormalisasi menjadi `Yes`/`Off`.
`FormDataBinder::fromXfdf`	`list<FormField> $fields`, `string $xfdfXml`	Mengurai XFDF, lalu mengikat	`FormDataBindResult`	`InvalidArgumentException`	Mode kegagalan sama seperti `XfdfParser::parse`.
`FormDataBinder::fromArray`	`list<FormField> $fields`, `array<string, string> $data`	Membungkus map dalam `XfdfData`, lalu mengikat	`FormDataBindResult`	—	—
`FormDataBindResult`	`isFullyBound`, `hasNoUnmatchedKeys`, `boundCount`, `fieldCount`; readonly `fields`, `boundFieldNames`, `unmatchedDataKeys`, `unboundFieldNames`	Diagnostik pengikatan yang immutable	per metode	—	`isFullyBound` memerlukan nol kunci yang tak cocok dan nol bidang yang tak terikat.
`XfdfData`	`hasField`, `getValue`, `count`, `isEmpty`, `getFieldNames`, `withField`, `withoutField`, `merge`; readonly `fields`	Kontainer nama-ke-nilai yang immutable	per metode	—	`with*` dan `merge` mengembalikan instance baru; `merge` mengutamakan nilai dari argumen.
`XfaFormData`	`getField`, `hasField`, `count`, `fieldNames`; readonly `fields`, `templateXml`, `datasetsXml`	Hasil penguraian XFA yang immutable	per metode	—	Membawa XML paket template dan datasets mentah untuk round-trip.
`XfaFormField`	readonly `name`, `type`, `value`, `required`, `caption`, `options`	Rekaman satu-bidang yang immutable	—	—	`type` adalah salah satu dari `text`, `numeric`, `date`, `choice`, `button`, `signature`.
`XfaPacket`	kasus enum `Template`, `Datasets`, `Config`, `LocaleSet`, `ConnectionSet`, `Form`; `xmlNamespace()`	Enumerasi paket berbasis string	`string` dari `xmlNamespace()`	—	URI namespace mengikuti XFA Specification 3.3.

public static function extract(array $fields): XfdfData
public static function toArray(array $fields): array
public static function toXfdf(array $fields, ?string $pdfHref = null): string
public static function extractNonEmpty(array $fields): XfdfData
public static function getEmptyFieldNames(array $fields): array

public static function fromFields(array $fields, ?string $pdfHref = null): string
public static function fromArray(array $data, ?string $pdfHref = null): string
public static function fromXfdfData(XfdfData $data, ?string $pdfHref = null): string

public static function parse(string $xfdfXml): XfdfData
public static function parseFile(string $filePath): XfdfData

public function parse(string $pdfData): XfaFormData
public function hasXfa(string $pdfData): bool
public function extractXfaXml(string $pdfData): string
public function parseXml(string $xml): XfaFormData

public static function bind(array $fields, XfdfData $data): FormDataBindResult
public static function fromXfdf(array $fields, string $xfdfXml): FormDataBindResult
public static function fromArray(array $fields, array $data): FormDataBindResult

Pengecualian

NextPDF\Pro\Form\Exception\XfaParseException memperluas RuntimeException — payload XFA tidak dapat diurai menjadi sebuah XfaFormData. Subclassing ini disengaja: call site catch (RuntimeException $e) yang sudah ada tetap bekerja.
SPL InvalidArgumentException — masukan yang kosong, terlalu besar, cacat, atau bukan-XFDF ke XfdfParser; masukan PDF kosong ke XfaParser::parse; path yang tidak terbaca di XfdfParser::parseFile.

Kontrak perilaku

Ekstraksi AcroForm. FormDataExtractor menelusuri daftar bidang yang Anda berikan dan membaca nama serta nilai setiap bidang. extract mengembalikan sebuah XfdfData; toArray mengembalikan map string nama-ke-nilai biasa. extractNonEmpty membuang bidang yang nilainya string kosong; getEmptyFieldNames mengembalikan daftar nama komplementernya. Ekstraksi tidak pernah mengubah bidang masukan.

Penulisan XFDF. XfdfWriter menghasilkan sebuah dokumen yang sesuai dengan struktur ISO 19444-1:2019. Keluaran diawali dengan deklarasi XML XFDF dan sebuah root xfdf dalam namespace XFDF Adobe (http://ns.adobe.com/xfdf/) dengan xml:space="preserve". pdfHref yang non-null memancarkan sebuah referensi <f href="..."/> kembali ke PDF sumber. Nama bidang notasi-titik (misalnya address.city) bersarang menjadi pohon elemen <field> hierarkis. Nilai dan atribut meng-escape kelima metakarakter XML. Nama bidang, nilai, dan pdfHref selanjutnya dinormalisasi agar well-formed: karakter kontrol C0 yang dilarang XML 1.0 dihapus, sementara TAB, LF, dan CR dipertahankan. Normalisasi ini bersifat lossy secara desain, sehingga writer selalu memancarkan XFDF yang well-formed dan dapat diurai ulang terlepas dari byte yang diberikan pemanggil.

Pembacaan XFDF. XfdfParser menerima root xfdf baik yang ber-namespace maupun tanpa namespace dan mencocokkan nama root secara tidak peka huruf besar-kecil, karena beberapa produser memancarkan elemen root huruf besar. Pohon <field> hierarkis diratakan kembali menjadi nama notasi-titik, sehingga penulisan dan pembacaan round-trip. Semua pemuatan XML menonaktifkan akses jaringan dan resolusi entitas eksternal. parseFile menambahkan penyelesaian path dan pemeriksaan keterbacaan di depan penguraian yang sama.

Pengikatan data. FormDataBinder::bind mencocokkan kunci data terhadap nama bidang. Karena FormField bersifat immutable, pengikatan membuat instance baru dengan nilai yang diperbarui; asli tidak pernah diubah. Hasilnya melaporkan tiga set diagnostik: nama bidang yang terikat, kunci data tanpa bidang yang cocok, dan bidang yang tidak menerima data. Nilai check-box dinormalisasi ke model status on/off dari ISO 32000-2:2020, 12.7.5.2.3: yes, true, 1, dan on (tidak peka huruf besar-kecil) dipetakan ke Yes; setiap nilai lain dipetakan ke Off.

Ekstraksi data XFA. XfaParser::parse menerima byte PDF mentah. Ia pertama-tama memindai marker /XFA; tanpa marker tersebut ia mengembalikan XfaFormData kosong. Ekstraksi kemudian mencoba dua strategi: pemindaian blok stream…endstream untuk indikator XFA XML, lalu pencarian langsung untuk dokumen <xdp:xdp>. Satu fragmen xdp:xdp dikembalikan apa adanya; beberapa fragmen digabungkan menjadi sebuah envelope xdp:xdp yang disintesis. parseXml mengekstrak paket template dan datasets dan mengurai setiap elemen <field> template menjadi sebuah XfaFormField: atribut name wajib, type diturunkan dari elemen anak UI bidang, flag required diturunkan dari elemen validate dengan nullTest disetel ke error, dan opsi choice berasal dari anak items.

Dukungan XFA berorientasi data. Parser menstrukturkan paket template dan datasets. Ia tidak mengeksekusi skrip kalkulasi XFA, merender tata letak XFA dinamis, atau me-round-trip setiap jenis paket. Validasi parser terhadap set dokumen spesifik Anda sebelum mengandalkannya.

Kasus tepi & mode kegagalan

XfdfParser::parse('') melempar InvalidArgumentException. Masukan di atas 10 MiB melempar InvalidArgumentException yang menyebutkan pagu tersebut.
XML yang cacat melempar InvalidArgumentException yang membawa pesan libxml yang terkumpul. Dokumen yang well-formed tetapi root-nya bukan xfdf melempar eksepsi dan menyebutkan elemen root yang sebenarnya.
Dokumen XFDF tanpa elemen <fields> terurai menjadi XfdfData kosong; itu bukan error.
Elemen bidang tanpa atribut name dilewati baik dalam penguraian XFDF maupun XFA. Bidang XFDF tanpa anak <value> tidak menyumbang entri.
XfaParser::parse('') melempar InvalidArgumentException. PDF tanpa marker /XFA, atau yang XFA XML-nya tidak dapat ditemukan, mengembalikan XfaFormData kosong alih-alih melempar eksepsi.
hasXfa adalah pemindaian marker byte: token /XFA apa pun dalam berkas cocok, termasuk yang ada di objek yang tidak terpakai. Langkah ekstraksi berikutnya yang memutuskan apakah XML yang dapat digunakan ada.
Ekstraksi XFA memeriksa paling banyak 50 MiB pertama dari string byte PDF; konten di luar batas itu tidak dipindai.
XFA XML di atas 10 MiB melempar XfaParseException sebelum pohon DOM apa pun terwujud. XFA XML yang cacat melempar XfaParseException dengan pesan libxml.
Normalisasi check-box tidak pernah meneruskan nilai yang tak dikenali; apa pun di luar bentuk-on yang diterima dipetakan ke Off.
Penghapusan karakter kontrol oleh writer bersifat lossy: byte C0 yang ilegal menurut XML 1.0 dalam nama, nilai, atau pdfHref dibuang agar keluaran tetap well-formed. TAB, LF, dan CR bertahan.
Semua penguraian XML menonaktifkan resolusi entitas eksternal dan akses jaringan (aman-XXE).
Modul ini tidak melakukan operasi kriptografis; mode FIPS tidak mengubah perilakunya.

Kesesuaian

Perilaku	Referensi	Status
Model formulir interaktif / dictionary bidang	ISO 32000-2:2020, 12.7	Selaras (berdasar produk)
Normalisasi status on/off check-box (`Yes`/`Off`)	ISO 32000-2:2020, 12.7.5.2.3	Selaras; klausa dikutip dalam catatan sitasi halaman ini
Struktur pertukaran data XFDF	ISO 19444-1:2019	Selaras (berdasar produk)
Nama paket XFA dan URI namespace	XFA Specification 3.3	Selaras (berdasar produk)

Korpus RAG yang tersedia pada saat penulisan tidak mencakup ISO 19444-1:2019, XFA Specification, atau W3C XML 1.0, sehingga pernyataan keselarasan tersebut berdasar produk dari anotasi sumber dan pengujian, bukan dikutip per klausa. Pernyataan-pernyataan ini menggambarkan kapabilitas terhadap dokumen yang dirujuk. NextPDF tidak memegang sertifikasi kesesuaian, dan dukungan terhadap suatu klausa bukanlah klaim sertifikasi.

Catatan pengembangan

Setiap entry point kecuali XfaParser bersifat static. XfaParser dapat diinstansiasi dan stateless; satu instance aman digunakan ulang lintas dokumen.
Round-trip yang dimaksudkan adalah: Core form reader menghasilkan nilai FormField; FormDataExtractor atau XfdfWriter menserialisasinya; XfdfParser membaca data kembali; FormDataBinder menerapkannya ke daftar bidang. Nama hierarkis bertahan melewati round-trip melalui notasi titik.
Gunakan diagnostik FormDataBindResult (isFullyBound, unmatchedDataKeys, unboundFieldNames) untuk mendeteksi drift antara berkas data XFDF dan template PDF yang direvisi sebelum menerima pengisian.
XfdfData adalah value object: withField, withoutField, dan merge mengembalikan instance baru. Pada tabrakan kunci, merge mengutamakan nilai dari argumen.
XfaFormData menyimpan XML paket template dan datasets mentah (templateXml, datasetsXml) sehingga Anda dapat memproses lebih lanjut paket yang tidak dicakup model bidang.
Modul ini tidak mengurai dictionary AcroForm dari byte PDF sendiri; ia mengonsumsi bidang yang dihasilkan Core form reader. Hanya XfaParser yang beroperasi pada konten PDF mentah.

Batas publikasi

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