Form: AcroForm 대화형 필드와 평탄화
한눈에 보기
섹션 제목: “한눈에 보기”Form 모듈은 PDF 대화형 양식을 구성합니다. 텍스트, 체크박스, 라디오, 선택(목록/콤보), 버튼, 서명 필드를 만들고, 이를 parent/child 계층 구조로 구성합니다. 또한 외관 스트림을 포함한 PDF 객체로 기록하며, 양식을 정적 페이지 콘텐츠로 평탄화할 수 있습니다.
composer require nextpdf/core:^3개념 개요
섹션 제목: “개념 개요”PDF 대화형 양식은 AcroForm입니다. 즉, 문서 수준의 필드 계층 구조이며 말단 필드는 페이지의 위젯 주석과 짝을 이룹니다. ISO 32000-2 §12.7 에서는 AcroForm 루트와 필드 계층 구조를 포함하여 양식 및 필드 딕셔너리를 정의합니다. 이 모듈은 해당 구조를 엔진에서 인코딩하는 역할을 합니다.
FormFieldManager가 기본 API 표면입니다. 이 클래스는 textField(), checkBox(), radioButton(), button(), signatureField() 빌더를 제공하고, 필드를 추적하며, writeFields()로 직렬화합니다. §8.10 에서 요구하는 대로 위젯마다 Form XObject 외관 스트림(/Subtype /Form, /BBox)을 내보냅니다. FormField는 필드 값 객체입니다. FormFieldDictionaryBuilder는 필드를 해당 PDF 딕셔너리로 변환하고, 유형별 항목과 플래그 비트(텍스트, 체크박스, 선택, 버튼)를 적용합니다. 매니저와 FormField는 @since 1.0.0입니다. 딕셔너리 빌더는 @since 1.1.0입니다.
FormFieldHierarchy는 parent/child 필드 트리를 모델링하며, addChild(), getRootFieldNames(), getChildren(), getParent(), 그리고 walkDepthFirst() 방문자를 제공합니다. 정규화된 필드 이름은 이 계층 구조를 따라가는 점 구분 경로이며, 이는 §12.7 에서 중첩 필드에 대해 규정한 모델입니다.
FormFlattener는 양식을 정적 페이지 콘텐츠로 렌더링합니다 — flatten()은 FlattenResult를 반환합니다 — 따라서 작성된 양식을 보관용으로 고정할 수 있습니다. FieldMDP와 FieldMdpAction은 필드 잠금 변환을 모델링합니다. 서명된 문서는 이름이 지정된 필드 집합을 추가 수정으로부터 잠글 수 있습니다. FieldMdpAction은 잠금 범위를 열거합니다. requiresFieldList()는 명시적인 필드 목록이 필수인 경우를 나타냅니다. FieldMDP는 @since 2.0.0입니다.
API 표면
섹션 제목: “API 표면”| 클래스 | 주요 멤버 | 역할 |
|---|---|---|
FormFieldManager | textField(), checkBox(), radioButton(), button(), signatureField(), addChildField(), getHierarchy(), writeFields() | 필드 빌더 + 직렬화기 (@since 1.0.0) |
FormField | 필드 값 객체 | 하나의 AcroForm 필드 (@since 1.0.0) |
FormFieldDictionaryBuilder | buildFieldDictionary(), applyTextFieldOptions(), applyCheckBoxOptions(), applyChoiceFieldOptions(), applyButtonOptions() | 필드-딕셔너리 빌더 (@since 1.1.0) |
FormFieldHierarchy | addChild(), getRootFieldNames(), getChildren(), getParent(), walkDepthFirst() | Parent/child 필드 트리 (@since 2.0.0) |
FormFlattener | flatten(array $fields, array $pages): FlattenResult | 양식을 정적 콘텐츠로 평탄화합니다 (@since 1.0.0) |
FieldMDP | toTransformParams() | 필드 잠금(FieldMDP) 변환 (@since 2.0.0) |
FieldMdpAction (열거형) | requiresFieldList() | 필드 잠금 범위 (@since 2.0.0) |
전체 PHPDoc 표는 composer docs:generate-api-php -- --module=Form을 실행해 확인하십시오.
코드 샘플 — 빠른 시작
섹션 제목: “코드 샘플 — 빠른 시작”소스: 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.엣지 케이스 및 함정
섹션 제목: “엣지 케이스 및 함정”- 필드 이름은
FormFieldHierarchy를 따라가는 정규화된 점 구분 경로입니다. 정규화된 이름이 동일한 두 말단 필드는 뷰어에서 동일한 논리적 필드로 취급됩니다 — 고유성은 호출자의 책임입니다. FieldMdpAction::requiresFieldList()는 필드 목록이 필수인 경우를 알려줍니다. 필수 목록이 없는Include/Exclude작업은 잘못된 형식의 잠금입니다. 플래그를 확인하십시오.FormFlattener::flatten()은 설계상 대화형 기능을 제거합니다 — 결과는 정적 콘텐츠입니다. 나중에 필요하면 대화형 원본을 보존하십시오.- 외관 스트림은 위젯마다 내보내집니다. 외관이 없는 필드는 뷰어마다 일관성 없이 렌더링됩니다. 외관을 생략하지 말고 매니저가 생성하도록 하십시오.
signatureField()는 필드 자리 표시자만 생성합니다. 실제 서명 생성은 이 모듈이 아니라 Security/서명 계층의 역할입니다.
필드 생성과 직렬화는 필드 수에 대해 O(n)이며, 여기에 위젯마다 하나의 Form XObject 외관 스트림이 추가됩니다. 평탄화 비용은 필드 수가 아니라 렌더링된 콘텐츠에 따라 증가합니다. 기본 참조 워크로드는 1500 ms 벽시계 시간 / 64 MB 피크 예산 이내입니다. 재현성 프로파일은 structural입니다. 즉, 객체 번호와 트레일러 /ID는 실행마다 달라집니다. 동일한 양식을 가진 두 문서는 구조적으로는 같지만 바이트 단위로 동일하지는 않습니다.
보안 참고
섹션 제목: “보안 참고”양식 필드 값은 사용자 입력입니다. 이 모듈은 PDF 직렬화를 위해 문자열 값을 이스케이프(PdfStringEscaper)하므로, 필드 값이 자신의 PDF 문자열을 벗어나 구조를 주입할 수 없습니다. 양식이 암호화되면 필드 콘텐츠는 문서의 AES-256 암호화로 보호됩니다. FieldMDP는 보안 제어입니다. 즉, 이름이 지정된 필드를 서명 이후 수정으로부터 잠급니다. 서명된 필드 집합과 일치하지 않는 필드 잠금은 이 제어를 약화시킵니다 — 잠금 범위를 신중하게 설정하십시오. 작성된 양식에서 추출한 값은 모두 신뢰할 수 없는 입력으로 취급하십시오. 엔진의 보안 모델은 /modules/core/security/를 참조하십시오.
적합성
섹션 제목: “적합성”이 모듈이 내보내는 양식 구조는 ISO 32000-2 §12.7 의 대화형 양식 모델 — AcroForm 루트와 필드 딕셔너리, 그리고 문서 필드 계층 구조 — 를 따릅니다. 위젯별 외관은 §8.10 에 따라 Form XObject 로 내보내지며, src/Form/ 안에 인라인으로 문서화되어 있습니다. 이는 tests/Unit/Form/로 검증되는 구현 사실이며, 종단 간 PDF 2.0 적합성에 대한 진술이 아닙니다. 전체 문서 적합성은 /modules/core/conformance/의 오라클 및 골든 스위트로 검증됩니다.
- Navigation 모듈 — 필드와 짝을 이루는 위젯 주석.
- Security 모듈 — 서명과 FieldMDP 신뢰 모델.
- Accessibility 모듈 — PDF/UA를 위한 양식 필드 태그 지정.
- 적합성 개요