SetaPDF-Merger Manual

PDF Forms

Introduction

The SetaPDF-Merger component is able to concatenate PDF documents including form fields.  

Also same named form fields are supported: By default  the component will rename a field by adding a numeric incrementing suffix (-N) if the field name already exists in another document that is part of the concatenation process.

This behavior can be controlled with the setRenameSameNamedFormFields() method. If this is set to false, same named form fields will be restructured and all names will be kept. 

Merge Same Form Several Times

PDF form fields are saved in a geared structure in a PDF document and are referenced in various way. They are registered in a global fields array but also referenced in annotation arrays which are bound to single pages.

The SetaPDF-Merger component allows you re-use a single page several times in a new document. This is done by copying the same page object several times. This works very well for flat PDF documents. If the copied pages have annotations attached to them, these annotations were only referenced (if they were created through indirect objects, which is the commen case). That to say the annotations which are referenced by the first instance of the merged page are absolutely the same as of the second or third merged page. 

Because annotations are editable parts of a PDF document (in this special case a form field) the change of a form field would end in changing all fields. While it's technically not prohibit to create such strucutres it's very hard for a reader application to handle such structures, because they are something special and uncommon.

If you need to copy a single PDF form several times to a new document you should always pass individual document instances to the merger instance to avoid unforeseeable events: 

<?php
require_once('library/SetaPDF/Autoload.php');

$merger = new \SetaPDF_Merger();
// This will result in a smal but geared structured PDF file and you should avoid it !!!
// $merger->addFile('files/pdfs/camtown/Order-Form.pdf');
// $merger->addFile('files/pdfs/camtown/Order-Form.pdf');
// $merger->addFile('files/pdfs/camtown/Order-Form.pdf');
// $merger->addFile('files/pdfs/camtown/Order-Form.pdf');

// This is the correct way!
$merger->addDocument(\SetaPDF_Core_Document::loadByFilename('files/pdfs/camtown/Order-Form.pdf'));
$merger->addDocument(\SetaPDF_Core_Document::loadByFilename('files/pdfs/camtown/Order-Form.pdf'));
$merger->addDocument(\SetaPDF_Core_Document::loadByFilename('files/pdfs/camtown/Order-Form.pdf'));
$merger->addDocument(\SetaPDF_Core_Document::loadByFilename('files/pdfs/camtown/Order-Form.pdf'));

// merge them together
$merger->merge();

Examples

Rename Same Named Form Fields

The following example will show the default behavior of the component: The fields will get renamed. If you set a value in a specific field, e.g. "Name", it will not get populated to the other "same named" fields:

<?php
require_once('library/SetaPDF/Autoload.php');

$merger = new \SetaPDF_Merger();
// add files with same named form fields
$merger->addFile('files/pdfs/camtown/Order-Form.pdf');
$merger->addFile('files/pdfs/etown/Order-Form.pdf');
$merger->addFile('files/pdfs/lenstown/Order-Form.pdf');
$merger->addFile('files/pdfs/tektown/Order-Form.pdf');

// merge them together
$merger->merge();

// get the resulting document instance
$document = $merger->getDocument();
// add a writer
$document->setWriter(new \SetaPDF_Core_Writer_Http('form-fields-1.pdf', true));
// save and finish
$document->save()->finish();

Don't Rename Same Named Form Fields

In this example the component will merge the same named fields into a new structure so that the names will not get changed. If you set a value in a specific field, e.g. "Name", it will get populated to the other "same named" fields as well: 

<?php
require_once('library/SetaPDF/Autoload.php');

$merger = new \SetaPDF_Merger();
// add files with same named form fields
$merger->addFile('files/pdfs/camtown/Order-Form.pdf');
$merger->addFile('files/pdfs/etown/Order-Form.pdf');
$merger->addFile('files/pdfs/lenstown/Order-Form.pdf');
$merger->addFile('files/pdfs/tektown/Order-Form.pdf');

// let's define that the field names should not be changed
$merger->setRenameSameNamedFormFields(false);

// merge them together
$merger->merge();

// get the resulting document instance
$document = $merger->getDocument();
// add a writer
$document->setWriter(new \SetaPDF_Core_Writer_Http('form-fields-1.pdf', true));
// save and finish
$document->save()->finish();