ฟอร์ม

ภาพรวมโดยสังเขป

NextPDF Pro อ่านและเขียนข้อมูลฟอร์มแบบอินเทอร์แอกทีฟ ได้แก่ ค่าฟิลด์ AcroForm ไฟล์ข้อมูล XFDF และข้อมูลที่นำพาโดยเทมเพลต XFA (XML Forms Architecture) โดยเสริมตัวอ่านฟอร์มของ Core แบบโอเพนซอร์สด้วยการ binding ข้อมูล การสกัด และการทำให้เป็นอนุกรม

การพร้อมใช้งานและการอนุญาต

ความสามารถนี้จัดส่งใน NextPDF Pro (nextpdf/pro) และเปิดใช้งานด้วยซองใบอนุญาตระดับ Pro การนำไปใช้งานที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและขอใบอนุญาต

Form เป็นส่วนหนึ่งของรุ่น Pro ไม่มีแฟล็กใบอนุญาตแยกต่อฟีเจอร์

การติดตั้ง

composer require nextpdf/pro:^3

ความสามารถ Form ต้องการใบอนุญาต NextPDF Pro ที่ถูกต้อง ดู การพร้อมใช้งานและการอนุญาต

ภาพรวมเชิงแนวคิด

ฟอร์มแบบอินเทอร์แอกทีฟของ PDF บางครั้งเรียกว่า AcroForm จัดเก็บแต่ละฟิลด์ไว้ในพจนานุกรมฟิลด์ ตามที่กำหนดใน ISO 32000-2 §12.7 NextPDF Pro ต่อยอดตัวอ่านฟอร์มของ Core เพื่อเพิ่มสามความสามารถ:

• การ round-trip ของ AcroForm FormDataExtractor อ่านคู่ชื่อ/ค่าฟิลด์จากฟิลด์ฟอร์มที่แจงแล้วและผลิตออบเจ็กต์ XfdfData หรือแมป name → value แบบธรรมดา XfdfWriter ทำในทางกลับกัน โดยสร้างเอกสาร XFDF
• การอ่านและเขียน XFDF XFDF คือรูปแบบการแลกเปลี่ยนข้อมูล XML สำหรับค่าฟอร์มที่อธิบายโดย ISO 19444-1:2019 XfdfParser อ่านไฟล์ XFDF ให้เป็นข้อมูลที่มีโครงสร้าง XfdfWriter ทำให้ค่าฟิลด์เป็นอนุกรมเป็น XFDF พร้อมการอ้างอิงกลับไปยัง PDF ต้นทางที่เลือกได้
• การสกัดข้อมูล XFA XfaParser ค้นหาแพ็กเก็ต XFA ในเอกสาร เชื่อมต่อชิ้นส่วน XML และแจงแพ็กเก็ต template และ datasets ให้เป็นข้อมูลฟิลด์ที่มีโครงสร้าง

ขอบเขตการรองรับ XFA

การรองรับ XFA ใน NextPDF Pro เป็นแบบ เน้นข้อมูล ไม่ใช่เอนจินการเรนเดอร์หรือสคริปต์ XFA แบบเต็ม ตัวแจงสกัดและจัดโครงสร้างแพ็กเก็ต template และ datasets เพื่อให้คุณอ่านนิยามฟิลด์และค่าได้ โดยไม่รันสคริปต์การคำนวณฟอร์ม XFA ไม่เรนเดอร์เค้าโครง XFA แบบไดนามิก หรือ round-trip แพ็กเก็ต XFA ทุกชนิด จงทดสอบตัวแจงกับเอกสารเฉพาะของคุณก่อนพึ่งพามันสำหรับชุดฟอร์ม XFA ที่กำหนด การแจง XML ทั้งหมดปิดการโหลดเอนทิตีภายนอก (ปลอดภัยจาก XXE)

เหตุผลที่ทำงานเช่นนี้

การรองรับ XFA ถูกจำกัดขอบเขตไว้ที่ข้อมูล ไม่ใช่การเรนเดอร์ อย่างจงใจ ISO 32000-2 ระบุว่ารายการ XFA ในพจนานุกรมฟอร์มเลิกใช้แล้วใน PDF 2.0 (§12.7) เอนจินเค้าโครงและสคริปต์ XFA แบบเต็มจะไล่ตามพื้นผิวเดิมที่งานส่วนใหญ่ไม่ต้องการอีกต่อไป NextPDF Pro จึงสกัดแพ็กเก็ต template และ datasets ซึ่งเป็นที่อยู่ของข้อมูลฟิลด์ที่คงทน และปฏิเสธส่วนที่เหลือ ท่าทีเดียวกันนี้ขับเคลื่อนการแจงแบบปิด XXE และเพดานการสแกน เพราะอินพุตฟอร์มมักมาจากฝ่ายที่ไม่น่าเชื่อถือ นั่นทำให้พื้นผิว Form ของ Pro เป็นส่วนขยายที่บางและคาดเดาได้ของโมเดล AcroForm ของ Core

พื้นหลังการออกแบบ: จากฟอร์มที่กรอกได้สู่ระเบียนที่ตรึงแล้ว: การกรอกและ flatten AcroForm

พื้นผิว API

