PDF フォームを作成し、事前入力する

概要

AcroForm は、PDF 内のインタラクティブなフォームです。このレシピでは AcroForm を作成し、そのフィールドに初期値を事前入力します。Core の HasFormFields トレイトは、フォームを作成するための API です。各フィールドを作成すると同時に、同じ呼び出しで値を指定します。テキストフィールドには default 引数を、選択フィールドには selected を、チェックボックスには checked を使用します。これにより、PDF を開いた時点でフィールドにはすでに値が入力されており、準拠するリーダーでは編集可能な状態が保たれます。ファイルを開いたユーザーは、引き続きそれらの値を変更できます。このレシピは examples/30-form-fields.php に従っています。

スコープの境界。 Core はドキュメントを構築する過程でフォームフィールドを作成し、値を入力します。サードパーティの PDF にすでに存在するフォームを読み取り、そこに値マップをマージすることはありません。ここでの「入力」とは、値を伴ってフォームを作成することを意味し、 外部の PDF を読み込んで入力することではありません。外部フォームのラウンドトリップは、 Premium およびサーバーの機能であり、Core の公開 API ではありません。

インストール

composer require nextpdf/core:^3

概念の概要

AcroForm フィールドは、現在の値をフィールド辞書の V エントリーに保持します（ISO 32000-2 §12.7）。フィールドは、オプションのデフォルト値を DV に保持することもでき、フォームのリセットアクションが実行されると、この値に戻ります。NextPDF は、各フィールドコンストラクターに渡した値に基づいて V を設定します。テキストのレンダリングには、デフォルトの外観文字列（DA）を使用します。

このプロファイルが structural であるのは、ドキュメントがトレーラーの /ID 配列を保持するためです。ポストパスは、比較の前にその不安定な識別子を正規化します。

API サーフェス

NextPDF\Core\Concerns\HasFormFields（Document にミックスイン）：

textField(string $name, float $x, float $y, float $w, float $h, string $default = '', array $options = []): static
checkBox(string $name, float $x, float $y, float $size, bool $checked = false): static
radioButton(string $name, float $x, float $y, float $size, string $value, string $group): static
comboBox(string $name, float $x, float $y, float $w, float $h, array $items, string $selected = ''): static
listBox(string $name, float $x, float $y, float $w, float $h, array $items, string $selected = ''): static
button(string $name, float $x, float $y, float $w, float $h, string $caption, string $action = ''): static

これらの default、checked、selected 引数が、事前入力される値を保持します。

コードサンプル — クイックスタート

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

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

// Text field pre-filled with a value (sets the field dictionary /V entry).
$doc->textField(name: 'full_name', x: 20, y: 30, w: 90, h: 8, default: 'Ada Lovelace');

// Choice field pre-selected.
$doc->comboBox(
    name: 'country',
    x: 20, y: 45, w: 90, h: 8,
    items: ['United Kingdom', 'Taiwan', 'Japan'],
    selected: 'Taiwan',
);

// Checkbox pre-checked.
$doc->checkBox(name: 'newsletter', x: 20, y: 60, size: 5, checked: true);

$doc->save(__DIR__ . '/prefilled-form.pdf');
echo "Wrote prefilled-form.pdf\n";

コードサンプル — 本番

以下の完全な例は、複数のセクションを持つ登録フォームである examples/30-form-fields.php を再現したものです。ハーネス向けに NEXTPDF_COOKBOOK_OUTPUT へ書き込みます。

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

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

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

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

// --- Personal information, pre-filled ---
$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,
        options: ['maxLen' => 80],
    );
    $y += $rowSpacing;
}

// --- Choice field, pre-selected ---
$y += 6;
$doc->setXY($leftMargin, $y);
$doc->cell(50, $fieldH, 'Country:');
$doc->comboBox(
    name: 'country',
    x: $fieldX,
    y: $y,
    w: $fieldW,
    h: $fieldH,
    items: ['United States', 'United Kingdom', 'Germany', 'Japan', 'Taiwan'],
    selected: 'United Kingdom',
);

// --- Checkboxes, pre-set ---
$y += $rowSpacing + 6;
$doc->setXY($leftMargin, $y);
$doc->cell(0, 7, 'Subscribe to newsletter');
$doc->checkBox(name: 'newsletter', x: $leftMargin + 70, y: $y, size: 5, checked: true);

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

echo "Wrote pre-filled registration form\n";

想定される出力：

Wrote pre-filled registration form

PDF を開くと、すべてのフィールドにはすでに値が入力されており、そのまま編集できます。

エッジケースと落とし穴

フィールド名は一意である必要があります。 同じ名前を共有する 2 つのフィールドは、準拠するリーダーでは値を共有する 1 つの論理フィールドになります。これはリンクされたフィールドでは望ましい挙動ですが、それ以外の場合は予期しない結果になります。
ラジオグループのセマンティクス。 radioButton() は、各オプションを group に関連付けます。選択されるオプションは、value がグループの値と一致するものです。グループごとに、一度にオンになるオプションは 1 つだけです。
maxLen はヒントです。 maxLen オプションは、準拠するリーダーで入力長を制限します。事前入力され、保存される値を制限するものではありません。
API では座標は左上が基準です。 トレイトが PDF の左下原点への変換を行うため、例で示すように左上の座標を渡してください。
外部 PDF への入力はできません。 既存のサードパーティフォームを読み込んで値マップを適用する Core のメソッドはありません。上記のスコープの境界を参照してください。

パフォーマンス

フォームの作成は、フィールド数に対して線形にスケールします。各フィールドは、1 つのウィジェット注釈と 1 つの外観を追加します。数百のフィールドであれば、1500 ms / 64 MB の予算に十分収まります。

セキュリティに関する注意事項

事前入力された値は、そのままフィールド辞書に書き込まれます。信頼できない入力から得た値は、配布するドキュメントに配置する前にエスケープまたは検証してください。事前入力されたフォームは保護されていません。PDF を開ける人は誰でも値を読み取り、変更できます。フォームの内容が機密である場合は、このレシピを権限付き暗号化と組み合わせ、そこに記載されているリーダー協調に関する注意点に留意してください。

準拠

記述	仕様	箇条
フィールドの現在の値は、フィールド辞書の `V` エントリーに保存されます。	ISO 32000-2	§12.7
デフォルト値は `DV` エントリーに保存され、フォームのリセット時に復元されます。	ISO 32000-2	§12.7
フィールドテキストの書式設定には、デフォルトの外観文字列 `DA` を使用します。	ISO 32000-2	§12.7

NextPDF は、引用した箇条で説明されている AcroForm 構造を出力します。完全な ISO 32000-2 準拠を主張するものではありません。