Archivos adjuntos

TCPDF-Next puede incrustar archivos arbitrarios dentro de un documento PDF. El sistema de adjuntos se gestiona a través de Navigation\FileAttachment y se accede mediante la API fluida de Document. Los adjuntos viajan con el PDF — los destinatarios pueden extraer los archivos incrustados directamente desde su visor.

Todos los métodos retornan static, por lo que cada llamada puede ser encadenada.

Referencia rápida

Método	Propósito
addFileAttachment()	Incrustar un archivo en el documento PDF

Ejemplo básico

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)

    // Adjuntar archivos de soporte
    ->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

Parámetro	Tipo	Descripción
$file	string	Ruta absoluta al archivo a incrustar
$name	string	Nombre para mostrar en el panel de adjuntos del visor (predeterminado: nombre de archivo original)
$desc	string	Descripción legible del adjunto
$mimeType	string	Tipo MIME (auto-detectado si está vacío)
$relationship	string	Relación de archivo asociado PDF 2.0 (Data, Source, Alternative, Supplement, Unspecified)

Casos de uso comunes

Adjuntar datos fuente, documentos complementarios u originales en alta resolución:

$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');

Cumplimiento PDF/A-3 y PDF/A-4

Los estándares de archivo PDF/A-3 y PDF/A-4 permiten archivos incrustados, haciendo que los adjuntos sean esenciales para el intercambio de datos estructurados. El caso de uso más prominente es la facturación electrónica ZUGFeRD / Factur-X, donde una factura XML legible por máquina se incrusta junto al PDF legible por humanos.

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)

    // Adjunto de e-factura 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

Al apuntar a PDF/A-3 o PDF/A-4, establece el parámetro $relationship para describir cómo se relaciona el adjunto con el documento. Los valores comunes son Data (representación de datos estructurados), Source (archivo fuente original) y Alternative (representación alternativa).

Metadatos de adjuntos

Los archivos incrustados llevan metadatos que los visores muestran en sus paneles de adjuntos:

Metadato	Fuente
Nombre de archivo	Parámetro $name (o nombre de archivo original)
Descripción	Parámetro $desc
Tipo MIME	Parámetro $mimeType (auto-detectado si está vacío)
Tamaño	Calculado automáticamente desde el archivo
Fecha de modificación	Leída de la marca de tiempo del sistema de archivos

Consejos

• Los adjuntos aumentan el tamaño del archivo PDF aproximadamente por el tamaño del archivo incrustado. Considera comprimir los adjuntos grandes antes de incrustarlos.
• Adobe Acrobat, Foxit Reader y la mayoría de los visores PDF de escritorio soportan adjuntos. Los visores basados en navegador típicamente no exponen el panel de adjuntos.
• No hay restricción de formato — puedes adjuntar cualquier tipo de archivo (CSV, XLSX, XML, PNG, ZIP, etc.).
• Para flujos de trabajo de facturación electrónica, siempre valida el XML contra el esquema del estándar relevante (ZUGFeRD, Factur-X o XRechnung) antes de incrustar.