Spłaszczanie pól formularza do statycznej zawartości strony

W skrócie

Ten przepis pokazuje, jak spłaszczyć interaktywny formularz AcroForm. NextPDF rysuje bieżącą wartość każdego pola w strumieniu zawartości strony jako zwykłą grafikę, a następnie usuwa słownik AcroForm. W efekcie powstaje formularz nieinteraktywny: statyczna reprezentacja pól, która wygląda tak samo w każdym środowisku, nawet w czytniku bez obsługi formularzy (ISO 32000-2 §12.7). Przepis tworzy formularz na podstawie examples/30-form-fields.php, a następnie wywołuje flattenForms().

Instalacja

composer require nextpdf/core:^3

Przegląd koncepcyjny

Spłaszczanie „drukuje” każdy widżet na jego stronie. Pola tekstowe stają się tekstem BT … Tj … ET. Pola wyboru i przyciski opcji stają się narysowanymi ścieżkami. Pola listy wyboru renderują wybrany element. Przyciski poleceń są renderowane jako statyczne pole przypominające przycisk. Odpowiada to opisanemu w specyfikacji modelowi statycznie zdefiniowanego wyglądu, gdy zawartość pola jest znana z wyprzedzeniem (ISO 32000-2 §12.7). Ponieważ NextPDF wbudowuje wartości w stronę, przestarzały mechanizm NeedAppearances nie jest potrzebny.

Profil ma wartość structural. Dokument zawiera wartość /ID w zwiastunie, którą końcowy przebieg normalizuje przed porównaniem dwóch uruchomień.

Powierzchnia API

NextPDF\Core\Concerns\HasFormFields::flattenForms(): static zamienia każde pole utworzone w dokumencie na statyczną zawartość strony i usuwa AcroForm. Jeśli nie ma żadnych pól, nie robi nic. Wewnętrznie deleguje pracę do NextPDF\Form\FormFlattener.

Zbuduj formularz za pomocą konstruktorów pól. Szczegółowe kroki opisuje Tworzenie i wstępne wypełnianie formularza PDF. Następnie wywołaj flattenForms() przed save().

Przykład kodu — szybki start

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Flattened Form');
$doc->addPage();

$doc->textField(name: 'full_name', x: 20, y: 30, w: 90, h: 8, default: 'Ada Lovelace');
$doc->checkBox(name: 'agree', x: 20, y: 45, size: 5, checked: true);

// Bake the field values into the page; the AcroForm is removed.
$doc->flattenForms();

$doc->save(__DIR__ . '/flattened.pdf');
echo "Wrote flattened.pdf (no interactive fields)\n";

Przykład kodu — wersja produkcyjna

Pełny przykład poniżej buduje formularz z wieloma sekcjami na podstawie examples/30-form-fields.php. Wstępnie wypełnia formularz, spłaszcza go i zapisuje do NEXTPDF_COOKBOOK_OUTPUT na potrzeby mechanizmu testowego.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Customer Registration — Flattened');
$doc->addPage();

$doc->setFont('helvetica', 'B', 20);
$doc->cell(0, 14, 'Customer Registration (read-only copy)', newLine: true);
$doc->ln(4);

$leftMargin = 15.0;
$fieldX     = 70.0;
$fieldW     = 120.0;
$fieldH     = 8.0;
$rowSpacing = 12.0;

$prefill = [
    'full_name' => 'Ada Lovelace',
    'email'     => '[email protected]',
    'phone'     => '+44 20 7946 0000',
    'company'   => 'Analytical Engines Ltd',
];

$y = 40.0;
$doc->setFont('helvetica', '', 10);
foreach ($prefill as $name => $value) {
    $doc->setXY($leftMargin, $y);
    $doc->cell(50, $fieldH, ucwords(str_replace('_', ' ', $name)) . ':');
    $doc->textField(name: $name, x: $fieldX, y: $y, w: $fieldW, h: $fieldH, default: $value);
    $y += $rowSpacing;
}

