첨부 파일

TCPDF-Next는 PDF 문서 내부에 임의의 파일을 임베드할 수 있습니다. 첨부 시스템은 Navigation\FileAttachment를 통해 관리되며 Document 플루언트 API를 통해 접근합니다. 첨부 파일은 PDF와 함께 이동합니다 -- 수신자는 뷰어에서 직접 임베드된 파일을 추출할 수 있습니다.

모든 메서드는 static을 반환하므로 모든 호출을 체이닝할 수 있습니다.

빠른 참조

메서드	용도
addFileAttachment()	PDF 문서에 파일 임베드

기본 예제

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'Invoice #2026-001', newLine: true)
    ->cell(0, 10, 'The original spreadsheet is attached to this PDF.', newLine: true)

    // 보조 파일 첨부
    ->addFileAttachment('/path/to/invoice-data.xlsx', 'invoice-data.xlsx', 'Original invoice data')
    ->addFileAttachment('/path/to/zugferd.xml', 'factur-x.xml', 'Factur-X e-invoice XML')

    ->save('invoice-with-attachments.pdf');

addFileAttachment()

$pdf->addFileAttachment(
    string $file,
    string $name = '',
    string $desc = '',
    string $mimeType = '',
    string $relationship = 'Unspecified'
): static

매개변수	유형	설명
$file	string	임베드할 파일의 절대 경로
$name	string	뷰어의 첨부 패널에 표시되는 이름 (기본값은 원래 파일명)
$desc	string	사람이 읽을 수 있는 첨부 파일 설명
$mimeType	string	MIME 유형 (비어 있으면 자동 감지)
$relationship	string	PDF 2.0 관련 파일 관계 (Data, Source, Alternative, Supplement, Unspecified)

일반적인 활용 사례

원본 데이터, 보충 문서 또는 고해상도 원본을 첨부합니다:

$pdf->addFileAttachment('/path/to/report-data.csv', 'report-data.csv', 'Raw CSV export')
    ->addFileAttachment('/path/to/terms.pdf', 'terms-and-conditions.pdf', 'Terms & Conditions')
    ->addFileAttachment('/path/to/photo-full.tiff', 'photo-full.tiff', 'Full-resolution original');

PDF/A-3 및 PDF/A-4 준수

PDF/A-3 및 PDF/A-4 보관 표준은 임베드된 파일을 허용하여 구조화된 데이터 교환에 첨부 파일이 필수적입니다. 가장 대표적인 사용 사례는 ZUGFeRD / Factur-X 전자 송장으로, 기계 판독 가능한 XML 송장이 사람이 읽을 수 있는 PDF와 함께 임베드됩니다.

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setPDFVersion('2.0')
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'Electronic Invoice', newLine: true)
    ->cell(0, 10, 'This PDF contains a Factur-X XML attachment.', newLine: true)

    // Factur-X / ZUGFeRD 전자 송장 첨부
    ->addFileAttachment(
        '/path/to/factur-x.xml',
        'factur-x.xml',
        'Factur-X BASIC invoice data',
        'text/xml',
        'Data'
    )

    ->save('e-invoice.pdf');

TIP

PDF/A-3 또는 PDF/A-4를 대상으로 할 때, $relationship 매개변수를 설정하여 첨부 파일이 문서와 어떤 관계인지 설명하십시오. 일반적인 값은 Data(구조화된 데이터 표현), Source(원본 소스 파일), Alternative(대체 표현)입니다.

첨부 파일 메타데이터

임베드된 파일은 뷰어의 첨부 패널에 표시되는 메타데이터를 담고 있습니다:

메타데이터	출처
파일명	$name 매개변수 (또는 원래 파일명)
설명	$desc 매개변수
MIME 유형	$mimeType 매개변수 (비어 있으면 자동 감지)
크기	파일에서 자동 계산
수정 날짜	파일의 파일 시스템 타임스탬프에서 읽음

팁

• 첨부 파일은 임베드된 파일 크기만큼 PDF 파일 크기를 증가시킵니다. 큰 첨부 파일은 임베딩 전에 압축하는 것을 고려하십시오.
• Adobe Acrobat, Foxit Reader 및 대부분의 데스크톱 PDF 뷰어는 첨부 파일을 지원합니다. 브라우저 기반 뷰어는 일반적으로 첨부 패널을 노출하지 않습니다.
• 형식 제한은 없습니다 -- 모든 파일 유형(CSV, XLSX, XML, PNG, ZIP 등)을 첨부할 수 있습니다.
• 전자 송장 워크플로우의 경우, 임베딩 전에 항상 관련 표준 스키마(ZUGFeRD, Factur-X 또는 XRechnung)에 대해 XML을 검증하십시오.