SetaPDF-Merger Manual

Refactor Version 1 Code With the release of version 2 there were changes that are not backwards compatible

Overview

SetaPDF 2 was rewritten from scratch. Because of this, code that was written for SetaPDF 1 cannot be used anymore without refactoring it.

Error Handling

While in version 1 error objects were returned, version 2 uses Exceptions throughout. More details can be found here.

Loading the Component

In version 1 it was a requirement that the SetaPDF folder was available through the include_path. In version 2 all class loading is done by an autoload implementation. So only one file has to be required:

require_once('/absolute/path/to/library/SetaPDF/Autoload.php');

or

require_once('../relative/path/to/library/SetaPDF/Autoload.php');

General Refactoring

Because most method parameters are changed to object properties or methods were removed and replaced by other logic workflows old SetaPDF code has to be refactored and or rewritten.

For example the factory()-method is removed and the merge()-method's signature changed. Because of this existing code has to be refactored as following example:

$fileA = 'A.pdf';
$fileB = 'B.pdf';
$mergedPdf = 'AB.pdf';
$stream = true;
 
// Old style for SetaPDF 
$merger = \SetaPDF_Merger::factory();
$merger->addFile($fileA);
$merger->addFile($fileB);
     
//...
     
$merger->merge($mergedPdf, 'I', $stream);

Which will become:

$merger = new \SetaPDF_Merger();
$merger->addFile($fileA);
$merger->addFile($fileB);

//...
     
$merger->merge();
$document = $merger->getDocument();
if ($stream) {
    $writer = new \SetaPDF_Core_Writer_Http($filenameOut, true);
} else {
    $writer = new \SetaPDF_Core_Writer_HttpStream($filenameOut, true);
}
$document->setWriter($writer);
$document->save()->finish();

In version 2 reading and writing PDF files is done via reader and writer classes throughout. 

Removed Methods

Following methods are removed in the main SetaPDF_Merger class:

• factory()
• getPageCount()
• setAuthor()
• setCreator()
• setKeywords()
• setSubject()
• setTitle()
• setDisplayMode()
• setPageMode()
• setHandleNamedReferences()
• setAddBookmarks()
• setPdfVersionCallback()
• setFormFieldNamesCallback()
• extract()

If your code relies on these methods, make sure you refactor it!

Most of these methods and their logic are implemented in the new core system of version 2.0.

Refactor Usage of Version 1 Methods

As already written the complete component was rewritten. Because of this, methods were removed or changed.

The method extract() is completely removed without any direct counterpart.
This method setFormFieldNamesCallback() is completely removed because simple renaming of form fields will result in corrupted PDF documents.

The refactoring of the other removed or changed methods is described in the following. 

The getPageCount() and setPageMode() Method

A page count can be resolved through the document instance:

$document = \SetaPDF_Core_Document::loadByFilename('filename.pdf');
$pages = $document->getCatalog()->getPages();
$pageCount = $pages->count();
// or
$pageCount = count($pages);

The setPageMode() method becomes part of the Core system through the SetaPDF_Core_Document_Catalog::setPageMode() method.

$merger->setPageMode('UseOutlines');
// becomes
$document = $merger->getDocument();
$catalog = $document->getCatalog();
$catalog->setPageMode(\SetaPDF_Core_Document_PageMode::USE_OUTLINES);

If you do not want to use separate object instances you can also go through the merger instance, to access a document instance:

$document = $merger->getDocumentByFileName('filename.pdf');
$pages = $document->getCatalog()->getPages();
$pageCount = $pages->count();
// or
$pageCount = count($pages);

Methods That Moved to the Documents Info Object

The methods setAuthor(), setCreator(), setKeywords(), setSubject() and setTitle() are available through methods of a documents Info object.

$document = $merger->getDocument();
$info = $document->getInfo();
$info->setAuthor('Setasign');
$info->setCreator('SetaPDF');
// ...

The setDisplayMode() Method

This method also becomes part of the Core system. Both parameters are available by following helper classes.

$merger->setDisplayMode('fullpage', 'single');
// becomes
$document = $merger->getDocument();
$catalog = $document->getCatalog();
$catalog->setOpenAction(\SetaPDF_Core_Document_Destination::createByPageNo($document, 1, 'Fit'));
$catalog->setPageLayout(\SetaPDF_Core_Document_PageLayout::SINGLE_PAGE);
     
// another example
$merger->setDisplayMode(120, 'single');
// becomes
$document = $merger->getDocument();
$catalog = $document->getCatalog();
$catalog->setOpenAction(\SetaPDF_Core_Document_Destination::createByPageNo($document, 1, 'XYZ', null, null, 120 / 100));
$catalog->setPageLayout(\SetaPDF_Core_Document_PageLayout::SINGLE_PAGE);

The setHandleNamedReferences() Method

This method is renamed to SetaPDF_Merger::setHandleNames().

The new method also accepts a callback as the second parameter which will be used to handle name clashes of different documents. See SetaPDF_Core_DataStructure_NameTree::adjustNameCallback().

The setAddBookmarks() Method

This method is removed. Bookmark entries could be added by passing the correct parameter to the SetaPDF_Merger::addFile() or SetaPDF_Merger::addDocument() method.

To emulate the old behavior a very flexible core implementation for handling outlines could be used: SetaPDF_Core_Document_Catalog_Outlines

The $showOutline parameter could be replaced by:

$document = $merger->getDocument();
$catalog = $document->getCatalog();
$catalog->setPageMode(\SetaPDF_Core_Document_PageMode::USE_OUTLINES);

The setPdfVersionCallback() Method

This method is removed. The PDF version can be changed/accessed through the document instance:

• SetaPDF_Core_Document::getPdfVerion()
• SetaPDF_Core_Document::setPdfVerion()
• SetaPDF_Core_Document::setMinPdfVerion()