Form

Sekilas pandang

NextPDF Pro membaca dan menulis data formulir interaktif: nilai bidang AcroForm, berkas data XFDF, dan data yang dibawa oleh templat XFA (XML Forms Architecture). Ia melengkapi pembaca formulir Core sumber terbuka dengan data binding, ekstraksi, dan serialisasi.

Ketersediaan & lisensi

Kapabilitas ini disertakan dalam NextPDF Pro (nextpdf/pro) dan diaktifkan dengan amplop lisensi tingkat Pro. Deployment tanpa hak tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Form adalah bagian dari edisi Pro. Tidak ada penanda lisensi per-fitur terpisah.

Pemasangan

composer require nextpdf/pro:^3

Kapabilitas Form membutuhkan lisensi NextPDF Pro yang valid. Lihat Ketersediaan & lisensi.

Tinjauan konseptual

Sebuah formulir interaktif PDF — kadang disebut AcroForm — menyimpan setiap bidang dalam sebuah field dictionary, sebagaimana didefinisikan di ISO 32000-2 §12.7. NextPDF Pro membangun di atas pembaca formulir Core untuk menambahkan tiga kapabilitas:

• Round-trip AcroForm. FormDataExtractor membaca pasangan nama/nilai bidang dari bidang formulir yang diurai dan menghasilkan sebuah objek XfdfData atau peta name → value polos. XfdfWriter melakukan kebalikannya, menghasilkan sebuah dokumen XFDF.
• Baca dan tulis XFDF. XFDF adalah format pertukaran-data XML untuk nilai formulir yang dideskripsikan oleh ISO 19444-1:2019. XfdfParser membaca berkas XFDF menjadi data terstruktur; XfdfWriter menserialisasi nilai bidang ke XFDF, dengan referensi opsional kembali ke PDF sumber.
• Ekstraksi data XFA. XfaParser menemukan paket XFA dalam sebuah dokumen, menggabungkan fragmen XML, dan mengurai paket template dan datasets menjadi data bidang terstruktur.

Cakupan dukungan XFA

Dukungan XFA di NextPDF Pro bersifat berorientasi-data, bukan mesin perenderan atau scripting XFA penuh. Parser mengekstrak dan menyusun paket template dan datasets sehingga Anda dapat membaca definisi dan nilai bidang. Ia tidak mengeksekusi skrip kalkulasi-formulir XFA, merender tata letak XFA dinamis, atau melakukan round-trip pada setiap tipe paket XFA. Uji parser terhadap dokumen spesifik Anda sebelum mengandalkannya untuk himpunan formulir XFA tertentu. Semua penguraian XML menonaktifkan pemuatan entitas-eksternal (XXE-safe).

Mengapa cara kerjanya seperti ini

Dukungan XFA dilingkupi pada data, bukan perenderan, secara sengaja. ISO 32000-2 menandai entri XFA pada form dictionary sebagai deprecated di PDF 2.0 (§12.7). Sebuah mesin tata letak dan scripting XFA penuh akan mengejar permukaan legacy yang tidak lagi dibutuhkan sebagian besar beban kerja. Sebagai gantinya, NextPDF Pro mengekstrak paket template dan datasets, tempat data bidang yang tahan lama berada, dan menolak sisanya. Sikap yang sama mendorong penguraian XXE-off dan plafon pemindaian, karena input formulir sering datang dari pihak yang tidak tepercaya. Itu menjaga permukaan formulir Pro tetap menjadi ekstensi yang tipis dan dapat diprediksi dari model AcroForm Core.

Latar belakang desain: Dari formulir yang dapat diisi menjadi rekaman yang dibekukan: pengisian dan perataan AcroForm.

Permukaan API

Class	Responsibility
FormDataExtractor	Mengekstrak nilai bidang AcroForm sebagai XfdfData atau array.
XfdfParser	Mengurai dokumen XFDF menjadi data terstruktur.
XfdfWriter	Menserialisasi nilai bidang ke XFDF, referensi PDF opsional.
XfaParser	Mengekstrak dan mengurai paket template dan datasets XFA.
FormDataBinder	Mengikat peta data kembali ke bidang formulir.

