Form — การอ้างอิงเชิงลึก

โดยสังเขป

หน้านี้คือการอ้างอิงเชิงลึกสำหรับโมดูล Pro Form ครอบคลุมการสกัดค่า AcroForm การอ่านและเขียน XFDF การผูกข้อมูล และการสกัดข้อมูล XFA โมดูลนี้รับค่า NextPDF\Form\FormField ที่ผลิตโดยตัวอ่านฟอร์มของ Core แล้วเพิ่มการทำ serialization การแจง และการผูกข้อมูลทับลงไป การรองรับ XFA เน้นข้อมูลเป็นหลัก: ตัวแจงจัดโครงสร้างแพ็กเก็ต template และ datasets โดยไม่รันสคริปต์คำนวณ XFA และไม่เรนเดอร์เลย์เอาต์ XFA แบบไดนามิก

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

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

ไม่มีแฟล็กใบอนุญาตรายฟีเจอร์ นี่คือความสามารถของรุ่น Pro

พื้นผิว API สาธารณะ

สัญลักษณ์	พารามิเตอร์	พฤติกรรมโดยปริยาย	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
FormDataExtractor::extract	list<FormField> $fields	อ่านชื่อและค่าของแต่ละฟิลด์	XfdfData	—	รวมฟิลด์ที่มีค่าว่างด้วย
FormDataExtractor::toArray	list<FormField> $fields	สร้างแมปสตริงจากชื่อไปยังค่า	array<string, string>	—	ชื่อซ้ำที่มาทีหลังจะเขียนทับชื่อก่อนหน้า
FormDataExtractor::toXfdf	list<FormField> $fields, ?string $pdfHref = null	มอบหมายให้ XfdfWriter::fromFields	string (XFDF XML)	—	เส้นทางอำนวยความสะดวกสำหรับการส่งออกในการเรียกครั้งเดียว
FormDataExtractor::extractNonEmpty	list<FormField> $fields	ข้ามฟิลด์ที่มีค่าเป็นสตริงว่าง	XfdfData	—	—
FormDataExtractor::getEmptyFieldNames	list<FormField> $fields	แสดงรายชื่อฟิลด์ที่ยังไม่ได้ตั้งค่า	list<string>	—	ส่วนเติมเต็มของ extractNonEmpty
XfdfWriter::fromFields	list<FormField> $fields, ?string $pdfHref = null	รวบรวมคู่ชื่อ-ค่า แล้วมอบหมายให้ fromArray	string (XFDF XML)	—	—
XfdfWriter::fromArray	array<string, string> $data, ?string $pdfHref = null	ห่อแมปไว้ใน XfdfData แล้วมอบหมายต่อ	string (XFDF XML)	—	—
XfdfWriter::fromXfdfData	XfdfData $data, ?string $pdfHref = null	ทำ serialization เป็น XFDF ชื่อแบบ dot-notation จะซ้อนกันเป็นอิลิเมนต์ <field> แบบลำดับชั้น	string (XFDF XML)	—	ตัดอักขระควบคุมที่ผิดกฎ XML 1.0 ออก ดูข้อกำหนดด้านพฤติกรรม
XfdfParser::parse	string $xfdfXml	โหลด XML แบบปลอดภัยจาก XXE และแผ่ฟิลด์ให้เป็น dot notation	XfdfData	InvalidArgumentException	เพดานอินพุต 10 MiB รับรากทั้งแบบมีเนมสเปซและไม่มีเนมสเปซ
XfdfParser::parseFile	string $filePath	แปลงพาธ อ่านไฟล์ แล้วมอบหมายให้ parse	XfdfData	InvalidArgumentException	พาธที่ไม่มีอยู่ ไม่ใช่ไฟล์ หรืออ่านไม่ได้จะทำให้เกิดข้อยกเว้น
XfaParser::parse	string $pdfData	ตรวจมาร์กเกอร์ สกัด XML แจงแพ็กเก็ต	XfaFormData	InvalidArgumentException, XfaParseException	หากไม่มีมาร์กเกอร์ /XFA จะคืนผลลัพธ์ว่าง ไม่ใช่ข้อผิดพลาด
XfaParser::hasXfa	string $pdfData	สแกนไบต์เพื่อหามาร์กเกอร์ /XFA	bool	—	การสแกนมาร์กเกอร์ระดับไบต์ โทเคนที่ปรากฏที่ใดก็ตามถือว่าตรงกัน
XfaParser::extractXfaXml	string $pdfData	สแกนสตรีมหามาร์กเกอร์ XFA แล้วค้นหา <xdp:xdp> โดยตรง	string (XFA XML or '')	RuntimeException (ประกาศไว้)	สแกนอินพุตไม่เกิน 50 MiB แรกเท่านั้น
XfaParser::parseXml	string $xml	สกัดแพ็กเก็ต template และ datasets แจงอิลิเมนต์ <field>	XfaFormData	XfaParseException	เพดาน XML 10 MiB บังคับใช้ก่อนโหลด DOM
FormDataBinder::bind	list<FormField> $fields, XfdfData $data	สร้างอินสแตนซ์ FormField ใหม่พร้อมค่าที่ผูกแล้ว	FormDataBindResult	—	ต้นฉบับไม่ถูกแก้ไข ช่องกาเครื่องหมายจะถูกปรับให้เป็น Yes/Off
FormDataBinder::fromXfdf	list<FormField> $fields, string $xfdfXml	แจง XFDF แล้วจึงผูก	FormDataBindResult	InvalidArgumentException	โหมดความล้มเหลวเป็นเช่นเดียวกับ XfdfParser::parse
FormDataBinder::fromArray	list<FormField> $fields, array<string, string> $data	ห่อแมปไว้ใน XfdfData แล้วจึงผูก	FormDataBindResult	—	—
FormDataBindResult	isFullyBound, hasNoUnmatchedKeys, boundCount, fieldCount; readonly fields, boundFieldNames, unmatchedDataKeys, unboundFieldNames	ข้อมูลวินิจฉัยการผูกแบบไม่เปลี่ยนรูป	แล้วแต่เมท็อด	—	isFullyBound ต้องไม่มีคีย์ที่จับคู่ไม่ได้และไม่มีฟิลด์ที่ไม่ได้ผูกเลย
XfdfData	hasField, getValue, count, isEmpty, getFieldNames, withField, withoutField, merge; readonly fields	คอนเทนเนอร์ชื่อ-ค่าแบบไม่เปลี่ยนรูป	แล้วแต่เมท็อด	—	with* และ merge คืนอินสแตนซ์ใหม่ merge ให้ความสำคัญกับค่าจากอาร์กิวเมนต์
XfaFormData	getField, hasField, count, fieldNames; readonly fields, templateXml, datasetsXml	ผลการแจง XFA แบบไม่เปลี่ยนรูป	แล้วแต่เมท็อด	—	พก XML ดิบของแพ็กเก็ต template และ datasets ไว้สำหรับการรับส่งไปกลับ
XfaFormField	readonly name, type, value, required, caption, options	เรกคอร์ดฟิลด์เดี่ยวแบบไม่เปลี่ยนรูป	—	—	type เป็นหนึ่งใน text, numeric, date, choice, button, signature
XfaPacket	กรณี enum Template, Datasets, Config, LocaleSet, ConnectionSet, Form; xmlNamespace()	การแจกแจงแพ็กเก็ตที่หนุนด้วยสตริง	string จาก xmlNamespace()	—	URI ของเนมสเปซเป็นไปตาม 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

