Form

Краткий обзор

NextPDF Pro читает и записывает данные интерактивных форм: значения полей AcroForm, файлы данных XFDF и данные, которые несут шаблоны XFA (XML Forms Architecture). Он дополняет модуль чтения форм Core с открытым исходным кодом привязкой данных, извлечением и сериализацией.

Доступность и лицензирование

Эта возможность поставляется в составе NextPDF Pro (nextpdf/pro) и активируется лицензионным конвертом уровня Pro. Развёртывание без этого права не загружает классы данной возможности. Сравнить редакции и получить лицензию.

Form входит в редакцию Pro. Отдельного флага лицензии для каждой возможности нет.

Установка

composer require nextpdf/pro:^3

Возможность Form требует действительной лицензии NextPDF Pro. См. Доступность и лицензирование.

Концептуальный обзор

Интерактивная форма PDF — иногда называемая AcroForm — хранит каждое поле в словаре поля, как определено в ISO 32000-2 §12.7. NextPDF Pro строится на модуле чтения форм Core, добавляя три возможности:

• Круговая обработка AcroForm. FormDataExtractor читает пары имя/значение поля из разобранных полей формы и формирует объект XfdfData или простую карту name → value. XfdfWriter выполняет обратное, генерируя документ XFDF.
• Чтение и запись XFDF. XFDF — это XML-формат обмена данными для значений форм, описанный в ISO 19444-1:2019. XfdfParser читает файл XFDF в структурированные данные; XfdfWriter сериализует значения полей в XFDF с необязательной ссылкой обратно на исходный PDF.
• Извлечение данных XFA. XfaParser находит пакеты XFA в документе, объединяет фрагменты XML и разбирает пакеты template и datasets в структурированные данные полей.

Область поддержки XFA

Поддержка XFA в NextPDF Pro ориентирована на данные, а не является полным движком отрисовки или сценариев XFA. Парсер извлекает и структурирует пакеты template и datasets, чтобы вы могли читать определения и значения полей. Он не выполняет сценарии вычислений форм XFA, не отрисовывает динамические макеты XFA и не выполняет круговую обработку каждого типа пакета XFA. Проверьте парсер на ваших конкретных документах, прежде чем полагаться на него для определённого набора форм XFA. Весь разбор XML отключает загрузку внешних сущностей (защита от XXE).

Почему это устроено именно так

Поддержка XFA намеренно ограничена данными, а не отрисовкой. ISO 32000-2 помечает запись XFA в словаре формы как устаревшую в PDF 2.0 (§12.7). Полный движок макета и сценариев XFA гнался бы за унаследованной поверхностью, которая большинству нагрузок больше не нужна. Вместо этого NextPDF Pro извлекает пакеты template и datasets, где хранятся долговечные данные полей, и отказывается от остального. Тот же подход определяет разбор с отключённым XXE и потолок сканирования, потому что ввод форм часто приходит от недоверенных сторон. Это сохраняет поверхность форм Pro тонким, предсказуемым расширением модели AcroForm из Core.

Справочный контекст проектирования: От заполняемой формы к замороженной записи: заполнение и сведение AcroForm.

Поверхность API

Класс	Назначение
FormDataExtractor	Извлекать значения полей AcroForm как XfdfData или массив.
XfdfParser	Разбирать документ XFDF в структурированные данные.
XfdfWriter	Сериализовать значения полей в XFDF, необязательная ссылка на PDF.
XfaParser	Извлекать и разбирать пакеты template и datasets XFA.
FormDataBinder	Привязывать карту данных обратно к полям формы.

Полный справочник на уровне методов находится в подробном справочнике Form.

Пример кода — быстрый старт

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

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

Пример кода — продакшн

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()]);
}

Граничные случаи и подводные камни

• XfaParser отклоняет ввод PDF больше своего потолка сканирования, а не читает неограниченные данные.
• Документ может нести как интерактивные, так и неинтерактивные формы; извлечение нацелено на словари конечных полей.
• XFDF выполняет круговую обработку плоских структур полей; глубоко вложенные иерархии полей могут потребовать явной обработки.

Производительность

Извлечение и сериализация линейны по числу полей формы. Стоимость разбора XFA растёт с размером встроенных пакетов XML.

Замечания по безопасности

Весь разбор XML отключает разрешение внешних сущностей для предотвращения XXE. Относитесь к вводу XFDF и XFA из недоверенных источников как к враждебному и проверяйте разобранный набор полей перед его привязкой обратно в документ.

Соответствие

Поведение	Ссылка	Статус
Модель интерактивной формы / словаря поля	ISO 32000-2 §12.7	Согласовано (пересказ)
Формат обмена данными XFDF	ISO 19444-1:2019	Согласовано

Эта таблица фиксирует спецификации, на которые ориентирован NextPDF Pro. Это не заявление о формальной сертификации.

Контракт поведения

• FormDataExtractor читает пары имя/значение из разобранных словарей конечных полей и возвращает объект XfdfData или простой массив name → value.
• XfdfParser разбирает документ XFDF в структурированные данные; XfdfWriter сериализует значения полей в XFDF с необязательной ссылкой обратно на исходный PDF.
• XfaParser находит пакеты XFA, объединяет фрагменты XML и разбирает пакеты template и datasets в структурированные данные полей. Он отклоняет ввод PDF больше своего потолка сканирования, а не читает неограниченные данные.
• Поддержка XFA ориентирована на данные: парсер извлекает и структурирует пакеты template и datasets. Он не выполняет сценарии вычислений форм XFA, не отрисовывает динамические макеты XFA и не выполняет круговую обработку каждого типа пакета XFA.
• Весь разбор XML отключает разрешение внешних сущностей (защита от XXE).

Примечание о границе Enterprise

Enterprise не меняет поведение Form. Enterprise добавляет комплаенс- и архивные возможности более высокого уровня, документированные отдельно; они не требуются для круговой обработки AcroForm, чтения/записи XFDF или извлечения данных XFA.

Резервный вариант Core / альтернатива

Модуль чтения форм NextPDF Core с открытым исходным кодом читает поля форм. Чтение/запись XFDF, извлечение данных XFA и привязка полей — это дополнения Pro. См. /modules/form/.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую публичную поверхность API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы тикетов вне области рассмотрения.

См. также

• Interop — версионированные DTO данных форм для внешних систем.
• Core Form module — модуль чтения форм с открытым исходным кодом.
• Form — Deep Reference — справочник на уровне методов для классов форм Pro.