Lampiran File

TCPDF-Next bisa menyematkan file sembarang di dalam dokumen PDF. Sistem lampiran dikelola melalui Navigation\FileAttachment dan diakses melalui API fluent Document. Lampiran ikut bersama PDF — penerima bisa mengekstrak file yang disematkan langsung dari viewer mereka.

Semua method mengembalikan static, sehingga setiap panggilan bisa di-chain.

Referensi Cepat

Method	Tujuan
addFileAttachment()	Sematkan file ke dalam dokumen PDF

Contoh Dasar

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->cell(0, 10, 'Invoice #2026-001', newLine: true)
    ->cell(0, 10, 'Spreadsheet asli dilampirkan ke PDF ini.', newLine: true)

    // Lampirkan file pendukung
    ->addFileAttachment('/path/to/invoice-data.xlsx', 'invoice-data.xlsx', 'Data invoice asli')
    ->addFileAttachment('/path/to/zugferd.xml', 'factur-x.xml', 'XML e-invoice Factur-X')

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

addFileAttachment()

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

Parameter	Tipe	Deskripsi
$file	string	Path absolut ke file yang akan disematkan
$name	string	Nama tampilan di panel lampiran viewer (default ke nama file asli)
$desc	string	Deskripsi lampiran yang bisa dibaca manusia
$mimeType	string	Tipe MIME (auto-detect jika kosong)
$relationship	string	Hubungan associated file PDF 2.0 (Data, Source, Alternative, Supplement, Unspecified)

Kasus Penggunaan Umum

Lampirkan data sumber, dokumen pendukung, atau original resolusi tinggi:

$pdf->addFileAttachment('/path/to/report-data.csv', 'report-data.csv', 'Export CSV mentah')
    ->addFileAttachment('/path/to/terms.pdf', 'terms-and-conditions.pdf', 'Syarat & Ketentuan')
    ->addFileAttachment('/path/to/photo-full.tiff', 'photo-full.tiff', 'Original resolusi penuh');

Kepatuhan PDF/A-3 dan PDF/A-4

Standar arsip PDF/A-3 dan PDF/A-4 mengizinkan file yang disematkan, menjadikan lampiran penting untuk pertukaran data terstruktur. Kasus penggunaan paling menonjol adalah e-invoicing ZUGFeRD / Factur-X, di mana invoice XML yang bisa dibaca mesin disematkan bersama PDF yang bisa dibaca manusia.

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, 'PDF ini berisi lampiran XML Factur-X.', newLine: true)

    // Lampiran e-invoice Factur-X / ZUGFeRD
    ->addFileAttachment(
        '/path/to/factur-x.xml',
        'factur-x.xml',
        'Data invoice Factur-X BASIC',
        'text/xml',
        'Data'
    )

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

TIP

Saat menargetkan PDF/A-3 atau PDF/A-4, set parameter $relationship untuk menjelaskan bagaimana lampiran berhubungan dengan dokumen. Nilai umum adalah Data (representasi data terstruktur), Source (file sumber asli), dan Alternative (representasi alternatif).

Metadata Lampiran

File yang disematkan membawa metadata yang ditampilkan viewer di panel lampiran mereka:

Metadata	Sumber
Nama file	Parameter $name (atau nama file asli)
Deskripsi	Parameter $desc
Tipe MIME	Parameter $mimeType (auto-detect jika kosong)
Ukuran	Dihitung otomatis dari file
Tanggal modifikasi	Dibaca dari timestamp filesystem file

Tips

• Lampiran menambah ukuran file PDF kira-kira sebesar ukuran file yang disematkan. Pertimbangkan untuk mengompresi lampiran besar sebelum menyematkan.
• Adobe Acrobat, Foxit Reader, dan sebagian besar PDF viewer desktop mendukung lampiran. Viewer berbasis browser biasanya tidak menampilkan panel lampiran.
• Tidak ada batasan format — Anda bisa melampirkan tipe file apa pun (CSV, XLSX, XML, PNG, ZIP, dll.).
• Untuk workflow e-invoicing, selalu validasi XML terhadap skema standar yang relevan (ZUGFeRD, Factur-X, atau XRechnung) sebelum menyematkan.