Index

  1. \setasign\SetaPDF2
    1. Merger
      1. Collection
      2. Collection
      3. Exception
      4. Merger

setasign\SetaPDF2\Merger

Merger The main class of the SetaPDF-Merger Component

File: /SetaPDF v2/Merger/Merger.php
Old class name (alias): \SetaPDF_Merger

Class hierarchy

Summary

Methods

Properties

Constants

Constants

COPY_OUTLINES_AS_CHILDS

public const string 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

public const string Merger::COPY_OUTLINES_TO_ROOT = 'copyOutlinesToRoot'

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

DESTINATION_FIT_MODE

public const string Merger::DESTINATION_FIT_MODE = 'fitMode'

Keyword for the destination fit mode.

DESTINATION_NAME

public const string Merger::DESTINATION_NAME = 'name'

Keyword for the destination name.

OUTLINES_BOLD

public const string Merger::OUTLINES_BOLD = 'bold'

Key for the bold style property of an outline item

OUTLINES_COLOR

public const string Merger::OUTLINES_COLOR = 'color'

Key for the color property of an outline item

OUTLINES_COPY

public const string Merger::OUTLINES_COPY = 'copy'

Key for the copy behavior of an outline item

OUTLINES_FIT_MODE

public const Merger::OUTLINES_FIT_MODE = 'fitMode'

Key for the fit-mode property of an outline item destination

OUTLINES_ITALIC

public const string Merger::OUTLINES_ITALIC = 'italic'

Key for the italic style property of an outline item

OUTLINES_PARENT

public const string Merger::OUTLINES_PARENT = 'parent'

Key for the parent property of an outline item

OUTLINES_TITLE

public const string Merger::OUTLINES_TITLE = 'title'

Key for the title property of an outline item

PAGES_ALL

public const string Merger::PAGES_ALL = 'all'

Keyword for all pages

PAGES_FIRST

public const string Merger::PAGES_FIRST = 'first'

Keyword for the first page

PAGES_LAST

public const string Merger::PAGES_LAST = 'last'

Keyword for the last page

VERSION

public const string Merger::VERSION = '2.47.0.2095'

Version


Properties

$_adjustNameCallback

protected callback Merger::$_adjustNameCallback

Callback method used for renaming names

See

$_currentDocument

protected \SetaPDF_Core_Document Merger::$_currentDocument

The currently processed document instance.

$_documentCache

protected array Merger::$_documentCache = array()

Cache for document objects by filename

$_documents

protected array Merger::$_documents = array()

The documents/pages which should be added

$_handleNames

protected bool Merger::$_handleNames = true

Should names be copied/handled

$_initialDocument

protected \SetaPDF_Core_Document 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.

$_maxFileHandler

protected \SetaPDF_Core_Reader_MaxFileHandler Merger::$_maxFileHandler

A max file handler.

$_renameSameNamedFormFields

protected bool Merger::$_renameSameNamedFormFields = true

Flag saying if same named form fields should be renamed.

$beforePageAddedCallback

public ?callback Merger::$beforePageAddedCallback

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

See

Methods

__construct()

public Merger::__construct (
?\SetaPDF_Core_Document $initialDocument = null
)

The constructor.

Parameters
$initialDocument : ?\SetaPDF_Core_Document

The initial document to start with

_beforePageAdded()

protected 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 Merger::_checkOutlinesConfig (
string|array $outlinesConfig
): ?int

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 Merger::_checkPageNumber (
int $pageNumber,
null|int|string|array|callback $condition = null
): bool

Checks a page number against a condition.

Parameters
$pageNumber : int

The page number

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

Valid conditions are:

  • PAGES_XXX constant or null (equal to 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, \setasign\SetaPDF2\Core\Document $document)

Exceptions

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

Throws \setasign\SetaPDF2\Core\Type\Exception

_copyDefaultResources()

protected Merger::_copyDefaultResources (): void

Helper method that copies the default resources in the AcroForm dictionary.

Parameters
$acroForm : \SetaPDF_Core_Document_Catalog_AcroForm
 
$resAcroForm : \SetaPDF_Core_Document_Catalog_AcroForm
 
$resDocument : \SetaPDF_Core_Document
 
Exceptions

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

