Formularz

W skrócie

NextPDF Pro odczytuje i zapisuje dane formularzy interaktywnych: wartości pól AcroForm, pliki danych XFDF oraz dane niesione przez szablony XFA (XML Forms Architecture). Uzupełnia otwartoźródłowy czytnik formularzy z Core o wiązanie danych, ekstrakcję i serializację.

Dostępność i licencjonowanie

Ta możliwość 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 możliwości. Porównaj edycje i uzyskaj licencję.

Form jest częścią edycji Pro. Nie ma osobnej flagi licencyjnej dla poszczególnych funkcji.

Instalacja

composer require nextpdf/pro:^3

Możliwość Form wymaga ważnej licencji NextPDF Pro. Zobacz Dostępność i licencjonowanie.

Przegląd koncepcyjny

Formularz interaktywny PDF — czasem nazywany AcroForm — przechowuje każde pole w słowniku pola, zgodnie z definicją w ISO 32000-2 §12.7. NextPDF Pro opiera się na czytniku formularzy z Core, aby dodać trzy możliwości:

• Round-trip AcroForm. FormDataExtractor odczytuje pary nazwa/wartość pól ze sparsowanych pól formularza i wytwarza obiekt XfdfData lub zwykłą mapę name → value. XfdfWriter wykonuje operację odwrotną, generując dokument XFDF.
• Odczyt i zapis XFDF. XFDF to format wymiany danych XML dla wartości formularza opisany przez ISO 19444-1:2019. XfdfParser odczytuje plik XFDF do danych strukturalnych; XfdfWriter serializuje wartości pól do XFDF, z opcjonalnym odniesieniem z powrotem do źródłowego pliku PDF.
• Ekstrakcja danych XFA. XfaParser lokalizuje pakiety XFA w dokumencie, łączy fragmenty XML i parsuje pakiety template oraz datasets do strukturalnych danych pól.

Zakres obsługi XFA

Obsługa XFA w NextPDF Pro jest zorientowana na dane, a nie jest pełnym silnikiem renderowania ani skryptowania XFA. Parser wyodrębnia i strukturyzuje pakiety template oraz datasets, abyś mógł odczytać definicje i wartości pól. Nie wykonuje skryptów obliczeniowych formularzy XFA, nie renderuje dynamicznych układów XFA ani nie wykonuje round-tripu każdego typu pakietu XFA. Przetestuj parser względem swoich konkretnych dokumentów, zanim zaczniesz na nim polegać dla danego zestawu formularzy XFA. Całe parsowanie XML wyłącza ładowanie encji zewnętrznych (bezpieczne wobec XXE).

Dlaczego działa to w ten sposób

Obsługa XFA jest celowo zawężona do danych, a nie do renderowania. ISO 32000-2 oznacza wpis XFA w słowniku formularza jako przestarzały w PDF 2.0 (§12.7). Pełny silnik układu i skryptowania XFA gonił by za przestarzałą powierzchnią, której większość obciążeń już nie potrzebuje. Zamiast tego NextPDF Pro wyodrębnia pakiety template oraz datasets, gdzie mieszkają trwałe dane pól, a resztę odrzuca. Ta sama postawa napędza parsowanie z wyłączonym XXE oraz pułap skanowania, ponieważ wejście formularza często przychodzi od niezaufanych stron. Dzięki temu powierzchnia formularza w Pro pozostaje cienkim, przewidywalnym rozszerzeniem modelu AcroForm z Core.

Tło projektowe: Od wypełnialnego formularza do zamrożonego rekordu: wypełnianie i spłaszczanie AcroForm.

Powierzchnia API

Klasa	Odpowiedzialność
FormDataExtractor	Wyodrębnij wartości pól AcroForm jako XfdfData lub tablicę.
XfdfParser	Sparsuj dokument XFDF do danych strukturalnych.
XfdfWriter	Serializuj wartości pól do XFDF, opcjonalne odniesienie do PDF.
XfaParser	Wyodrębnij i sparsuj pakiety template oraz datasets XFA.
FormDataBinder	Powiąż mapę danych z powrotem z polami formularza.

