Achate campos de formulário em conteúdo estático da página

Visão geral

Use esta receita para achatar um AcroForm interativo. O NextPDF desenha o valor atual de cada campo no stream de conteúdo da página como gráficos comuns e, em seguida, remove o dicionário AcroForm. O resultado é um formulário não interativo: uma representação estática dos campos, com a mesma aparência em qualquer ambiente, mesmo em um leitor sem suporte a formulários (ISO 32000-2 §12.7). Esta receita constrói o formulário a partir de examples/30-form-fields.php e, em seguida, chama flattenForms().

Instalação

composer require nextpdf/core:^3

Visão conceitual

O achatamento “imprime” cada widget na respectiva página. Os campos de texto tornam-se texto BT … Tj … ET. As caixas de seleção e os botões de opção tornam-se traçados desenhados. Os campos de escolha renderizam o item selecionado. Os botões de ação são renderizados como uma caixa estática semelhante a um botão. Esse comportamento corresponde ao modelo da especificação para uma aparência definida estaticamente quando o conteúdo do campo é conhecido com antecedência (ISO 32000-2 §12.7). Como o NextPDF incorpora os valores na página, o mecanismo NeedAppearances, que está obsoleto, não é necessário.

O perfil é structural. O documento carrega um trailer /ID, que o pós-processamento normaliza antes da comparação entre duas execuções.

Superfície da API

NextPDF\Core\Concerns\HasFormFields::flattenForms(): static achata todos os campos criados no documento em conteúdo estático da página e remove o AcroForm. Quando não há campos, ele não faz nada. Internamente, ele delega o trabalho para NextPDF\Form\FormFlattener.

Construa o formulário com os construtores de campos. Para ver o passo a passo detalhado, consulte Construa e preencha previamente um formulário PDF. Em seguida, chame flattenForms() antes de save().

Exemplo de código — Início rápido

<?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";

Exemplo de código — Produção

O exemplo completo abaixo constrói um formulário com várias seções a partir de examples/30-form-fields.php. Ele preenche previamente o formulário, achata-o e grava em NEXTPDF_COOKBOOK_OUTPUT para o harness.

<?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";

Saída esperada:

Wrote flattened registration form

A saída mostra os mesmos valores, sem campos interativos. Um leitor sem suporte a formulários renderiza o documento da mesma maneira.

Casos extremos e pegadinhas

O achatamento é irreversível. Depois que você chama save(), os campos interativos deixam de existir. Mantenha a origem não achatada se precisar editar os valores mais tarde.
Ordem de chamada. Execute flattenForms() depois de criar os campos e antes de save(). Chamá-lo quando não há campos não faz nada, o que é seguro.
Os campos de assinatura não são achatados. A superfície visual de um campo /Sig é a aparência produzida a partir do seu Cryptographic Message Syntax (CMS) SignedData, não um valor que possa ser renderizado novamente. Rasterizá-la novamente criaria um gráfico “fantasma” estático que não corresponderia mais a nenhuma assinatura verificável. Por esse motivo, o achatador ignora intencionalmente os campos de assinatura. Achate o formulário antes de assinar, nunca depois.
Interpretação da caixa de seleção. Uma caixa de seleção renderiza a marca de seleção quando o valor é Yes/On/1/true. Um valor vazio ou Off renderiza apenas a caixa.
Fonte do texto achatado. O texto achatado usa a fonte atual. Sem nenhuma fonte definida, ele recorre à Helvetica. Para valores de campo em chinês, japonês e coreano (CJK) ou com fontes personalizadas, defina a fonte desejada antes de flattenForms().

Desempenho

O achatamento escala linearmente com o número de campos. Para cada campo, o NextPDF acrescenta um bloco de conteúdo limitado e, em seguida, remove o objeto AcroForm. Formulários típicos ficam confortavelmente dentro do orçamento de 1500 ms / 64 MB.

Notas de segurança

O achatamento torna os valores dos campos não editáveis em leitores normais. Essa é uma mudança de apresentação, não um controle de acesso. Os valores permanecem visíveis no conteúdo da página, e qualquer ferramenta de texto pode extraí-los. Não trate o achatamento como remoção segura de conteúdo nem como proteção de valores sensíveis. Para confidencialidade, use Criptografe com permissões. Leia também a ressalva sobre a cooperação do leitor nessa página, porque os bits de permissão também não impõem restrições de leitura. Nunca achate um documento assinado. Achate primeiro, depois assine.

Conformidade

Declaração	Especificação	Cláusula
Um formulário achatado é uma representação não interativa (estática) dos campos.	ISO 32000-2	§12.7
A aparência do campo é definida estaticamente quando o seu conteúdo é conhecido com antecedência.	ISO 32000-2	§12.7
As aparências incorporadas tornam desnecessário o sinalizador `NeedAppearances`, que está obsoleto.	ISO 32000-2	§12.7

O NextPDF produz a estrutura estática descrita pelas cláusulas citadas. Ele não reivindica conformidade total com a ISO 32000-2.