$y += 6;
$doc->setXY($leftMargin, $y);
$doc->cell(0, 7, 'Newsletter');
$doc->checkBox(name: 'newsletter', x: $leftMargin + 70, y: $y, size: 5, checked: true);

// Flatten: widgets become static page content; the AcroForm is dropped.
$doc->flattenForms();

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/registration-flattened.pdf');

echo "Wrote flattened registration form\n";

Oczekiwany wynik:

Wrote flattened registration form

Wynik zawiera te same wartości, ale bez pól interaktywnych. Czytnik bez obsługi formularzy renderuje go w ten sam sposób.

Przypadki brzegowe i pułapki

Spłaszczanie jest nieodwracalne. Po wywołaniu save() pola interaktywne znikają. Zachowaj niespłaszczone źródło, jeśli później możesz potrzebować edytować wartości.
Kolejność wywołań. Wywołaj flattenForms() po utworzeniu pól, a przed save(). Wywołanie flattenForms() przy braku pól jest bezpieczne i nie robi nic.
Pola podpisu nie są spłaszczane. Powierzchnia wizualna pola /Sig to wygląd wygenerowany z jego struktury Cryptographic Message Syntax (CMS) SignedData, a nie wartość możliwa do ponownego wyrenderowania. Ponowne zrasteryzowanie utworzyłoby statyczną grafikę „ducha”, która nie odpowiadałaby już żadnemu weryfikowalnemu podpisowi. Z tego powodu mechanizm spłaszczania celowo pomija pola podpisu. Spłaszcz formularz przed podpisaniem, nigdy po.
Interpretacja logiczna pola wyboru. Pole wyboru renderuje znacznik wyboru, gdy jego wartość to Yes/On/1/true. Przy pustej wartości lub wartości Off renderowane jest samo pole.
Czcionka spłaszczonego tekstu. Spłaszczony tekst używa bieżącej czcionki. Jeśli czcionka nie została ustawiona, używana jest awaryjnie Helvetica. Jeśli wartości pól są w języku chińskim, japońskim lub koreańskim (CJK) albo mają używać czcionek niestandardowych, ustaw żądaną czcionkę przed flattenForms().

Wydajność

Spłaszczanie skaluje się liniowo wraz z liczbą pól. Dla każdego pola NextPDF dodaje ograniczony blok zawartości, a następnie usuwa obiekt AcroForm. Typowe formularze mieszczą się z dużym zapasem w budżecie 1500 ms / 64 MB.

Uwagi dotyczące bezpieczeństwa

Spłaszczanie sprawia, że wartości pól nie można edytować w zwykłych czytnikach. To zmiana prezentacji, a nie kontrola dostępu. Wartości pozostają widoczne w zawartości strony, a dowolne narzędzie tekstowe może je wyodrębnić. Nie traktuj spłaszczania jako redakcji ani jako ochrony wartości wrażliwych. W celu zapewnienia poufności użyj funkcji Szyfrowanie z uprawnieniami. Przeczytaj też znajdujące się tam zastrzeżenie o współpracy czytnika, ponieważ bity uprawnień również nie egzekwują ograniczeń odczytu. Nigdy nie spłaszczaj podpisanego dokumentu. Najpierw spłaszcz, a potem podpisz.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula
Spłaszczony formularz to nieinteraktywna (statyczna) reprezentacja pól.	ISO 32000-2	§12.7
Wygląd pola jest zdefiniowany statycznie, gdy jego zawartość jest znana z wyprzedzeniem.	ISO 32000-2	§12.7
Wbudowane wyglądy sprawiają, że przestarzała flaga `NeedAppearances` jest zbędna.	ISO 32000-2	§12.7

NextPDF wytwarza statyczną strukturę opisaną w cytowanych klauzulach. Nie rości sobie pełnej zgodności z ISO 32000-2.