Class	Responsibility
FormDataExtractor	สกัดค่าฟิลด์ AcroForm เป็น XfdfData หรืออาร์เรย์
XfdfParser	แจงเอกสาร XFDF ให้เป็นข้อมูลที่มีโครงสร้าง
XfdfWriter	ทำให้ค่าฟิลด์เป็นอนุกรมเป็น XFDF พร้อมการอ้างอิง PDF ที่เลือกได้
XfaParser	สกัดและแจงแพ็กเก็ต template และ datasets ของ XFA
FormDataBinder	bind แมปข้อมูลกลับเข้าฟิลด์ฟอร์ม

การอ้างอิงระดับเมธอดแบบเต็มอยู่ใน Form deep reference

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

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

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

ตัวอย่างโค้ด — สำหรับใช้งานจริง

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()]);
}

ข้อควรระวังและกรณีขอบ

• XfaParser ปฏิเสธอินพุต PDF ที่ใหญ่กว่าเพดานการสแกนแทนที่จะอ่านข้อมูลแบบไม่มีขอบเขต
• เอกสารอาจนำพาทั้งฟอร์มแบบอินเทอร์แอกทีฟและไม่อินเทอร์แอกทีฟ การสกัดมุ่งเป้าไปยังพจนานุกรมฟิลด์ปลายทาง
• XFDF round-trip โครงสร้างฟิลด์แบน ลำดับชั้นของฟิลด์ที่ซ้อนลึกอาจต้องการการจัดการที่ชัดเจน

ประสิทธิภาพ

การสกัดและการทำให้เป็นอนุกรมเป็นเชิงเส้นตามจำนวนฟิลด์ฟอร์ม ต้นทุนการแจง XFA ปรับตามขนาดของแพ็กเก็ต XML ที่ฝังอยู่

บันทึกด้านความปลอดภัย

การแจง XML ทั้งหมดปิดการคลี่คลายเอนทิตีภายนอกเพื่อป้องกัน XXE จงปฏิบัติต่ออินพุต XFDF และ XFA จากแหล่งที่ไม่น่าเชื่อถือว่าเป็นปฏิปักษ์และตรวจสอบชุดฟิลด์ที่แจงแล้วก่อน bind กลับเข้าเอกสาร

ความสอดคล้องกับมาตรฐาน

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

ตารางนี้บันทึกข้อกำหนดที่ NextPDF Pro สร้างขึ้นเทียบกับ ไม่ใช่ข้อความแสดงการรับรองอย่างเป็นทางการ

สัญญาพฤติกรรม

• FormDataExtractor อ่านคู่ชื่อ/ค่าจากพจนานุกรมฟิลด์ปลายทางที่แจงแล้วและคืนค่าออบเจ็กต์ XfdfData หรืออาร์เรย์ name → value แบบธรรมดา
• XfdfParser แจงเอกสาร XFDF ให้เป็นข้อมูลที่มีโครงสร้าง XfdfWriter ทำให้ค่าฟิลด์เป็นอนุกรมเป็น XFDF พร้อมการอ้างอิงกลับไปยัง PDF ต้นทางที่เลือกได้
• XfaParser ค้นหาแพ็กเก็ต XFA เชื่อมต่อชิ้นส่วน XML และแจงแพ็กเก็ต template และ datasets ให้เป็นข้อมูลฟิลด์ที่มีโครงสร้าง โดยปฏิเสธอินพุต PDF ที่ใหญ่กว่าเพดานการสแกนแทนที่จะอ่านข้อมูลแบบไม่มีขอบเขต
• การรองรับ XFA เน้นข้อมูล คือตัวแจงสกัดและจัดโครงสร้างแพ็กเก็ต template และ datasets โดยไม่รันสคริปต์การคำนวณฟอร์ม XFA ไม่เรนเดอร์เค้าโครง XFA แบบไดนามิก หรือ round-trip แพ็กเก็ต XFA ทุกชนิด
• การแจง XML ทั้งหมดปิดการคลี่คลายเอนทิตีภายนอก (ปลอดภัยจาก XXE)

บันทึกขอบเขตของ Enterprise

Enterprise ไม่เปลี่ยนพฤติกรรมของ Form Enterprise เพิ่มฟีเจอร์การปฏิบัติตามข้อกำหนดและการจัดเก็บถาวรระดับสูงขึ้นที่บันทึกแยกต่างหาก โดยไม่จำเป็นสำหรับการ round-trip ของ AcroForm การอ่าน/เขียน XFDF หรือการสกัดข้อมูล XFA

ทางเลือก / ทางสำรองของ Core

ตัวอ่านฟอร์มแบบโอเพนซอร์สของ NextPDF Core อ่านฟิลด์ฟอร์ม การอ่าน/เขียน XFDF การสกัดข้อมูล XFA และการ binding ฟิลด์เป็นการเพิ่มเติมของ Pro ดู /modules/form/

ขอบเขตการเผยแพร่

หน้านี้อธิบายพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น เส้นทาง namespace ภายใน คลาสตัวช่วย ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้า ticket อยู่นอกขอบเขต

ดูเพิ่มเติม

• Interop — DTO ข้อมูลฟอร์มที่มีเวอร์ชันสำหรับระบบภายนอก
• Core Form module — ตัวอ่านฟอร์มแบบโอเพนซอร์ส
• Form — Deep Reference — การอ้างอิงระดับเมธอดสำหรับคลาสฟอร์มของ Pro