PDF 양식 만들기 및 사전 채우기

한눈에 보기

AcroForm은 PDF 내부의 대화형 양식입니다. 이 레시피에서는 양식을 하나 만들고 초기값으로 필드를 미리 채웁니다. Core HasFormFields 트레이트는 양식 작성 API입니다. 각 필드를 만들 때 같은 호출에서 해당 값을 함께 제공합니다. 텍스트 필드에는 default 인수를, 선택 필드에는 selected를, 확인란에는 checked를 사용하십시오. 그러면 PDF는 필드가 이미 채워진 상태로 열리며, 규격을 준수하는 리더에서 계속 편집할 수 있습니다. 파일을 여는 사람은 누구나 값을 계속 변경할 수 있습니다. 이 레시피는 examples/30-form-fields.php를 따릅니다.

범위 경계. Core는 문서를 빌드하는 동안 양식 필드를 만들고 채웁니다. 타사 PDF에 이미 존재하는 양식을 읽어 들여 값 맵을 병합하지는 않습니다. 여기서 “채우기”는 값으로 양식을 작성한다는 의미이며, 외부 PDF를 로드하여 채운다는 의미가 아닙니다. 외부 양식의 왕복 처리는 Premium 및 server 기능이며, 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를 열면 모든 필드가 이미 채워져 있고, 그대로 편집할 수 있습니다.

엣지 케이스 및 유의 사항

• 필드 이름은 고유해야 합니다. 같은 이름을 가진 두 필드는 규격을 준수하는 리더에서 값을 공유하는 하나의 논리적 필드가 됩니다. 연결된 필드라면 의도한 동작이지만, 그렇지 않다면 예상치 못한 결과입니다.
• 라디오 그룹의 의미. radioButton()는 각 옵션을 group에 연결합니다. 선택된 옵션은 value가 그룹의 값과 일치하는 옵션입니다. 한 번에 그룹당 하나의 옵션만 켜집니다.
• maxLen은 힌트입니다. maxLen 옵션은 규격을 준수하는 리더에서 입력 길이를 제한합니다. 미리 채워 저장하는 값에는 제한을 적용하지 않습니다.
• API에서 좌표는 좌측 상단 기준입니다. 트레이트가 PDF의 좌측 하단 원점으로 자동 변환해 주므로, 예제에서 보듯이 좌측 상단 좌표를 전달하십시오.
• 외부 PDF 채우기는 없습니다. 기존 타사 양식을 로드하여 값 맵을 적용하는 Core 메서드는 없습니다. 위의 범위 경계를 참고하십시오.

성능

양식 작성 비용은 필드 수에 비례해 선형적으로 늘어납니다. 각 필드는 위젯 주석 하나와 모양 하나를 추가합니다. 필드가 수백 개여도 1500 ms / 64 MB 예산 내에 충분히 머뭅니다.

보안 참고 사항

미리 채운 값은 필드 딕셔너리에 그대로 기록됩니다. 신뢰할 수 없는 입력에서 가져온 값은 배포할 문서에 넣기 전에 이스케이프하거나 검증하십시오. 미리 채운 양식은 보호되지 않습니다. PDF를 열 수 있는 사람은 누구나 값을 읽고 변경할 수 있습니다. 양식 콘텐츠가 민감한 경우 이 레시피를 권한으로 암호화와 결합하고, 해당 문서에 명시된 리더 협력 의존성 관련 주의 사항에 유의하십시오.

규격 준수

설명	규격	조항	참조 ID(reference_id)
필드의 현재 값은 필드 딕셔너리 V 항목에 저장됩니다.	ISO 32000-2	§12.7
기본값은 DV 항목에 저장되며 양식 재설정 시 복원됩니다.	ISO 32000-2	§12.7
필드 텍스트 서식은 기본 모양 문자열 DA를 사용합니다.	ISO 32000-2	§12.7

NextPDF 는 인용된 조항에 설명된 AcroForm 구조를 생성합니다. 완전한 ISO 32000-2 준수를 주장하지는 않습니다.

함께 보기

• Form 모듈
• 양식 필드 평탄화
• 권한으로 암호화