SetaPDF_Merger The main class of the SetaPDF-Merger Component

File: /SetaPDF/Merger.php

Class hierarchy

Summary

Constants

COPY_OUTLINES_AS_CHILDS

const string SetaPDF_Merger::COPY_OUTLINES_AS_CHILDS = 'copyOutlinesAsChilds'

Constant defines that existing outline items should be copied as child items to the newly created outline item

COPY_OUTLINES_TO_ROOT

const string SetaPDF_Merger::COPY_OUTLINES_TO_ROOT = 'copyOutlinesToRoot'

Constant defines that existing outlines items should be copied to the outlines root

OUTLINES_BOLD

const string SetaPDF_Merger::OUTLINES_BOLD = 'bold'

Key for the bold style property of an outline item

OUTLINES_COLOR

const string SetaPDF_Merger::OUTLINES_COLOR = 'color'

Key for the color property of an outline item

OUTLINES_COPY

const string SetaPDF_Merger::OUTLINES_COPY = 'copy'

Key for the copy behavior of an outline item

OUTLINES_ITALIC

const string SetaPDF_Merger::OUTLINES_ITALIC = 'italic'

Key for the italic style property of an outline item

OUTLINES_PARENT

const string SetaPDF_Merger::OUTLINES_PARENT = 'parent'

Key for the parent property of an outline item

OUTLINES_TITLE

const string SetaPDF_Merger::OUTLINES_TITLE = 'title'

Key for the title property of an outline item

PAGES_ALL

const string SetaPDF_Merger::PAGES_ALL = 'all'

Keyword for all pages

PAGES_FIRST

const string SetaPDF_Merger::PAGES_FIRST = 'first'

Keyword for the first page

PAGES_LAST

const string SetaPDF_Merger::PAGES_LAST = 'last'

Keyword for the last page

VERSION

const string SetaPDF_Merger::VERSION = '2.24.0.1049'

Version


Properties

$_adjustNameCallback

Callback method used for renaming names

See

$_currentDocument

The currently processed document instance.

$_documentCache

protected array SetaPDF_Merger::$_documentCache = array()

Cache for document objects by filename

$_documents

protected array SetaPDF_Merger::$_documents = array()

The documents/pages which should be added

$_handleNames

protected boolean SetaPDF_Merger::$_handleNames = true

Should names be copied/handled

$_initialDocument

The initial document is the document to which the new documents/pages will be added.

It will be created automatically if none was provided in the constructor.

$_maxFileHanlder

$_renameSameNamedFormFields

Flag saying if same named form fields should be renamed.

$beforePageAddedCallback

A callback which is called just before a page is added to the new document

See

$rewrittenFormFieldNamesData

An array to save information about changed form fields


Methods

__construct()

public SetaPDF_Merger::__construct ( [ SetaPDF_Core_Document $initialDocument = null ] )

The constructor.

Parameters
$initialDocument : SetaPDF_Core_Document

The initial document to start with

_beforePageAdded()

protected void SetaPDF_Merger::_beforePageAdded ( SetaPDF_Core_Document_Page $page, int $pageNumber )

Will be called just before a page is added to the pages tree.

An own callback can be defined through the $beforePageAddedCallback property. Or this method can be overwritten to implement own logic in the scope of the class.

Parameters
$page : SetaPDF_Core_Document_Page

The page that will be added

$pageNumber : int

The number of the page

_checkOutlinesConfig()

protected int|null SetaPDF_Merger::_checkOutlinesConfig ( string|array $outlinesConfig )

Checks the $outlinesConfig parameter if it is possible to add childs to the resulting outline item.

Parameters
$outlinesConfig : string|array

The outlines config

_checkPageNumber()

protected boolean SetaPDF_Merger::_checkPageNumber ( integer $pageNumber [, null|integer|string|array|callback $condition = null ] )

Checks a page number against a condition.

Parameters
$pageNumber : integer

The page number

$condition : null|integer|string|array|callback

Valid conditions are:

  • PAGES_XXX constant or null (equal to SetaPDF_Merger::PAGES_ALL)
  • Integer with the valid page number
  • String with the valid page number or the valid range (e.g. '10-12')
  • Array with all valid page numbers
  • Callback with the arguments (int $pageNumber, SetaPDF_Core_Document $document)

_getDocument()

protected SetaPDF_Core_Document SetaPDF_Merger::_getDocument ( string|SetaPDF_Core_Document $filename [, boolean $cache = true ] )

Get a document instance by filename.

Parameters
$filename : string|SetaPDF_Core_Document

The filename

$cache : boolean

Cache the document by filename

Exceptions

Throws SetaPDF_Merger_Exception

_handleAcroForms()

protected void SetaPDF_Merger::_handleAcroForms ( array $touchedPdfs )

Handle AcroForm data.

Parameters
$touchedPdfs : array
 

_handleAcroFormsByMergingSameNamedFields()

protected void SetaPDF_Merger::_handleAcroFormsByMergingSameNamedFields ( array $touchedPdfs )

Handles AcroForm data by merging same named form fields.

Parameters
$touchedPdfs : array
 

_handleAcroFormsByRenamingSameNamedFields()

protected void SetaPDF_Merger::_handleAcroFormsByRenamingSameNamedFields ( array $touchedPdfs )

Handles AcroForm data by renaming same named form fields.