Throws \setasign\SetaPDF2\Core\Type\Exception

_ensureNameConfig()

protected Merger::_ensureNameConfig (
array|string|null $nameConfig
): ?array

Ensures the name config array.

Parameters
$nameConfig : array|string|null
 

_ensureOutlinesConfig()

protected Merger::_ensureOutlinesConfig (
array|string|null $outlinesConfig
): ?array

Ensures the outlines configuration array.

Parameters
$outlinesConfig : array|string|null
 

_getDocument()

protected Merger::_getDocument (
string|\SetaPDF_Core_Document $filename,
bool $cache = true
): \SetaPDF_Core_Document

Get a document instance by filename.

Parameters
$filename : string|\SetaPDF_Core_Document

The filename

$cache : bool

Cache the document by filename

Exceptions

Throws Exception

_handleAcroForms()

protected Merger::_handleAcroForms (
array $touchedPdfs
): void

Handle AcroForm data.

Parameters
$touchedPdfs : array
 
Exceptions

Throws \setasign\SetaPDF2\Core\Document\ObjectNotFoundException

Throws \setasign\SetaPDF2\Core\Exception

Throws \setasign\SetaPDF2\Core\Parser\Pdf\InvalidTokenException

Throws \setasign\SetaPDF2\Core\Reader\Exception

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

Throws \setasign\SetaPDF2\Core\Type\Exception

Throws \setasign\SetaPDF2\Core\Type\IndirectReference\Exception

Throws \setasign\SetaPDF2\Exception

Throws \setasign\SetaPDF2\NotImplementedException

Throws Exception

_handleAcroFormsByMergingSameNamedFields()

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

Handles AcroForm data by merging same named form fields.

Parameters
$touchedPdfs : array
 
Exceptions

Throws \setasign\SetaPDF2\Core\Document\ObjectNotFoundException

Throws \setasign\SetaPDF2\Core\Exception

Throws \setasign\SetaPDF2\Core\Parser\Pdf\InvalidTokenException

Throws \setasign\SetaPDF2\Core\Reader\Exception

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

Throws \setasign\SetaPDF2\Core\Type\Exception

Throws \setasign\SetaPDF2\Core\Type\IndirectReference\Exception

Throws \setasign\SetaPDF2\Exception

Throws \setasign\SetaPDF2\NotImplementedException

Throws Exception

_handleAcroFormsByRenamingSameNamedFields()

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

Handles AcroForm data by renaming same named form fields.

Parameters
$touchedPdfs : array
 
Exceptions

Throws \setasign\SetaPDF2\Core\Document\ObjectNotFoundException

Throws \setasign\SetaPDF2\Core\Exception

Throws \setasign\SetaPDF2\Core\Parser\Pdf\InvalidTokenException

Throws \setasign\SetaPDF2\Core\Reader\Exception

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

Throws \setasign\SetaPDF2\Core\Type\Exception

Throws \setasign\SetaPDF2\Core\Type\IndirectReference\Exception

Throws \setasign\SetaPDF2\Exception

Throws \setasign\SetaPDF2\NotImplementedException

Throws Exception

_handleNames()

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

Imports names of all used documents and defined named destinations.

Parameters
$touchedPdfs : array
 
$namedDestinations : array
 
Exceptions

Throws \setasign\SetaPDF2\Core\DataStructure\Tree\KeyAlreadyExistsException

Throws \setasign\SetaPDF2\Core\Exception

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

Throws \setasign\SetaPDF2\Core\Type\Exception

Throws Exception

_handleOptionalContent()

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

Handles optional content data (Layers).

Parameters
$touchedPdfs : array
 
Exceptions

Throws \setasign\SetaPDF2\Core\Type\Exception

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

Throws Exception

_handleOutlines()

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

Handle creation and import of outlines.

Parameters
$touchedPdfs : array
 
$outlineTargets : array
 
Exceptions

Throws \setasign\SetaPDF2\Core\Exception

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

Throws \setasign\SetaPDF2\Core\Type\Exception

Throws Exception

_removeFormFieldFromFieldTree()

protected Merger::_removeFormFieldFromFieldTree (): void

Removes a form field in its parent fields array

Parameters
$fieldObject : \SetaPDF_Core_Type_IndirectObjectInterface
 
