Form: ฟิลด์แบบโต้ตอบของ AcroForm และการ Flatten

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

โมดูล Form ใช้สร้างฟอร์มแบบโต้ตอบสำหรับเอกสาร Portable Document Format (PDF) โมดูลนี้สร้างฟิลด์ text, checkbox, radio, choice (list/combo), button และ signature จัดระเบียบฟิลด์เหล่านี้เป็นลำดับชั้นแบบ parent/child เขียนฟิลด์เป็น PDF object พร้อม appearance stream และสามารถ flatten ฟอร์มให้กลายเป็นเนื้อหาหน้าแบบสแตติกได้

การติดตั้ง

composer require nextpdf/core:^3

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

ฟอร์ม PDF แบบโต้ตอบคือ AcroForm ซึ่งเป็นลำดับชั้นของฟิลด์ระดับเอกสาร โดยฟิลด์ปลายทางจะจับคู่กับ widget annotation บนหน้าเอกสาร ตามที่ ISO 32000-2 §12.7 กำหนดไว้สำหรับฟอร์มประเภทนี้ รวมถึง field dictionary, AcroForm root และลำดับชั้นฟิลด์ โมดูลนี้เข้ารหัสโครงสร้างเหล่านั้นให้เอนจินใช้งาน

FormFieldManager เป็น API หลัก โมดูลมีตัวสร้าง textField(), checkBox(), radioButton(), button() และ signatureField() สำหรับติดตามฟิลด์ และซีเรียลไลซ์ฟิลด์ด้วย writeFields() โมดูลสร้าง Form XObject appearance stream หนึ่งรายการสำหรับ widget แต่ละตัว (/Subtype /Form, /BBox) ตามที่ §8.10 กำหนด FormField เป็น value object ของฟิลด์ FormFieldDictionaryBuilder แปลงฟิลด์เป็น PDF dictionary ของฟิลด์ และใส่รายการเฉพาะตามชนิดและบิตของแฟล็กสำหรับฟิลด์ text, checkbox, choice และ button manager และ FormField เป็น @since 1.0.0 ส่วน dictionary builder เป็น @since 1.1.0

FormFieldHierarchy สร้างโมเดลต้นไม้ฟิลด์แบบ parent/child ด้วย addChild(), getRootFieldNames(), getChildren(), getParent() และ visitor walkDepthFirst() ชื่อฟิลด์แบบ fully-qualified คือเส้นทางที่คั่นด้วยจุดผ่านลำดับชั้นนี้ ซึ่งตรงกับโมเดลฟิลด์ซ้อนใน §12.7

FormFlattener เรนเดอร์ฟอร์มให้เป็นเนื้อหาหน้าแบบสแตติก flatten() คืนค่าเป็น FlattenResult จึงสามารถตรึงฟอร์มที่กรอกแล้วไว้เพื่อจัดเก็บถาวรได้ FieldMDP และ FieldMdpAction สร้างโมเดลของการแปลงสำหรับล็อกฟิลด์ เอกสารที่ลงนามแล้วสามารถล็อกชุดฟิลด์ที่ระบุชื่อไว้ไม่ให้แก้ไขเพิ่มเติมได้ FieldMdpAction ระบุขอบเขตของการล็อก และ requiresFieldList() บอกว่าเมื่อใดจำเป็นต้องระบุรายการฟิลด์อย่างชัดเจน FieldMDP เป็น @since 2.0.0

พื้นผิว API

คลาส	สมาชิกหลัก	บทบาท
`FormFieldManager`	`textField()`, `checkBox()`, `radioButton()`, `button()`, `signatureField()`, `addChildField()`, `getHierarchy()`, `writeFields()`	ตัวสร้างฟิลด์ + ตัวซีเรียลไลซ์ (`@since 1.0.0`)
`FormField`	value object ของฟิลด์	ฟิลด์ AcroForm หนึ่งฟิลด์ (`@since 1.0.0`)
`FormFieldDictionaryBuilder`	`buildFieldDictionary()`, `applyTextFieldOptions()`, `applyCheckBoxOptions()`, `applyChoiceFieldOptions()`, `applyButtonOptions()`	ตัวสร้าง dictionary จากฟิลด์ (`@since 1.1.0`)
`FormFieldHierarchy`	`addChild()`, `getRootFieldNames()`, `getChildren()`, `getParent()`, `walkDepthFirst()`	ต้นไม้ฟิลด์แบบ parent/child (`@since 2.0.0`)
`FormFlattener`	`flatten(array $fields, array $pages): FlattenResult`	Flatten ฟอร์มให้เป็นเนื้อหาแบบสแตติก (`@since 1.0.0`)
`FieldMDP`	`toTransformParams()`	การแปลงเพื่อล็อกฟิลด์ (FieldMDP) (`@since 2.0.0`)
`FieldMdpAction` (enum)	`requiresFieldList()`	ขอบเขตการล็อกฟิลด์ (`@since 2.0.0`)

เรียกใช้ composer docs:generate-api-php -- --module=Form เพื่อสร้างตาราง PHPDoc แบบเต็ม

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

แหล่งที่มา: examples/30-form-fields.php

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Form\FormFieldManager;

$form = new FormFieldManager();

$form->textField(name: 'applicant_name', x: 50, y: 700, w: 200, h: 18);
$form->checkBox(name: 'agree_terms', x: 50, y: 660, size: 12);
$form->radioButton(name: 'plan', x: 50, y: 620, size: 12 /* + option set */);

// The Writer invokes $form->writeFields(...) during document serialization.

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