ข้อยกเว้น

• NextPDF\Pro\Form\Exception\XfaParseException สืบทอดจาก RuntimeException — เพย์โหลด XFA ไม่สามารถแจงเป็น XfaFormData ได้ การสืบคลาสนี้เป็นความตั้งใจ: จุดเรียก catch (RuntimeException $e) ที่มีอยู่เดิมยังคงทำงานได้
• SPL InvalidArgumentException — อินพุตที่ว่าง ใหญ่เกิน ผิดรูปแบบ หรือไม่ใช่ XFDF ที่ส่งให้ XfdfParser อินพุต PDF ว่างที่ส่งให้ XfaParser::parse และพาธที่อ่านไม่ได้ใน XfdfParser::parseFile

ข้อกำหนดด้านพฤติกรรม

การสกัด AcroForm FormDataExtractor เดินอ่านรายการฟิลด์ที่คุณส่งเข้ามาและอ่านชื่อกับค่าของแต่ละฟิลด์ extract คืนค่า XfdfData ส่วน toArray คืนแมปสตริงชื่อ-ค่าแบบธรรมดา extractNonEmpty ตัดฟิลด์ที่มีค่าเป็นสตริงว่างออก ส่วน getEmptyFieldNames คืนรายชื่อที่เป็นส่วนเติมเต็ม การสกัดไม่เคยเปลี่ยนแปลงฟิลด์อินพุต

