SetaPDF_Merger The main class of the SetaPDF-Merger Component

File: /SetaPDF v2/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.26.0.1122'

Version


Properties

$_adjustNameCallback

protected callback SetaPDF_Merger::$_adjustNameCallback

Callback method used for renaming names

See

$_currentDocument

protected SetaPDF_Core_Document SetaPDF_Merger::$_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

protected SetaPDF_Core_Document SetaPDF_Merger::$_initialDocument

The initial document

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

protected SetaPDF_Core_Reader_MaxFileHandler SetaPDF_Merger::$_maxFileHanlder

A max file handler.

$_renameSameNamedFormFields

protected bool SetaPDF_Merger::$_renameSameNamedFormFields = true

Flag saying if same named form fields should be renamed.

$beforePageAddedCallback

public null|callback SetaPDF_Merger::$beforePageAddedCallback

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

See

$rewrittenFormFieldNamesData

public array SetaPDF_Merger::$rewrittenFormFieldNamesData = array()

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 SetaPDF_Merger::_beforePageAdded (
SetaPDF_Core_Document_Page $page, int $pageNumber
): void

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 SetaPDF_Merger::_checkOutlinesConfig (
string|array $outlinesConfig
): int|null

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 SetaPDF_Merger::_checkPageNumber (
integer $pageNumber [, null|integer|string|array|callback $condition = null ]
): boolean

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_Merger::_getDocument (
string|SetaPDF_Core_Document $filename [, boolean $cache = true ]
): SetaPDF_Core_Document

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 SetaPDF_Merger::_handleAcroForms (
array $touchedPdfs
): void

Handle AcroForm data.

Parameters
$touchedPdfs : array
 

_handleAcroFormsByMergingSameNamedFields()

protected SetaPDF_Merger::_handleAcroFormsByMergingSameNamedFields (
array $touchedPdfs
): void

Handles AcroForm data by merging same named form fields.

Parameters
$touchedPdfs : array
 

_handleAcroFormsByRenamingSameNamedFields()

protected SetaPDF_Merger::_handleAcroFormsByRenamingSameNamedFields (
array $touchedPdfs
): void

Handles AcroForm data by renaming same named form fields.

Parameters
$touchedPdfs : array
 

_handleNames()

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

Imports names of all used documents and defined named destinations.

Parameters
$touchedPdfs : array
 
$namedDestinations : array
 

_handleOptionalContent()

protected SetaPDF_Merger::_handleOptionalContent (
array $touchedPdfs
): void

Handles optional content data (Layers).

Parameters
$touchedPdfs : array
 

_handleOutlines()

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

Handle creation and import of outlines.

Parameters
$touchedPdfs : array
 
$outlineTargets : array
 

_removeFormFieldFromFieldTree()

protected SetaPDF_Merger::_removeFormFieldFromFieldTree (
$fieldObject
): void

Removes a form field in its parent fields array

Parameters
$fieldObject
 

addDocument()

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

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 SetaPDF_Merger::addFile (
string|array $filenameOrConfig [, mixed $pages = null [, string $name = null [, null|string|array $outlinesConfig = null [, boolean $copyLayers = true ]]]]
): int|null

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 SetaPDF_Merger::cleanUp (
void
): 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_Merger::getDocumentByFilename (
string $filename [, boolean $cache = true ]
): SetaPDF_Core_Document

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 SetaPDF_Merger::getPageCount (
string|SetaPDF_Core_Document $filename [, boolean $cacheDocumentInstance = true ]
): integer

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

Throws 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 SetaPDF_Merger::setHandleNames (
[ boolean $handleNames = true [, null|callback $adjustNameCallback = null ]]
): void

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 SetaPDF_Merger::setMaxFileHandler (
[ SetaPDF_Core_Reader_MaxFileHandler|null $handler = null ]
): void

Set the maximum file handler.

Parameters
$handler : SetaPDF_Core_Reader_MaxFileHandler|null
 

setRenameSameNamedFormFields()

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

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