Pro edycja

Form — szczegółowa dokumentacja referencyjna

W skrócie

Ta strona to szczegółowa dokumentacja referencyjna modułu Pro Form. Obejmuje ekstrakcję wartości AcroForm, odczyt i zapis XFDF, wiązanie danych oraz ekstrakcję danych XFA. Moduł konsumuje wartości NextPDF\Form\FormField wytwarzane przez czytnik formularzy Core i dodaje do nich serializację, parsowanie oraz wiązanie. Obsługa XFA jest zorientowana na dane: parser strukturyzuje pakiety template i datasets. Nie wykonuje skryptów obliczeniowych XFA ani nie renderuje dynamicznych układów XFA.

Dostępność i licencjonowanie

Ta funkcjonalność jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się wraz z kopertą licencyjną poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcjonalności. Porównaj edycje i uzyskaj licencję.

Nie istnieje flaga licencji dla pojedynczej funkcji. Jest to funkcjonalność edycji Pro.

Powierzchnia publicznego API

Symbol	Parametry	Domyślne zachowanie	Zwraca	Zgłasza lub kończy się błędem	Uwagi
`FormDataExtractor::extract`	`list<FormField> $fields`	Odczytuje nazwę i wartość każdego pola	`XfdfData`	—	Uwzględnia pola, których wartość jest pusta.
`FormDataExtractor::toArray`	`list<FormField> $fields`	Buduje mapę łańcuchów nazwa-wartość	`array<string, string>`	—	Późniejsza zduplikowana nazwa nadpisuje wcześniejszą.
`FormDataExtractor::toXfdf`	`list<FormField> $fields`, `?string $pdfHref = null`	Deleguje do `XfdfWriter::fromFields`	`string` (XFDF XML)	—	Wygodna ścieżka eksportu jednym wywołaniem.
`FormDataExtractor::extractNonEmpty`	`list<FormField> $fields`	Pomija pola, których wartość jest pustym łańcuchem	`XfdfData`	—	—
`FormDataExtractor::getEmptyFieldNames`	`list<FormField> $fields`	Wypisuje nazwy pól bez ustawionej wartości	`list<string>`	—	Dopełnienie `extractNonEmpty`.
`XfdfWriter::fromFields`	`list<FormField> $fields`, `?string $pdfHref = null`	Zbiera pary nazwa-wartość, deleguje do `fromArray`	`string` (XFDF XML)	—	—
`XfdfWriter::fromArray`	`array<string, string> $data`, `?string $pdfHref = null`	Opakowuje mapę w `XfdfData`, deleguje	`string` (XFDF XML)	—	—
`XfdfWriter::fromXfdfData`	`XfdfData $data`, `?string $pdfHref = null`	Serializuje do XFDF; nazwy w notacji z kropkami zagnieżdżają się jako hierarchiczne elementy `<field>`	`string` (XFDF XML)	—	Usuwa znaki sterujące niedozwolone w XML 1.0; zob. kontrakt zachowania.
`XfdfParser::parse`	`string $xfdfXml`	Ładuje XML w sposób odporny na XXE i spłaszcza pola do notacji z kropkami	`XfdfData`	`InvalidArgumentException`	Limit wejścia 10 MiB; akceptuje korzenie z przestrzenią nazw i bez niej.
`XfdfParser::parseFile`	`string $filePath`	Rozwiązuje ścieżkę, odczytuje plik, deleguje do `parse`	`XfdfData`	`InvalidArgumentException`	Brakujące, nie będące plikiem lub nieczytelne ścieżki powodują wyjątek.
`XfaParser::parse`	`string $pdfData`	Sprawdzenie markera, ekstrakcja XML, parsowanie pakietów	`XfaFormData`	`InvalidArgumentException`, `XfaParseException`	Brak markera `/XFA` zwraca pusty wynik, a nie błąd.
`XfaParser::hasXfa`	`string $pdfData`	Skanuje bajty w poszukiwaniu markera `/XFA`	`bool`	—	Skan markera bajtowego; dopasowuje każde wystąpienie tokena.
`XfaParser::extractXfaXml`	`string $pdfData`	Skan strumieni pod kątem markerów XFA, następnie bezpośrednie wyszukiwanie `<xdp:xdp>`	`string` (XFA XML lub `''`)	`RuntimeException` (zadeklarowany)	Skanuje najwyżej pierwsze 50 MiB danych wejściowych.
`XfaParser::parseXml`	`string $xml`	Wyodrębnia pakiety template i datasets, parsuje elementy `<field>`	`XfaFormData`	`XfaParseException`	Limit XML 10 MiB, egzekwowany przed załadowaniem DOM.
`FormDataBinder::bind`	`list<FormField> $fields`, `XfdfData $data`	Tworzy nowe instancje `FormField` z powiązanymi wartościami	`FormDataBindResult`	—	Oryginały nigdy nie są modyfikowane; pola wyboru normalizują się do `Yes`/`Off`.
`FormDataBinder::fromXfdf`	`list<FormField> $fields`, `string $xfdfXml`	Parsuje XFDF, następnie wiąże	`FormDataBindResult`	`InvalidArgumentException`	Tryby awarii są takie jak w `XfdfParser::parse`.
`FormDataBinder::fromArray`	`list<FormField> $fields`, `array<string, string> $data`	Opakowuje mapę w `XfdfData`, następnie wiąże	`FormDataBindResult`	—	—
`FormDataBindResult`	`isFullyBound`, `hasNoUnmatchedKeys`, `boundCount`, `fieldCount`; readonly `fields`, `boundFieldNames`, `unmatchedDataKeys`, `unboundFieldNames`	Niezmienne diagnostyki wiązania	zależnie od metody	—	`isFullyBound` wymaga zera niedopasowanych kluczy i zera niepowiązanych pól.
`XfdfData`	`hasField`, `getValue`, `count`, `isEmpty`, `getFieldNames`, `withField`, `withoutField`, `merge`; readonly `fields`	Niezmienny kontener nazwa-wartość	zależnie od metody	—	`with*` i `merge` zwracają nowe instancje; `merge` preferuje wartości argumentu.
`XfaFormData`	`getField`, `hasField`, `count`, `fieldNames`; readonly `fields`, `templateXml`, `datasetsXml`	Niezmienny wynik parsowania XFA	zależnie od metody	—	Przenosi surowy XML pakietów template i datasets do pełnej wymiany dwustronnej.
`XfaFormField`	readonly `name`, `type`, `value`, `required`, `caption`, `options`	Niezmienny rekord pojedynczego pola	—	—	`type` przyjmuje jedną z wartości: `text`, `numeric`, `date`, `choice`, `button`, `signature`.
`XfaPacket`	przypadki enum `Template`, `Datasets`, `Config`, `LocaleSet`, `ConnectionSet`, `Form`; `xmlNamespace()`	Wyliczenie pakietów oparte na łańcuchach	`string` z `xmlNamespace()`	—	Identyfikatory URI przestrzeni nazw są zgodne z 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