การเขียน XFDF XfdfWriter สร้างเอกสารที่สอดคล้องกับโครงสร้าง ISO 19444-1:2019 เอาต์พุตขึ้นต้นด้วยการประกาศ XFDF XML และรูท xfdf ในเนมสเปซ Adobe XFDF (http://ns.adobe.com/xfdf/) พร้อม xml:space="preserve" pdfHref ที่ไม่เป็น null จะปล่อยการอ้างอิง <f href="..."/> กลับไปยัง PDF ต้นทาง ชื่อฟิลด์แบบ dot-notation (เช่น address.city) จะซ้อนกันเป็นต้นไม้อิลิเมนต์ <field> แบบลำดับชั้น ค่าและแอตทริบิวต์จะ escape อักขระเมทาของ XML ทั้งห้าตัว ชื่อฟิลด์ ค่า และ pdfHref ยังถูกปรับให้อยู่ในรูปแบบที่ถูกต้องเพิ่มเติม: อักขระควบคุม C0 ที่ XML 1.0 ห้ามไว้จะถูกตัดออก ขณะที่ TAB, LF และ CR ยังคงอยู่ การปรับนี้สูญเสียข้อมูลโดยการออกแบบ ดังนั้นตัวเขียนจึงปล่อย XFDF ที่ถูกรูปแบบและแจงซ้ำได้เสมอ ไม่ว่าผู้เรียกจะส่งไบต์ใดมา

การอ่าน XFDF XfdfParser รับรูท xfdf ทั้งแบบมีเนมสเปซและไม่มีเนมสเปซ และจับคู่ชื่อรูทแบบไม่สนตัวพิมพ์ใหญ่เล็ก เพราะผู้ผลิตบางรายปล่อยอิลิเมนต์รูทเป็นตัวพิมพ์ใหญ่ ต้นไม้ <field> แบบลำดับชั้นจะถูกแผ่กลับเป็นชื่อแบบ dot-notation ดังนั้นการเขียนและอ่านจึงรับส่งไปกลับได้ครบ การโหลด XML ทั้งหมดปิดการเข้าถึงเครือข่ายและการแปลงค่า external-entity parseFile เพิ่มการแปลงพาธและการตรวจสอบความสามารถในการอ่านไว้ก่อนการแจงเดียวกัน

การผูกข้อมูล FormDataBinder::bind จับคู่คีย์ข้อมูลกับชื่อฟิลด์ เนื่องจาก FormField ไม่เปลี่ยนรูป การผูกจึงสร้างอินสแตนซ์ใหม่พร้อมค่าที่อัปเดตแล้ว ต้นฉบับไม่ถูกแก้ไข ผลลัพธ์รายงานชุดข้อมูลวินิจฉัยสามชุด: ชื่อฟิลด์ที่ผูกแล้ว คีย์ข้อมูลที่ไม่มีฟิลด์ตรงกัน และฟิลด์ที่ไม่ได้รับข้อมูล ค่าของช่องกาเครื่องหมายจะถูกปรับให้เข้ากับแบบจำลองสถานะ on/off ของ ISO 32000-2:2020, 12.7.5.2.3: yes, true, 1 และ on โดยไม่สนตัวพิมพ์ใหญ่เล็กจะแมปเป็น Yes ค่าอื่นทั้งหมดแมปเป็น Off

การสกัดข้อมูล XFA XfaParser::parse รับไบต์ PDF ดิบ ขั้นแรกจะสแกนหามาร์กเกอร์ /XFA หากไม่มีมาร์กเกอร์จะคืน XfaFormData ว่าง จากนั้นการสกัดจะลองสองกลยุทธ์: สแกนบล็อก stream…endstream เพื่อหาตัวบ่งชี้ XFA XML แล้วค้นหาเอกสาร <xdp:xdp> โดยตรง ชิ้นส่วน xdp:xdp เดี่ยวจะถูกคืนตามเดิม ส่วนหลายชิ้นส่วนจะถูกต่อเข้าด้วยกันเป็นซอง xdp:xdp ที่สังเคราะห์ขึ้น parseXml สกัดแพ็กเก็ต template และ datasets แล้วแจงอิลิเมนต์ <field> ของ template แต่ละตัวให้เป็น XfaFormField: แอตทริบิวต์ name จำเป็นต้องมี ประเภทได้มาจากอิลิเมนต์ลูก UI ของฟิลด์ แฟล็ก required ได้มาจากอิลิเมนต์ validate ที่ตั้ง nullTest เป็น error และตัวเลือกแบบ choice มาจากลูก items

การรองรับ XFA เน้นข้อมูลเป็นหลัก ตัวแจงจัดโครงสร้างแพ็กเก็ต template และ datasets โดยไม่รันสคริปต์คำนวณ XFA ไม่เรนเดอร์เลย์เอาต์ XFA แบบไดนามิก และไม่รับส่งแพ็กเก็ตทุกประเภทไปกลับ ให้ตรวจสอบตัวแจงกับชุดเอกสารเฉพาะของคุณก่อนพึ่งพา

กรณีขอบและโหมดความล้มเหลว

• XfdfParser::parse('') โยน InvalidArgumentException อินพุตที่เกิน 10 MiB โยน InvalidArgumentException ที่ระบุเพดานไว้
• XML ที่ผิดรูปแบบโยน InvalidArgumentException ที่พกข้อความ libxml ที่รวบรวมไว้ เอกสารที่ถูกรูปแบบแต่มีรูทที่ไม่ใช่ xfdf จะโยนและระบุอิลิเมนต์รูทจริง
• เอกสาร XFDF ที่ไม่มีอิลิเมนต์ <fields> จะแจงเป็น XfdfData ว่าง ซึ่งไม่ใช่ข้อผิดพลาด
• อิลิเมนต์ฟิลด์ที่ไม่มีแอตทริบิวต์ name จะถูกข้ามทั้งในการแจง XFDF และ XFA ฟิลด์ XFDF ที่ไม่มีลูก <value> จะไม่เพิ่มรายการใด
• XfaParser::parse('') โยน InvalidArgumentException PDF ที่ไม่มีมาร์กเกอร์ /XFA หรือที่หา XFA XML ไม่พบ จะคืน XfaFormData ว่างแทนการโยนข้อยกเว้น
• hasXfa เป็นการสแกนมาร์กเกอร์ระดับไบต์: โทเคน /XFA ใด ๆ ในไฟล์ถือว่าตรงกัน รวมถึงโทเคนในอ็อบเจกต์ที่ไม่ได้ใช้ ขั้นตอนการสกัดที่ตามมาจะเป็นตัวตัดสินว่ามี XML ที่ใช้ได้หรือไม่
• การสกัด XFA ตรวจสอบไบต์สตริงของ PDF ไม่เกิน 50 MiB แรกเท่านั้น เนื้อหาที่เกินขอบเขตนั้นจะไม่ถูกสแกน
• XFA XML ที่เกิน 10 MiB โยน XfaParseException ก่อนที่จะสร้างต้นไม้ DOM ใด ๆ XFA XML ที่ผิดรูปแบบโยน XfaParseException พร้อมข้อความ libxml
• การปรับค่าช่องกาเครื่องหมายไม่เคยปล่อยค่าที่ไม่รู้จักผ่านไป สิ่งใดที่อยู่นอกรูปแบบ on ที่ยอมรับจะแมปเป็น Off
• การตัดอักขระควบคุมของตัวเขียนสูญเสียข้อมูล: ไบต์ C0 ที่ผิดกฎ XML 1.0 ในชื่อ ค่า หรือ pdfHref จะถูกตัดออกเพื่อให้เอาต์พุตยังคงถูกรูปแบบ TAB, LF และ CR ยังคงอยู่
• การแจง XML ทั้งหมดปิดการแปลงค่า external-entity และการเข้าถึงเครือข่าย (ปลอดภัยจาก XXE)
• โมดูลนี้ไม่ทำการดำเนินการเข้ารหัสลับใด ๆ โหมด FIPS ไม่เปลี่ยนพฤติกรรมของมัน

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

พฤติกรรม	อ้างอิง	สถานะ
แบบจำลองฟอร์มแบบโต้ตอบ / field dictionary	ISO 32000-2:2020, 12.7	สอดคล้อง (อ้างอิงจากผลิตภัณฑ์)
การปรับสถานะ on/off ของช่องกาเครื่องหมาย (Yes/Off)	ISO 32000-2:2020, 12.7.5.2.3	สอดคล้อง อ้างถึงข้อกำหนดในบันทึกการอ้างอิงของหน้านี้
โครงสร้างการแลกเปลี่ยนข้อมูล XFDF	ISO 19444-1:2019	สอดคล้อง (อ้างอิงจากผลิตภัณฑ์)
ชื่อแพ็กเก็ต XFA และ URI ของเนมสเปซ	XFA Specification 3.3	สอดคล้อง (อ้างอิงจากผลิตภัณฑ์)

คลัง RAG ที่มีอยู่ ณ เวลาเขียนไม่รวม ISO 19444-1:2019, XFA Specification หรือ W3C XML 1.0 ดังนั้นคำกล่าวเรื่องความสอดคล้องเหล่านั้นจึงอ้างอิงจากผลิตภัณฑ์โดยมาจากคำอธิบายในซอร์สและการทดสอบ ไม่ใช่การอ้างข้อกำหนด คำกล่าวเหล่านี้อธิบายความสามารถเทียบกับเอกสารที่อ้างถึง NextPDF ไม่ได้ถือการรับรองความสอดคล้องใด ๆ และการรองรับข้อกำหนดหนึ่งไม่ใช่การอ้างการรับรอง

บันทึกการพัฒนา

• จุดเข้าใช้งานทุกจุดยกเว้น XfaParser เป็นแบบ static XfaParser สร้างอินสแตนซ์ได้และไม่มีสถานะ หนึ่งอินสแตนซ์ปลอดภัยที่จะนำกลับมาใช้ซ้ำข้ามเอกสาร
• การรับส่งไปกลับที่ตั้งใจไว้คือ: ตัวอ่านฟอร์มของ Core ผลิตค่า FormField FormDataExtractor หรือ XfdfWriter ทำ serialization ค่าเหล่านั้น XfdfParser อ่านข้อมูลกลับ และ FormDataBinder นำไปใช้กับรายการฟิลด์ ชื่อแบบลำดับชั้นคงอยู่ตลอดการรับส่งไปกลับผ่าน dot notation
• ใช้ข้อมูลวินิจฉัยของ FormDataBindResult (isFullyBound, unmatchedDataKeys, unboundFieldNames) เพื่อตรวจจับความคลาดเคลื่อนระหว่างไฟล์ข้อมูล XFDF กับ template PDF ที่ปรับปรุงแล้วก่อนยอมรับการกรอก
• XfdfData เป็นอ็อบเจกต์ค่า: withField, withoutField และ merge คืนอินสแตนซ์ใหม่ เมื่อคีย์ชนกัน merge ให้ความสำคัญกับค่าจากอาร์กิวเมนต์
• XfaFormData เก็บ XML ดิบของแพ็กเก็ต template และ datasets ไว้ (templateXml, datasetsXml) เพื่อให้คุณประมวลผลภายหลังกับแพ็กเก็ตที่แบบจำลองฟิลด์ไม่ครอบคลุมได้
• โมดูลนี้ไม่ได้แจง AcroForm dictionary ออกจากไบต์ PDF ด้วยตัวเอง แต่รับฟิลด์ที่ผลิตโดยตัวอ่านฟอร์มของ Core มีเพียง XfaParser เท่านั้นที่ทำงานกับเนื้อหา PDF ดิบ

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

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

ดูเพิ่มเติม

• Form — ภาพรวมความสามารถ
• Interop — การอ้างอิงเชิงลึก
• โมดูล Core Form