Referensi tingkat-metode lengkap ada di Referensi mendalam Form.

Contoh kode — Mulai cepat

use NextPDF\Pro\Form\FormDataExtractor;
use NextPDF\Pro\Form\XfdfWriter;

$values = FormDataExtractor::toArray($fields);
$xfdf   = XfdfWriter::fromFields($fields, 'invoice.pdf');

Contoh kode — Produksi

use NextPDF\Pro\Form\XfaParser;
use NextPDF\Pro\Form\Exception\XfaParseException;

try {
    $formData = (new XfaParser())->parse($pdfBytes);
    $logger->info('xfa.parsed', ['fields' => count($formData->fields)]);
} catch (XfaParseException $e) {
    $logger->warning('xfa.parse_failed', ['reason' => $e->getMessage()]);
}

Kasus tepi & jebakan

• XfaParser menolak input PDF yang lebih besar dari plafon pemindaiannya alih-alih membaca data tak terbatas.
• Sebuah dokumen dapat membawa formulir interaktif sekaligus non-interaktif; ekstraksi menargetkan field dictionary terminal.
• XFDF melakukan round-trip pada struktur bidang datar; hierarki bidang yang bersarang dalam mungkin perlu penanganan eksplisit.

Performa

Ekstraksi dan serialisasi bersifat linear terhadap jumlah bidang formulir. Biaya penguraian XFA menskala dengan ukuran paket XML tertanam.

Catatan keamanan

Semua penguraian XML menonaktifkan resolusi entitas-eksternal untuk mencegah XXE. Perlakukan input XFDF dan XFA dari sumber yang tidak tepercaya sebagai bermusuhan dan validasi himpunan bidang yang diurai sebelum mengikatnya kembali ke dalam sebuah dokumen.

Konformansi

Behavior	Reference	Status
Interactive form / field dictionary model	ISO 32000-2 §12.7	Aligned (paraphrased)
XFDF data-exchange format	ISO 19444-1:2019	Aligned

Tabel ini mencatat spesifikasi yang menjadi dasar pembangunan NextPDF Pro. Ini bukan pernyataan sertifikasi formal.

Kontrak perilaku

• FormDataExtractor membaca pasangan nama/nilai dari field dictionary terminal yang diurai dan mengembalikan sebuah objek XfdfData atau array name → value polos.
• XfdfParser mengurai dokumen XFDF menjadi data terstruktur; XfdfWriter menserialisasi nilai bidang ke XFDF dengan referensi opsional kembali ke PDF sumber.
• XfaParser menemukan paket XFA, menggabungkan fragmen XML, dan mengurai paket template dan datasets menjadi data bidang terstruktur. Ia menolak input PDF yang lebih besar dari plafon pemindaiannya alih-alih membaca data tak terbatas.
• Dukungan XFA bersifat berorientasi-data: parser mengekstrak dan menyusun paket template dan datasets. Ia tidak mengeksekusi skrip kalkulasi-formulir XFA, merender tata letak XFA dinamis, atau melakukan round-trip pada setiap tipe paket XFA.
• Semua penguraian XML menonaktifkan resolusi entitas-eksternal (XXE-safe).

Catatan batas Enterprise

Enterprise tidak mengubah perilaku Form. Enterprise menambahkan fitur kepatuhan dan arsip tingkat-lebih-tinggi yang didokumentasikan terpisah; fitur tersebut tidak diwajibkan untuk round-trip AcroForm, baca/tulis XFDF, atau ekstraksi data XFA.

Fallback / alternatif Core

Pembaca formulir sumber terbuka NextPDF Core membaca bidang formulir. Baca/tulis XFDF, ekstraksi data XFA, dan pengikatan bidang adalah tambahan Pro. Lihat /modules/form/.

Batas publikasi

Halaman ini mendokumentasikan hanya perilaku yang dapat diamati secara eksternal 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

• Interop — DTO data-formulir berversi untuk sistem eksternal.
• Core Form module — pembaca formulir sumber terbuka.
• Form — Deep Reference — referensi tingkat-metode untuk kelas-kelas formulir Pro.