Parameters
$touchedPdfs : array
 

_handleNames()

protected void SetaPDF_Merger::_handleNames ( array $touchedPdfs, array $namedDestinations )

Imports names of all used documents and defined named destinations.

Parameters
$touchedPdfs : array
 
$namedDestinations : array
 

_handleOptionalContent()

protected void SetaPDF_Merger::_handleOptionalContent ( array $touchedPdfs )

Handles optional content data (Layers).

Parameters
$touchedPdfs : array
 

_handleOutlines()

protected void SetaPDF_Merger::_handleOutlines ( array $touchedPdfs, array $outlineTargets )

Handle creation and import of outlines.

Parameters
$touchedPdfs : array
 
$outlineTargets : array
 

addDocument()

public int|null SetaPDF_Merger::addDocument ( SetaPDF_Core_Document|array $documentOrConfig [, mixed $pages = null [, string $name = null [, null|string|array $outlinesConfig = null [, boolean $copyLayers = true ]]]] )

Add a document.

Same as addFile() but the document has to be passed as SetaPDF_Core_Document instance.

Parameters
$documentOrConfig : SetaPDF_Core_Document|array

The document or config array. If an array is passed the keys has to be named as the method parameters. All other parameters are optional then.

$pages : mixed

The pages to add from the file. See _checkPageNumber() for a full description.

$name : string

The name for a named destination for this document

$outlinesConfig : null|string|array

The outlines config

$copyLayers : boolean

Whether to copy layer information of the document

Exceptions

Throws InvalidArgumentException

See

addFile()

public int|null SetaPDF_Merger::addFile ( string|array $filenameOrConfig [, mixed $pages = null [, string $name = null [, null|string|array $outlinesConfig = null [, boolean $copyLayers = true ]]]] )

Add a document by filename.

The document could include dynamic content like form fields, links or any other page annotation.

Form fields are handled especially: If a document was added with form fields which names were already used by a previously added document the field name will be suffixed with a slash and a number.

This behavior may lead to corrupted java scripts which may calculate field sums by field names!

Parameters
$filenameOrConfig : string|array

The filename or config array. If an array is passed the keys has to be named as the method parameters. All other parameters are optional then.

$pages : mixed

The pages to add from the file. See _checkPageNumber() for a full description.

$name : string

The name for a named destination for this file

$outlinesConfig : null|string|array

The outlines config

$copyLayers : boolean

Whether to copy layer information of the document

Exceptions

Throws InvalidArgumentException

cleanUp()

public void SetaPDF_Merger::cleanUp ( void )

Release objects to free memory and cycled references.

After calling this method the instance of this object is unusable!

getCurrentDocument()

Get the currently processed document instance.

This method can be used to get the document instance that is actually processed if an Exception is thrown.

getDocument()

Alias for getInitialDocument.

getDocumentByFilename()

public SetaPDF_Core_Document SetaPDF_Merger::getDocumentByFilename ( string $filename [, boolean $cache = true ] )

Get a document instance by a filename.

Parameters
$filename : string

The filename

$cache : boolean

Cache the document by filename

getInitialDocument()

getMaxFileHandler()

Get the maximum file handler.

getPageCount()

public integer SetaPDF_Merger::getPageCount ( string|SetaPDF_Core_Document $filename [, boolean $cacheDocumentInstance = true ] )

Helper method to get the page count of a document or file.

Parameters
$filename : string|SetaPDF_Core_Document

The filename or the document instance

$cacheDocumentInstance : boolean

Cache the document instance or not

merge()

Merges the documents/pages in memory.

This method merges the documents and/or pages to the initial document object without calling the save()-method. The document is hold in memory until it is "manually" saved through the initial document instance.

Exceptions

Throws SetaPDF_Core_SecHandler_Exception, SetaPDF_Merger_Exception

rewriteNamesCallback()

Callback method for renaming string values of renamed names.

Parameters
$document : SetaPDF_Core_Document

The document instance

$value : SetaPDF_Core_Type_StringValue

The string value

See

setHandleNames()

public void SetaPDF_Merger::setHandleNames ( [ boolean $handleNames = true [, null|callback $adjustNameCallback = null ]] )

Defines that the document's name dictionaries are merged into the resulting document.

This behavior is enabled by default. It sadly needs much memory and script runtime, because name trees could be very huge.

Parameters
$handleNames : boolean

The flag status

$adjustNameCallback : null|callback

See SetaPDF_Core_DataStructure_Tree::merge() for a detailed description of the callback

setMaxFileHandler()

public void SetaPDF_Merger::setMaxFileHandler ( [ SetaPDF_Core_Reader_MaxFileHandler|null $handler = null ] )

Set the maximum file handler.

Parameters
$handler : SetaPDF_Core_Reader_MaxFileHandler|null
 

setRenameSameNamedFormFields()

public void SetaPDF_Merger::setRenameSameNamedFormFields ( [ bool $renameSameNamedFormFields = true ] )

Set the flag defining if same named form fields should be renamed (default behavior).

If this flag is set to false the fields will be merged so that all same named fields will have the same value. Notice that this could occur in an incorrect appearance if the initial values are different.

Parameters
$renameSameNamedFormFields : bool

The flag status

setWriter()

Set the writer for the initial document.

Parameters
$writer : SetaPDF_Core_Writer_WriterInterface

The writer instance