NAME
PDF::Make::Attachment - Embed file attachments in PDF documents
SYNOPSIS
use PDF::Make::Document;
use PDF::Make::Attachment;
my $doc = PDF::Make::Document->new;
$doc->add_page(612, 792);
# Attach from in-memory data
my $att = PDF::Make::Attachment->attach($doc,
name => 'config.json',
data => '{"key":"value"}',
mime => 'application/json',
description => 'Application config',
);
# Attach from file on disk
my $att2 = PDF::Make::Attachment->attach($doc,
name => 'report.xlsx',
path => '/path/to/report.xlsx',
);
# Inspect
print $att->name, "\n"; # config.json
print $att->filename, "\n"; # config.json
print $att->mime_type, "\n"; # application/json
print $att->size, " bytes\n"; # 15 bytes
# Extract back to bytes or file
my $bytes = $att->data;
$att->extract_to_file('/tmp/extracted.json');
$doc->to_file('with_attachments.pdf');DESCRIPTION
PDF::Make::Attachment embeds files into a PDF document as EmbeddedFile streams with Filespec dictionaries. Attachments appear in the PDF viewer's attachment panel and can be extracted by readers.
MIME types are auto-detected from the file extension when not specified (e.g. .json maps to application/json).
CLASS METHODS
attach($doc, %args)
my $att = PDF::Make::Attachment->attach($doc,
name => 'data.csv', # required
data => $csv_string, # provide data or path
path => '/path/to/file', # alternative to data
filename => 'data.csv', # display name (defaults to name)
mime => 'text/csv', # auto-detected if omitted
description => 'Raw data', # optional
);Create and attach a file to the document. Returns the attachment object. Either data (in-memory bytes) or path (file on disk) must be provided.
INSTANCE METHODS
name()
my $name = $att->name;Returns the attachment name (the key in the EmbeddedFiles name tree).
filename()
my $fn = $att->filename;Returns the display filename shown in the PDF viewer.
mime_type()
my $mime = $att->mime_type;Returns the MIME type string.
size()
my $bytes = $att->size;Returns the size of the embedded data in bytes.
data()
my $raw = $att->data;Returns the raw embedded file data as a byte string, or undef if empty.
extract_to_file($path)
$att->extract_to_file('/tmp/output.csv');Writes the embedded data to a file on disk. Croaks on failure.
write_to_doc($doc)
my $obj_num = $att->write_to_doc($doc);Writes the attachment's PDF objects (Filespec + EmbeddedFile stream) into the document. Returns the object number. This is called automatically by to_bytes/to_file for attachments created via attach().