สร้างชุดฟิลด์ของเอกสารที่ลงนาม จากนั้นล็อกฟิลด์ที่ลงนามแล้วด้วย FieldMDP

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Form\FieldMDP;
use NextPDF\Form\FieldMdpAction;
use NextPDF\Form\FormFieldManager;

$form = new FormFieldManager();
$form->textField(name: 'contract_value', x: 50, y: 700, w: 160, h: 18);
$form->signatureField(name: 'approver_sig', x: 50, y: 600, w: 200, h: 60);

// Lock only the named fields after signing.
$lock = new FieldMDP(
    action: FieldMdpAction::Include,
    fields: ['contract_value'],
);

$transformParams = $lock->toTransformParams();
// $transformParams is attached to the signature's transform method by the signing layer.

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

ชื่อฟิลด์คือเส้นทางแบบ fully-qualified ที่คั่นด้วยจุดผ่าน FormFieldHierarchy ในโปรแกรมดู ฟิลด์ปลายทางสองฟิลด์ที่มีชื่อ fully-qualified เดียวกันคือฟิลด์เชิงตรรกะเดียวกัน คุณมีหน้าที่ทำให้ชื่อไม่ซ้ำกัน
FieldMdpAction::requiresFieldList() บอกว่าเมื่อใดจำเป็นต้องระบุรายการฟิลด์ การกระทำ Include/Exclude ที่ไม่มีรายการที่จำเป็นจะสร้างการล็อกที่มีรูปแบบไม่ถูกต้อง ให้ตรวจสอบแฟล็ก
FormFlattener::flatten() ลบความสามารถในการโต้ตอบออกโดยเจตนา ผลลัพธ์คือเนื้อหาแบบสแตติก ให้เก็บแหล่งที่มาแบบโต้ตอบไว้หากต้องใช้อีกในภายหลัง
appearance stream ถูกสร้างต่อ widget แต่ละตัว ฟิลด์ที่ไม่มี appearance อาจเรนเดอร์ไม่สอดคล้องกันในโปรแกรมดูแต่ละตัว ให้ manager สร้าง appearance แทนการละเว้น
signatureField() สร้างเฉพาะ placeholder ของฟิลด์เท่านั้น เลเยอร์ Security/signing เป็นผู้สร้างลายเซ็นจริง ไม่ใช่โมดูลนี้

ประสิทธิภาพ

การสร้างฟิลด์และการซีเรียลไลซ์เป็น O(n) ตามจำนวนฟิลด์ บวกกับ Form XObject appearance stream หนึ่งรายการต่อ widget แต่ละตัว ต้นทุนการ flatten ขึ้นอยู่กับเนื้อหาที่เรนเดอร์ ไม่ใช่จำนวนฟิลด์ เวิร์กโหลดอ้างอิงค่าเริ่มต้นอยู่ภายในงบ wall 1500 ms / peak 64 MB โปรไฟล์ความสามารถในการทำซ้ำเป็น structural หมายเลข object และ /ID ของ trailer จะแตกต่างกันในแต่ละครั้งที่รัน เอกสารสองชุดที่มีฟอร์มเดียวกันจะเท่ากันในเชิงโครงสร้าง แต่ไม่เหมือนกันในระดับไบต์

หมายเหตุด้านความปลอดภัย

ค่าฟิลด์ของฟอร์มเป็นอินพุตจากผู้ใช้ โมดูล escape ค่าสตริงสำหรับการซีเรียลไลซ์ PDF ด้วย PdfStringEscaper ดังนั้นค่าฟิลด์จึงไม่สามารถหลุดออกจาก PDF string ของตนเองและฉีดโครงสร้างเข้ามาได้ เมื่อฟอร์มถูกเข้ารหัสลับ การเข้ารหัสลับ AES-256 ของเอกสารจะครอบคลุมเนื้อหาของฟิลด์ FieldMDP เป็นการควบคุมด้านความปลอดภัย โดยจะล็อกฟิลด์ที่ระบุชื่อไว้ไม่ให้แก้ไขหลังการลงนาม การล็อกฟิลด์ที่ไม่ตรงกับชุดฟิลด์ที่ลงนามจะบ่อนทำลายการควบคุมนั้น ให้กำหนดขอบเขตการล็อกอย่างรอบคอบ ให้ถือว่าค่าใด ๆ ที่ดึงมาจากฟอร์มที่กรอกแล้วเป็นอินพุตที่ไม่น่าเชื่อถือ ดูโมเดลความปลอดภัยของเอนจินได้ที่ /modules/core/security/

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

โครงสร้างฟอร์มที่โมดูลนี้สร้างเป็นไปตามโมเดลฟอร์มแบบโต้ตอบใน ISO 32000-2 §12.7 ได้แก่ AcroForm root, field dictionary และลำดับชั้นฟิลด์ของเอกสาร appearance ต่อ widget ถูกสร้างเป็น Form XObject ตาม §8.10 และมีเอกสารกำกับแบบอินไลน์ใน src/Form/ tests/Unit/Form/ ทดสอบข้อเท็จจริงของการนำไปใช้เหล่านี้ สิ่งเหล่านี้ไม่ใช่คำรับรองความสอดคล้อง PDF 2.0 แบบ end-to-end ความสอดคล้องของทั้งเอกสารได้รับการตรวจสอบโดย oracle และ golden suite ใน /modules/core/conformance/

ดูเพิ่มเติม

โมดูล Navigation — widget annotation ที่จับคู่กับฟิลด์
โมดูล Security — โมเดลความน่าเชื่อถือของการลงนามและ FieldMDP
โมดูล Accessibility — การติดแท็กฟิลด์ฟอร์มสำหรับ PDF/UA
ภาพรวมความสอดคล้องตามมาตรฐาน