Pełna dokumentacja na poziomie metod znajduje się w pełnej dokumentacji Form.

Przykład kodu — Szybki start

use NextPDF\Pro\Form\FormDataExtractor;
use NextPDF\Pro\Form\XfdfWriter;

$values = FormDataExtractor::toArray($fields);
$xfdf   = XfdfWriter::fromFields($fields, 'invoice.pdf');

Przykład kodu — Produkcja

use NextPDF\Pro\Form\XfaParser;
use NextPDF\Pro\Form\Exception\XfaParseException;

try {
    $formData = (new XfaParser())->parse($pdfBytes);
    $logger->info('xfa.parsed', ['fields' => count($formData->fields)]);
} catch (XfaParseException $e) {
    $logger->warning('xfa.parse_failed', ['reason' => $e->getMessage()]);
}

Przypadki brzegowe i pułapki

• XfaParser odrzuca wejście PDF większe niż jego pułap skanowania, zamiast odczytywać nieograniczone dane.
• Dokument może nieść zarówno formularze interaktywne, jak i nieinteraktywne; ekstrakcja celuje w terminalne słowniki pól.
• XFDF wykonuje round-trip płaskich struktur pól; głęboko zagnieżdżone hierarchie pól mogą wymagać jawnej obsługi.

Wydajność

Ekstrakcja i serializacja są liniowe względem liczby pól formularza. Koszt parsowania XFA skaluje się z rozmiarem osadzonych pakietów XML.

Uwagi dotyczące bezpieczeństwa

Całe parsowanie XML wyłącza rozstrzyganie encji zewnętrznych, aby zapobiec XXE. Traktuj wejście XFDF i XFA ze źródeł niezaufanych jako wrogie i waliduj sparsowany zestaw pól przed powiązaniem go z powrotem z dokumentem.

Konformancja

Zachowanie	Odniesienie	Status
Model formularza interaktywnego / słownika pola	ISO 32000-2 §12.7	Aligned (paraphrased)
Format wymiany danych XFDF	ISO 19444-1:2019	Aligned

Ta tabela zapisuje specyfikacje, względem których zbudowano NextPDF Pro. Nie jest oświadczeniem o formalnej certyfikacji.

Kontrakt zachowania

• FormDataExtractor odczytuje pary nazwa/wartość ze sparsowanych terminalnych słowników pól i zwraca obiekt XfdfData lub zwykłą tablicę name → value.
• XfdfParser parsuje dokument XFDF do danych strukturalnych; XfdfWriter serializuje wartości pól do XFDF z opcjonalnym odniesieniem z powrotem do źródłowego pliku PDF.
• XfaParser lokalizuje pakiety XFA, łączy fragmenty XML i parsuje pakiety template oraz datasets do strukturalnych danych pól. Odrzuca wejście PDF większe niż jego pułap skanowania, zamiast odczytywać nieograniczone dane.
• Obsługa XFA jest zorientowana na dane: parser wyodrębnia i strukturyzuje pakiety template oraz datasets. Nie wykonuje skryptów obliczeniowych formularzy XFA, nie renderuje dynamicznych układów XFA ani nie wykonuje round-tripu każdego typu pakietu XFA.
• Całe parsowanie XML wyłącza rozstrzyganie encji zewnętrznych (bezpieczne wobec XXE).

Nota o granicy Enterprise

Enterprise nie zmienia zachowania Form. Enterprise dodaje funkcje zgodności i archiwalne wyższego poziomu udokumentowane osobno; nie są one wymagane do round-tripu AcroForm, odczytu/zapisu XFDF ani ekstrakcji danych XFA.

Rozwiązanie awaryjne / alternatywa w Core

Otwartoźródłowy czytnik formularzy NextPDF Core odczytuje pola formularza. Odczyt/zapis XFDF, ekstrakcja danych XFA oraz wiązanie pól to dodatki Pro. Zobacz /modules/form/.

Granica publikacji

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

Zobacz też

• Interop — wersjonowane DTO danych formularza dla systemów zewnętrznych.
• Core Form module — otwartoźródłowy czytnik formularzy.
• Form — Deep Reference — dokumentacja na poziomie metod dla klas formularza Pro.