양식 필드를 정적 페이지 콘텐츠로 평탄화하기

한눈에 보기

이 레시피는 대화형 AcroForm을 평탄화합니다. 각 필드의 현재 값을 페이지 콘텐츠 스트림에 일반 그래픽으로 그린 다음, AcroForm 딕셔너리를 제거합니다. 그 결과물은 비대화형 양식, 즉 양식을 지원하지 않는 리더에서도 어디서나 동일하게 보이는 필드의 정적 표현입니다(ISO 32000-2 §12.7). 이 레시피는 examples/30-form-fields.php에서 양식을 빌드한 뒤 flattenForms()를 호출합니다.

설치

composer require nextpdf/core:^3

개념 개요

평탄화는 각 위젯을 해당 페이지에 “인쇄”합니다. 텍스트 필드는 BT … Tj … ET 텍스트가 됩니다. 체크박스와 라디오 버튼은 그려진 경로가 됩니다. 선택 필드는 선택된 항목을 렌더링합니다. 푸시 버튼은 정적인 버튼 모양의 상자를 렌더링합니다. 이는 필드 콘텐츠를 미리 알고 있을 때 정적으로 정의된 모양을 사용하는 사양 모델과 일치합니다(ISO 32000-2 §12.7). 값이 내장되므로 더 이상 사용되지 않는 NeedAppearances 메커니즘은 필요하지 않습니다.

프로파일은 structural입니다. 문서에는 트레일러 /ID가 포함되어 있으며, 후처리 패스는 두 번의 실행을 비교하기 전에 이를 정규화합니다.

API 표면

NextPDF\Core\Concerns\HasFormFields::flattenForms(): static은 문서에 생성된 모든 필드를 정적 페이지 콘텐츠로 평탄화하고 AcroForm을 제거합니다. 필드가 없으면 아무 작업도 수행하지 않습니다. 내부적으로는 작업을 NextPDF\Form\FormFlattener에 위임합니다.

필드 생성자를 사용해 양식을 빌드합니다. 단계는 PDF 양식 빌드 및 사전 채우기를 참조하세요. 그런 다음 save() 전에 flattenForms()를 호출합니다.

코드 샘플 — 빠른 시작

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

코드 샘플 — 프로덕션

아래 전체 예제는 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 — 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";

예상 출력:

Wrote flattened registration form

출력에는 동일한 값이 표시되지만 대화형 필드는 없습니다. 양식을 지원하지 않는 리더에서도 동일하게 렌더링됩니다.

엣지 케이스 및 주의 사항

평탄화는 되돌릴 수 없습니다. save()를 호출하고 나면 대화형 필드는 사라집니다. 나중에 값을 편집해야 할 가능성이 있다면 평탄화하지 않은 원본을 보관하세요.
호출 순서. flattenForms()는 필드를 생성한 후, 그리고 save() 전에 실행하세요. 필드가 없는 상태에서 호출하면 아무 작업도 수행하지 않으며, 이는 안전합니다.
서명 필드는 평탄화되지 않습니다. /Sig 필드의 시각적 표면은 다시 렌더링할 수 있는 값이 아니라 해당 CMS SignedData에서 생성된 모양입니다. 이를 다시 래스터화하면 검증 가능한 어떤 서명과도 더 이상 일치하지 않는 정적 “유령” 그래픽이 생성됩니다. 이 때문에 평탄화 도구는 서명 필드를 의도적으로 건너뜁니다. 양식은 서명 전에 평탄화하고, 서명 후에는 절대 평탄화하지 마세요.
체크박스의 참 여부. 체크박스는 값이 Yes/On/1/true일 때 체크 표시를 렌더링합니다. 값이 비어 있거나 Off이면 상자만 렌더링합니다.
평탄화된 텍스트의 글꼴. 평탄화된 텍스트는 현재 글꼴을 사용합니다. 글꼴이 설정되어 있지 않으면 Helvetica로 대체됩니다. CJK 문자나 사용자 지정 글꼴이 필요한 필드 값이라면 flattenForms() 전에 원하는 글꼴을 설정하세요.

성능

평탄화는 필드 수에 비례해 선형적으로 확장됩니다. 각 필드에 대해 범위가 제한된 콘텐츠 블록을 추가한 다음, AcroForm 객체를 제거합니다. 일반적인 양식은 1500ms / 64MB 예산 안에 충분히 들어옵니다.

보안 참고 사항

평탄화는 일반 리더에서 필드 값을 편집할 수 없게 만듭니다. 이는 표시 방식의 변경이며, 접근 제어가 아닙니다. 값은 페이지 콘텐츠에 그대로 표시되며, 어떤 텍스트 도구로도 추출할 수 있습니다. 평탄화를 편집 삭제(redaction)나 민감한 값 보호로 취급하지 마세요. 기밀성이 필요하다면 권한으로 암호화를 사용하세요. 권한 비트 또한 읽기 제한을 강제하지 않으므로, 해당 문서의 리더 협조형 주의 사항도 함께 읽어 보세요. 서명된 문서는 절대 평탄화하지 마세요. 먼저 평탄화한 다음 서명하세요.

적합성

설명	사양	조항
평탄화된 양식은 필드의 비대화형(정적) 표현입니다.	ISO 32000-2	§12.7
필드 모양은 콘텐츠를 미리 알고 있을 때 정적으로 정의됩니다.	ISO 32000-2	§12.7
내장된 모양은 더 이상 사용되지 않는 `NeedAppearances` 플래그를 불필요하게 만듭니다.	ISO 32000-2	§12.7

NextPDF는 인용된 조항에 설명된 정적 구조를 생성합니다. 이 설명이 포괄적인 ISO 32000-2 적합성을 주장하는 것은 아닙니다.