Wyjątki

NextPDF\Pro\Form\Exception\XfaParseException rozszerza RuntimeException — ładunek XFA nie może zostać sparsowany do XfaFormData. Dziedziczenie jest celowe: istniejące miejsca wywołań catch (RuntimeException $e) nadal działają.
SPL InvalidArgumentException — puste, zbyt duże, zniekształcone lub nie-XFDF dane wejściowe dla XfdfParser; puste dane PDF dla XfaParser::parse; nieczytelne ścieżki w XfdfParser::parseFile.

Kontrakt zachowania

Ekstrakcja AcroForm. FormDataExtractor przechodzi po przekazanej liście pól i odczytuje nazwę oraz wartość każdego pola. extract zwraca XfdfData; toArray zwraca zwykłą mapę łańcuchów nazwa-wartość. extractNonEmpty pomija pola, których wartość jest pustym łańcuchem; getEmptyFieldNames zwraca dopełniającą listę nazw. Ekstrakcja nigdy nie modyfikuje pól wejściowych.

Zapis XFDF. XfdfWriter produkuje dokument zgodny ze strukturą ISO 19444-1:2019. Wynik zaczyna się deklaracją XML XFDF oraz korzeniem xfdf w przestrzeni nazw Adobe XFDF (http://ns.adobe.com/xfdf/) z xml:space="preserve". Niepusty pdfHref emituje odniesienie <f href="..."/> z powrotem do źródłowego PDF. Nazwy pól w notacji z kropkami (na przykład address.city) zagnieżdżają się w hierarchiczne drzewo elementów <field>. Wartości i atrybuty escapują pięć metaznaków XML. Nazwy pól, wartości oraz pdfHref są dodatkowo normalizowane pod kątem poprawności składniowej: znaki sterujące C0, których zabrania XML 1.0, są usuwane, natomiast TAB, LF i CR są zachowywane. Ta normalizacja jest z założenia stratna, więc writer zawsze emituje poprawny składniowo, ponownie parsowalny XFDF, niezależnie od bajtów dostarczonych przez wywołującego.

Odczyt XFDF. XfdfParser akceptuje korzenie xfdf zarówno z przestrzenią nazw, jak i bez niej, oraz dopasowuje nazwę korzenia bez rozróżniania wielkości liter, ponieważ niektóre generatory emitują korzeń zapisany wielkimi literami. Hierarchiczne drzewa <field> spłaszczają się z powrotem do nazw w notacji z kropkami, dzięki czemu zapis i odczyt tworzą pełną wymianę dwustronną. Całe ładowanie XML wyłącza dostęp sieciowy i rozwiązywanie encji zewnętrznych. parseFile dodaje rozwiązywanie ścieżki i sprawdzanie czytelności przed tym samym parsowaniem.

Wiązanie danych. FormDataBinder::bind dopasowuje klucze danych do nazw pól. Ponieważ FormField jest niezmienny, wiązanie tworzy nowe instancje z zaktualizowanymi wartościami; oryginały nigdy nie są modyfikowane. Wynik raportuje trzy zbiory diagnostyczne: nazwy powiązanych pól, klucze danych bez pasującego pola oraz pola, które nie otrzymały danych. Wartości pól wyboru normalizują się do modelu stanu włączony/wyłączony z ISO 32000-2:2020, 12.7.5.2.3: yes, true, 1 i on (bez rozróżniania wielkości liter) mapują się na Yes; każda inna wartość mapuje się na Off.

Ekstrakcja danych XFA. XfaParser::parse przyjmuje surowe bajty PDF. Najpierw skanuje w poszukiwaniu markera /XFA; przy jego braku zwraca pusty XfaFormData. Ekstrakcja próbuje następnie dwóch strategii: skanu bloków stream…endstream pod kątem wskaźników XFA XML, a następnie bezpośredniego wyszukiwania dokumentu <xdp:xdp>. Pojedynczy fragment xdp:xdp jest zwracany bez zmian; wiele fragmentów jest łączonych w syntetyzowaną kopertę xdp:xdp. parseXml wyodrębnia pakiety template i datasets oraz parsuje każdy element <field> szablonu do XfaFormField: atrybut name jest wymagany, typ wynika z elementu podrzędnego UI pola, flaga required wynika z elementu validate z nullTest ustawionym na error, a opcje wyboru pochodzą z elementów podrzędnych items.

Obsługa XFA jest zorientowana na dane. Parser strukturyzuje pakiety template i datasets. Nie wykonuje skryptów obliczeniowych XFA, nie renderuje dynamicznych układów XFA ani nie realizuje pełnej wymiany dwustronnej każdego typu pakietu. Zwaliduj parser względem swojego konkretnego zestawu dokumentów, zanim zaczniesz na nim polegać.

Przypadki brzegowe i tryby awarii

XfdfParser::parse('') zgłasza InvalidArgumentException. Wejście powyżej 10 MiB zgłasza InvalidArgumentException z podaniem limitu.
Zniekształcony XML zgłasza InvalidArgumentException z zebranymi komunikatami libxml. Poprawny składniowo dokument, którego korzeniem nie jest xfdf, zgłasza wyjątek i podaje rzeczywisty element korzenia.
Dokument XFDF bez elementu <fields> parsuje się do pustego XfdfData; nie jest to błąd.
Elementy pól bez atrybutu name są pomijane zarówno w parsowaniu XFDF, jak i XFA. Pole XFDF bez elementu podrzędnego <value> nie wnosi żadnego wpisu.
XfaParser::parse('') zgłasza InvalidArgumentException. PDF bez markera /XFA lub taki, którego XFA XML nie da się zlokalizować, zwraca pusty XfaFormData zamiast zgłaszać wyjątek.
hasXfa to skan markera bajtowego: dopasowuje każdy token /XFA w pliku, w tym w nieużywanym obiekcie. Kolejny krok ekstrakcji decyduje, czy istnieje użyteczny XML.
Ekstrakcja XFA bada najwyżej pierwsze 50 MiB łańcucha bajtów PDF; treść poza tą granicą nie jest skanowana.
XFA XML powyżej 10 MiB zgłasza XfaParseException, zanim jakiekolwiek drzewo DOM zostanie zmaterializowane. Zniekształcony XFA XML zgłasza XfaParseException z komunikatami libxml.
Normalizacja pól wyboru nigdy nie przepuszcza nierozpoznanych wartości; wszystko poza akceptowanymi formami stanu włączonego mapuje się na Off.
Usuwanie znaków sterujących przez writer jest stratne: bajty C0 niedozwolone w XML 1.0 w nazwach, wartościach lub pdfHref są odrzucane, aby wynik pozostał poprawny składniowo. TAB, LF i CR zostają zachowane.
Całe parsowanie XML wyłącza rozwiązywanie encji zewnętrznych i dostęp sieciowy (odporne na XXE).
Ten moduł nie wykonuje żadnych operacji kryptograficznych; tryb FIPS nie zmienia jego zachowania.

Zgodność ze standardami

Zachowanie	Odniesienie	Status
Model formularza interaktywnego / słownika pól	ISO 32000-2:2020, 12.7	Zgodne (oparte na produkcie)
Normalizacja stanu włączony/wyłączony pola wyboru (`Yes`/`Off`)	ISO 32000-2:2020, 12.7.5.2.3	Zgodne; klauzula przytoczona w rekordzie cytowań tej strony
Struktura wymiany danych XFDF	ISO 19444-1:2019	Zgodne (oparte na produkcie)
Nazwy pakietów XFA i identyfikatory URI przestrzeni nazw	XFA Specification 3.3	Zgodne (oparte na produkcie)

Korpus RAG dostępny w czasie tworzenia tej strony nie obejmuje ISO 19444-1:2019, specyfikacji XFA ani W3C XML 1.0, więc te stwierdzenia o zgodności są oparte na produkcie — na adnotacjach źródłowych i testach — a nie przytaczane z klauzul. Stwierdzenia te opisują funkcjonalność względem przywoływanych dokumentów. NextPDF nie posiada żadnej certyfikacji zgodności, a obsługa danej klauzuli nie jest oświadczeniem o certyfikacji.

Uwagi deweloperskie

Każdy punkt wejścia z wyjątkiem XfaParser jest statyczny. XfaParser jest instancjonowalny i bezstanowy; jedną instancję można bezpiecznie używać ponownie w wielu dokumentach.
Zamierzona wymiana dwustronna wygląda tak: czytnik formularzy Core wytwarza wartości FormField; FormDataExtractor lub XfdfWriter je serializuje; XfdfParser odczytuje dane z powrotem; FormDataBinder stosuje je do listy pól. Nazwy hierarchiczne przetrwają wymianę dwustronną dzięki notacji z kropkami.
Użyj diagnostyk FormDataBindResult (isFullyBound, unmatchedDataKeys, unboundFieldNames), aby wykryć rozbieżność między plikiem danych XFDF a zmienionym szablonem PDF, zanim zaakceptujesz wypełnienie.
XfdfData to obiekt wartości: withField, withoutField i merge zwracają nowe instancje. Przy kolizjach kluczy merge preferuje wartości argumentu.
XfaFormData zachowuje surowy XML pakietów template i datasets (templateXml, datasetsXml), dzięki czemu można poddać dalszej obróbce pakiety, których model pól nie obejmuje.
Ten moduł sam nie parsuje słowników AcroForm z bajtów PDF; konsumuje pola wytworzone przez czytnik formularzy Core. Tylko XfaParser operuje na surowej treści PDF.

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne z zewnątrz oraz wspieraną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.