CombinePDF Documentation

You can merge multiple PDF files or specific pages into a single PDF object using the << operator.

Note that adding an entire file via CombinePDF.load is faster than adding pages one by one.

To merge files:

pdf = CombinePDF.new
pdf << CombinePDF.load("file1.pdf")
pdf << CombinePDF.load("file2.pdf")
pdf.save "combined.pdf"

To merge specific pages (e.g., only even pages):

pdf = CombinePDF.new
i = 0
CombinePDF.load("file.pdf").pages.each do |page|
  i += 1
  pdf << page if i.even?
end
pdf.save "even_pages.pdf"

You can output the PDF content as a string (useful for web responses) or save it directly to a file.

To a string (Memory)

Use .to_pdf to get the raw PDF data string.

In a Rails controller:

send_data combined_file.to_pdf, filename: "combined.pdf", type: "application/pdf"

In Sinatra:

status 200
body combined_file.to_pdf
headers 'content-type' => "application/pdf"

To a file

Use the .save method:

combined_file.save "output.pdf"

CombinePDF can load data from the file system or parse raw PDF data directly from memory (useful for data received via HTTP or generated by other libraries like Prawn).

From a file

pdf = CombinePDF.load("file.pdf")

From memory (String)

pdf = CombinePDF.parse(pdf_data)

Example: Loading from a URL

require 'combine_pdf'
require 'net/http'

url = "https://example.com/my.pdf"
pdf = CombinePDF.parse Net::HTTP.get_response(URI.parse(url)).body

To use CombinePDF in your Ruby project, install the gem using the following command:

gem install combine_pdf

When 'stamping' one PDF page over another, font or resource conflicts can occur. To prevent this, use the copy(true) method. Passing true (the secure flag) ensures that resource identifiers (like fonts) are renamed to guarantee uniqueness in the new context.

Note: The older make_secure and make_unsecure methods are deprecated. Use copy(true) instead.

# Safe way to prepare a page for stamping/overlaying
safe_page = other_page.copy(true)
page << safe_page

You can load PDF data using CombinePDF.load for files or CombinePDF.parse for raw binary data in memory.

From a file

pdf = CombinePDF.load("file.pdf")

From memory (e.g., IO or network data)

pdf_data = IO.read 'file.pdf'
pdf = CombinePDF.parse(pdf_data)

You can overlay content (like a logo or text) onto existing PDF pages. To do this, import the content from another PDF and use the << operator on individual Page objects.

Note: The << operator behaves differently on PDF objects (merging files) versus Page objects (overlaying content).

Overlaying a PDF page (e.g., a logo)

company_logo = CombinePDF.load("company_logo.pdf").pages[0]
pdf = CombinePDF.load "content_file.pdf"
pdf.pages.each {|page| page << company_logo}
pdf.save "content_with_logo.pdf"

Using stamp_pages for overlays

If the stamp is a PDF page, you can use stamp_pages. Use the :underlay option to place the stamp behind the existing content:

# Overlay (default)
pdf.stamp_pages(stamp_page)

# Underlay (reverse-stamp)
pdf.stamp_pages(stamp_page, underlay: true)

Use set_font to create a font object and add it to the page's resources dictionary. This returns the name of the font to be used in the content stream.

Supported font symbols include:

• :Helvetica (and variants like `:

CombinePDF has specific behaviors for certain types of PDF files:

Encrypted PDFs

Encrypted files may fail quietly. To force a loud failure, use the raise_on_encrypted: true option:

CombinePDF.load(pdf_file, raise_on_encrypted: true)

This will raise a CombinePDF::EncryptionError.

Optional Content PDFs

If a PDF contains optional content sections, CombinePDF might raise an exception. You can bypass this by passing allow_optional_content: true to load or parse:

CombinePDF.load(pdf_file, allow_optional_content: true)