Formularze: interaktywne pola AcroForm i spłaszczanie

W skrócie

Moduł Form tworzy interaktywne formularze w dokumentach w formacie Portable Document Format (PDF). Buduje pola tekstowe, pola wyboru, przyciski radiowe, pola listy (list/combo), przyciski oraz pola podpisu, porządkuje je w hierarchii parent/child, zapisuje jako obiekty PDF ze strumieniami wyglądu i może spłaszczyć formularz do statycznej zawartości strony.

Instalacja

composer require nextpdf/core:^3

Przegląd koncepcyjny

Interaktywny formularz PDF to AcroForm: hierarchia pól na poziomie dokumentu, w której pola terminalne są powiązane z adnotacjami widżetów na stronach. ISO 32000-2 §12.7 definiuje ten formularz, jego słowniki pól, korzeń AcroForm oraz hierarchię pól. Moduł koduje te struktury na potrzeby silnika.

FormFieldManager to główna powierzchnia API. Udostępnia kreatory textField(), checkBox(), radioButton(), button() oraz signatureField(), rejestruje pola i serializuje je za pomocą writeFields(). Dla każdego widżetu emituje jeden strumień wyglądu Form XObject (/Subtype /Form, /BBox), zgodnie z wymaganiami §8.10. FormField to obiekt wartości reprezentujący pole. FormFieldDictionaryBuilder przekształca pole w słownik PDF oraz stosuje wpisy właściwe dla danego typu i bity flag dla pól tekstowych, pól wyboru, pól listy i przycisków. Menedżer oraz FormField mają adnotację @since 1.0.0. Kreator słownika ma adnotację @since 1.1.0.

FormFieldHierarchy modeluje drzewo pól w relacji parent/child z addChild(), getRootFieldNames(), getChildren(), getParent() oraz wizytatorem walkDepthFirst(). W pełni kwalifikowana nazwa pola jest ścieżką w tej hierarchii rozdzieloną kropkami, zgodną z modelem pól zagnieżdżonych z §12.7.

FormFlattener renderuje formularz jako statyczną zawartość strony. flatten() zwraca FlattenResult, co pozwala zamrozić wypełniony formularz do archiwizacji. FieldMDP i FieldMdpAction modelują transformację blokady pól. Podpisany dokument może zablokować nazwany zestaw pól przed dalszą modyfikacją. FieldMdpAction określa zakres blokady, a requiresFieldList() wskazuje, kiedy jawna lista pól jest obowiązkowa. FieldMDP ma adnotację @since 2.0.0.

Powierzchnia API

Klasa	Kluczowe składowe	Rola
FormFieldManager	textField(), checkBox(), radioButton(), button(), signatureField(), addChildField(), getHierarchy(), writeFields()	Kreator pól + serializator (@since 1.0.0)
FormField	obiekt wartości pola	Jedno pole AcroForm (@since 1.0.0)
FormFieldDictionaryBuilder	buildFieldDictionary(), applyTextFieldOptions(), applyCheckBoxOptions(), applyChoiceFieldOptions(), applyButtonOptions()	Słownik PDF budowany z pola (@since 1.1.0)
FormFieldHierarchy	addChild(), getRootFieldNames(), getChildren(), getParent(), walkDepthFirst()	Drzewo pól w relacji parent/child (@since 2.0.0)
FormFlattener	flatten(array $fields, array $pages): FlattenResult	Spłaszcza formularz do statycznej zawartości (@since 1.0.0)
FieldMDP	toTransformParams()	Transformacja blokady pól (FieldMDP) (@since 2.0.0)
FieldMdpAction (typ wyliczeniowy)	requiresFieldList()	Zakres blokady pól (@since 2.0.0)

Uruchom composer docs:generate-api-php -- --module=Form, aby wygenerować pełną tabelę PHPDoc.

Przykład kodu — szybki start

Źródło: 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.

Przykład kodu — produkcja

Zbuduj zestaw pól dla podpisywanego dokumentu, a następnie zablokuj podpisywane pola za pomocą 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.

Przypadki brzegowe i pułapki

• Nazwa pola jest w pełni kwalifikowaną ścieżką w FormFieldHierarchy, rozdzieloną kropkami. W przeglądarce PDF dwa pola terminalne o tej samej w pełni kwalifikowanej nazwie są tym samym polem logicznym. Zadbaj o unikalność.
• FieldMdpAction::requiresFieldList() informuje, kiedy lista pól jest obowiązkowa. Akcja Include/Exclude bez wymaganej listy tworzy niepoprawną blokadę; sprawdź flagę.
• FormFlattener::flatten() celowo usuwa interaktywność. Efektem jest statyczna zawartość. Zachowaj interaktywne źródło, jeśli będzie potrzebne później.
• Strumienie wyglądu są emitowane dla każdego widżetu. Pole bez wyglądu może być renderowane niespójnie w różnych przeglądarkach; pozwól menedżerowi wygenerować wygląd, zamiast go pomijać.
• signatureField() tworzy wyłącznie pole zastępcze. Rzeczywisty podpis tworzy warstwa Security/podpisywania; ten moduł go nie tworzy.

Wydajność

Złożoność tworzenia i serializacji pól wynosi O(n) względem liczby pól; dodatkowo powstaje jeden strumień wyglądu Form XObject na każdy widżet. Koszt spłaszczania skaluje się z renderowaną zawartością, a nie z liczbą pól. Domyślne obciążenie referencyjne mieści się w budżecie 1500 ms czasu zegarowego / 64 MB szczytowego zużycia pamięci. Profil odtwarzalności to structural: numery obiektów oraz wpis /ID w zwiastunie różnią się między uruchomieniami. Dwa dokumenty z tym samym formularzem są równoważne strukturalnie, ale nie identyczne bajt po bajcie.

Uwagi dotyczące bezpieczeństwa

Wartości pól formularza są danymi wprowadzonymi przez użytkownika. Moduł wykonuje escaping wartości łańcuchowych na potrzeby serializacji PDF za pomocą PdfStringEscaper, dzięki czemu wartość pola nie może opuścić własnego łańcucha PDF ani wstrzyknąć struktury. Gdy formularz jest zaszyfrowany, szyfrowanie AES-256 dokumentu obejmuje zawartość pól. FieldMDP to mechanizm zabezpieczeń: blokuje nazwane pola przed modyfikacją po podpisaniu. Blokada pól niezgodna z podpisanym zestawem pól osłabia ten mechanizm; ustaw zakres blokady rozważnie. Traktuj każdą wartość wyodrębnioną z wypełnionego formularza jako niezaufane dane wejściowe. Zobacz model bezpieczeństwa silnika w /modules/core/security/.

Zgodność

Struktury formularza emitowane przez ten moduł są zgodne z modelem formularza interaktywnego z ISO 32000-2 §12.7: korzeń AcroForm, słowniki pól oraz hierarchia pól dokumentu. Wyglądy poszczególnych widżetów są emitowane jako obiekty Form XObject zgodnie z §8.10, co udokumentowano w kodzie w src/Form/. Testy w tests/Unit/Form/ sprawdzają te fakty implementacyjne. Same w sobie nie stanowią deklaracji kompleksowej zgodności z PDF 2.0. Zgodność całego dokumentu jest weryfikowana przez wyrocznię i pakiety wzorcowe w /modules/core/conformance/.

Zobacz też

• Moduł nawigacji — adnotacje widżetów powiązane z polami.
• Moduł bezpieczeństwa — model zaufania dla podpisywania i FieldMDP.
• Moduł dostępności — tagowanie pól formularza dla PDF/UA.
• Przegląd zgodności