Exceptions

Throws \setasign\SetaPDF2\Core\Document\ObjectNotFoundException

Throws \setasign\SetaPDF2\Core\Exception

Throws \setasign\SetaPDF2\Core\Parser\Pdf\InvalidTokenException

Throws \setasign\SetaPDF2\Core\Reader\Exception

Throws \setasign\SetaPDF2\Core\Type\Exception

Throws \setasign\SetaPDF2\Core\Type\IndirectReference\Exception

Throws \setasign\SetaPDF2\Exception

Throws \setasign\SetaPDF2\NotImplementedException

addDocument()

public Merger::addDocument (
\SetaPDF_Core_Document|array $documentOrConfig,
mixed $pages = null,
string|array $nameConfig = null,
null|string|array $outlinesConfig = null,
bool $copyLayers = true
): ?int

Add a document.

Same as addFile() but the document has to be passed as \setasign\SetaPDF2\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.

$nameConfig : string|array

The configuration for a named destination for this file.

$outlinesConfig : null|string|array

The outlines config

$copyLayers : bool

Whether to copy layer information of the document

Exceptions

Throws \InvalidArgumentException

See

addFile()

public Merger::addFile (
string|array $filenameOrConfig,
mixed $pages = null,
string|array $nameConfig = null,
null|string|array $outlinesConfig = null,
bool $copyLayers = true
): ?int

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.

$nameConfig : string|array

The configuration for a named destination for this file.

$outlinesConfig : null|string|array

The outlines config,

$copyLayers : bool

Whether to copy layer information of the document.

Exceptions

Throws \InvalidArgumentException

cleanUp()

public Merger::cleanUp (
void
): void

Release objects to free memory and cycled references.

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

Exceptions

Throws Exception

getCurrentDocument()

public Merger::getCurrentDocument (
void
): \SetaPDF_Core_Document

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()

public Merger::getDocument (
void
): \SetaPDF_Core_Document

Alias for getInitialDocument.

getDocumentByFilename()

public Merger::getDocumentByFilename (
string $filename,
bool $cache = true
): \SetaPDF_Core_Document

Get a document instance by a filename.

Parameters
$filename : string

The filename

$cache : bool

Cache the document by filename

Exceptions

Throws Exception

getInitialDocument()

public Merger::getInitialDocument (
void
): \SetaPDF_Core_Document

Returns the initial document.

See

getMaxFileHandler()

public Merger::getMaxFileHandler (
void
): ?\SetaPDF_Core_Reader_MaxFileHandler

Get the maximum file handler.

getPageCount()

public Merger::getPageCount (
string|\SetaPDF_Core_Document $filename,
bool $cacheDocumentInstance = true
): int

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 : bool

Cache the document instance or not

Exceptions

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

Throws \setasign\SetaPDF2\Core\Type\Exception

Throws Exception

merge()

public Merger::merge (
void
): \SetaPDF_Core_Document

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 \setasign\SetaPDF2\Core\Exception

Throws \setasign\SetaPDF2\Core\SecHandler\Exception

Throws \setasign\SetaPDF2\Core\Type\Exception

Throws Exception

Throws \Exception

rewriteStringNamesCallback()

public Merger::rewriteStringNamesCallback (): void

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 Merger::setHandleNames (
bool $handleNames = true,
?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 : bool

The flag status

$adjustNameCallback : ?callback

See \setasign\SetaPDF2\Core\DataStructure\Tree\AbstractTree::merge() for a detailed description of the callback

setMaxFileHandler()

public Merger::setMaxFileHandler (): void

Set the maximum file handler.

Parameters
$handler : ?\SetaPDF_Core_Reader_MaxFileHandler
 

setRenameSameNamedFormFields()

public 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()

public Merger::setWriter (): void

Set the writer for the initial document.

Parameters
$writer : \SetaPDF_Core_Writer_WriterInterface

The writer instance

writeDictionaryCallback()

public Merger::writeDictionaryCallback (): void

Callback method for renaming values of renamed names.

Parameters
$document : \SetaPDF_Core_Document

The document instance

$dict : \SetaPDF_Core_Type_Dictionary

The dictionary

See

© 2025 Setasign GmbH & Co. KG · Contact / Imprint · Data Privacy Statement (German)