Pro 에디션

Form — 심층 참조

한눈에 보기

이 페이지는 Pro Form 모듈의 심층 참조입니다. AcroForm 값 추출, XFDF 읽기 및 쓰기, 데이터 바인딩, XFA 데이터 추출을 다룹니다. 이 모듈은 Core form 리더가 생성한 NextPDF\Form\FormField 값을 소비하며, 그 위에 직렬화, 파싱, 바인딩을 더합니다. 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`	XFDF로 직렬화합니다. 점 표기법 이름은 계층적 `<field>` 요소로 중첩됩니다	`string` (XFDF XML)	—	XML 1.0에서 허용되지 않는 제어 문자를 제거합니다. 동작 계약을 참조하십시오.
`XfdfParser::parse`	`string $xfdfXml`	XML을 XXE 안전하게 로드하고 필드를 점 표기법으로 평탄화합니다	`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 또는 `''`)	`RuntimeException` (선언됨)	입력의 최대 처음 50 MiB까지만 스캔합니다.
`XfaParser::parseXml`	`string $xml`	template과 datasets 패킷을 추출하고 `<field>` 요소를 파싱합니다	`XfaFormData`	`XfaParseException`	10 MiB XML 상한. 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`는 일치하지 않는 키가 0개이고 바인딩되지 않은 필드가 0개일 것을 요구합니다.
`XfdfData`	`hasField`, `getValue`, `count`, `isEmpty`, `getFieldNames`, `withField`, `withoutField`, `merge`; readonly `fields`	불변 이름-값 컨테이너	메서드별	—	`with*`와 `merge`는 새 인스턴스를 반환합니다. `merge`는 인수의 값을 우선합니다.
`XfaFormData`	`getField`, `hasField`, `count`, `fieldNames`; readonly `fields`, `templateXml`, `datasetsXml`	불변 XFA 파싱 결과	메서드별	—	왕복을 위해 원시 template 및 datasets 패킷 XML을 담습니다.
`XfaFormField`	readonly `name`, `type`, `value`, `required`, `caption`, `options`	불변 단일 필드 레코드	—	—	`type`은 `text`, `numeric`, `date`, `choice`, `button`, `signature` 중 하나입니다.
`XfaPacket`	열거형 케이스 `Template`, `Datasets`, `Config`, `LocaleSet`, `ConnectionSet`, `Form`; `xmlNamespace()`	문자열 기반 패킷 열거형	`xmlNamespace()`에서 `string`	—	네임스페이스 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 — XfdfParser에 대한 비어 있거나, 크기가 초과되었거나, 잘못된 형식이거나, XFDF가 아닌 입력. XfaParser::parse에 대한 빈 PDF 입력. XfdfParser::parseFile의 읽을 수 없는 경로.

동작 계약

AcroForm 추출. FormDataExtractor는 전달한 필드 목록을 순회하며 각 필드의 이름과 값을 읽습니다. extract는 XfdfData를 반환하고, toArray는 단순한 이름-값 문자열 맵을 반환합니다. extractNonEmpty는 값이 빈 문자열인 필드를 버리고, getEmptyFieldNames는 그 여집합에 해당하는 이름 목록을 반환합니다. 추출은 입력 필드를 절대 변경하지 않습니다.

XFDF 쓰기. XfdfWriter는 ISO 19444-1:2019 구조를 따르는 문서를 생성합니다. 출력은 XFDF XML 선언과 Adobe XFDF 네임스페이스(http://ns.adobe.com/xfdf/)의 xfdf 루트로 시작하며 xml:space="preserve"를 갖습니다. null이 아닌 pdfHref는 원본 PDF를 가리키는 <f href="..."/> 참조를 내보냅니다. 점 표기법 필드 이름(예: address.city)은 계층적 <field> 요소 트리로 중첩됩니다. 값과 속성은 다섯 개의 XML 메타문자를 이스케이프합니다. 필드 이름, 값, pdfHref는 적격성(well-formedness)을 위해 추가로 정규화됩니다. XML 1.0이 금지하는 C0 제어 문자는 제거되고, TAB, LF, CR은 보존됩니다. 이 정규화는 설계상 손실이 있으므로, 라이터는 호출자가 제공한 바이트와 관계없이 항상 적격하고 다시 파싱 가능한 XFDF를 내보냅니다.

XFDF 읽기. XfdfParser는 네임스페이스가 있는 xfdf 루트와 없는 루트를 모두 받으며, 일부 생산자가 대문자 루트 요소를 내보내기 때문에 루트 이름을 대소문자 구분 없이 일치시킵니다. 계층적 <field> 트리는 다시 점 표기법 이름으로 평탄화되므로 쓰기와 읽기가 왕복됩니다. 모든 XML 로딩은 네트워크 접근과 외부 엔티티 해석을 비활성화합니다. parseFile은 동일한 파싱 앞에 경로 해석과 가독성 검사를 더합니다.

데이터 바인딩. FormDataBinder::bind는 데이터 키를 필드 이름과 대조합니다. FormField는 불변이므로 바인딩은 갱신된 값을 가진 새 인스턴스를 생성하며, 원본은 절대 수정되지 않습니다. 결과는 세 가지 진단 집합을 보고합니다. 바인딩된 필드 이름, 일치하는 필드가 없는 데이터 키, 데이터를 받지 못한 필드입니다. 확인란 값은 ISO 32000-2:2020, 12.7.5.2.3의 on/off 상태 모델로 정규화됩니다. 대소문자를 구분하지 않는 yes, true, 1, on은 Yes로 매핑되고, 그 외 모든 값은 Off로 매핑됩니다.

XFA 데이터 추출. XfaParser::parse는 원시 PDF 바이트를 받습니다. 먼저 /XFA 마커를 스캔하고, 마커가 없으면 빈 XfaFormData를 반환합니다. 그다음 추출은 두 가지 전략을 시도합니다. XFA XML 표시를 찾기 위한 stream…endstream 블록 스캔, 그리고 <xdp:xdp> 문서에 대한 직접 검색입니다. 단일 xdp:xdp 조각은 그대로 반환되고, 여러 조각은 합성된 xdp:xdp 엔벨로프로 연결됩니다. parseXml은 template과 datasets 패킷을 추출하고 각 template <field> 요소를 XfaFormField로 파싱합니다. name 속성은 필수이고, type은 필드의 UI 자식 요소에서 파생되며, required 플래그는 nullTest가 error로 설정된 validate 요소에서 파생되고, choice 옵션은 items 자식에서 옵니다.

XFA 지원은 데이터 지향적입니다. 파서는 template과 datasets 패킷을 구조화합니다. XFA 계산 스크립트를 실행하거나, 동적 XFA 레이아웃을 렌더링하거나, 모든 패킷 유형을 왕복하지는 않습니다. 의존하기 전에 특정 문서 집합에 대해 파서를 검증하십시오.

엣지 케이스 및 실패 모드

XfdfParser::parse('')는 InvalidArgumentException을 던집니다. 10 MiB를 초과하는 입력은 상한을 명시하는 InvalidArgumentException을 던집니다.
잘못된 형식의 XML은 수집된 libxml 메시지를 담은 InvalidArgumentException을 던집니다. 루트가 xfdf가 아닌 적격 문서는 예외를 던지며 실제 루트 요소를 명시합니다.
<fields> 요소가 없는 XFDF 문서는 빈 XfdfData로 파싱되며, 이는 오류가 아닙니다.
name 속성이 없는 필드 요소는 XFDF와 XFA 파싱 모두에서 건너뜁니다. <value> 자식이 없는 XFDF 필드는 항목을 만들지 않습니다.
XfaParser::parse('')는 InvalidArgumentException을 던집니다. /XFA 마커가 없거나 XFA XML을 찾을 수 없는 PDF는 예외를 던지는 대신 빈 XfaFormData를 반환합니다.
hasXfa는 바이트 마커 스캔입니다. 사용되지 않는 객체에 있는 것을 포함해, 파일 내 어떤 /XFA 토큰이든 일치합니다. 사용 가능한 XML이 존재하는지는 이어지는 추출 단계에서 결정됩니다.
XFA 추출은 PDF 바이트 문자열의 최대 처음 50 MiB까지만 검사하며, 그 경계를 넘는 내용은 스캔하지 않습니다.
10 MiB를 초과하는 XFA XML은 어떤 DOM 트리도 구체화되기 전에 XfaParseException을 던집니다. 잘못된 형식의 XFA XML은 libxml 메시지와 함께 XfaParseException을 던집니다.
확인란 정규화는 인식되지 않는 값을 절대 통과시키지 않습니다. 허용된 on 형식을 벗어나는 것은 모두 Off로 매핑됩니다.
라이터의 제어 문자 제거는 손실이 있습니다. 이름, 값, pdfHref에 있는 XML 1.0에서 허용되지 않는 C0 바이트는 출력이 적격 상태를 유지하도록 제거됩니다. TAB, LF, CR은 살아남습니다.
모든 XML 파싱은 외부 엔티티 해석과 네트워크 접근을 비활성화합니다(XXE 안전).
이 모듈은 어떠한 암호화 연산도 수행하지 않으며, FIPS 모드는 그 동작을 변경하지 않습니다.

적합성

동작	참조	상태
대화형 폼 / 필드 사전 모델	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를 제외한 모든 진입점은 정적입니다. XfaParser는 인스턴스화 가능하며 상태가 없습니다. 하나의 인스턴스를 여러 문서에 걸쳐 재사용해도 안전합니다.
의도된 왕복은 다음과 같습니다. Core form 리더가 FormField 값을 생성하고, FormDataExtractor 또는 XfdfWriter가 이를 직렬화하며, XfdfParser가 데이터를 다시 읽고, FormDataBinder가 이를 필드 목록에 적용합니다. 계층적 이름은 점 표기법을 통해 왕복에서 살아남습니다.
FormDataBindResult 진단(isFullyBound, unmatchedDataKeys, unboundFieldNames)을 사용하여 채우기를 수락하기 전에 XFDF 데이터 파일과 수정된 PDF template 사이의 불일치를 감지하십시오.
XfdfData는 값 객체입니다. withField, withoutField, merge는 새 인스턴스를 반환합니다. 키 충돌 시 merge는 인수의 값을 우선합니다.
XfaFormData는 원시 template 및 datasets 패킷 XML(templateXml, datasetsXml)을 유지하므로, 필드 모델이 다루지 않는 패킷을 후처리할 수 있습니다.
이 모듈은 PDF 바이트에서 AcroForm 사전을 직접 파싱하지 않습니다. Core form 리더가 생성한 필드를 소비합니다. 오직 XfaParser만 원시 PDF 콘텐츠에서 작동합니다.

게시 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만을 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 표, 런북 파일명, 티켓 접두사는 범위를 벗어납니다.