mergeDocx

mergeDocx

ADVANCED / PREMIUM TRIAL

Merges Word documents.

Description
public mergeDocx (string $firstDocument, array $documentArray, string $finalDocument, array $options)

This method allows the full merging of DOCX documents.

The merging process preserves all contents without internal/external dependencies: paragraphs, tables, bookmarks, run-of-text, text boxes, fields, shapes...

The merging process also preserves the following contents that include internal/external dependencies:

  • styles
  • images
  • charts
  • links and cross-references
  • lists
  • altChunk contents
  • footnotes and endnotes
  • comments
  • OLE objects
  • sections with their corresponding headers and footers (optional)

The mergeDocx method works in the same way as MS Word: a DOCX can only have one default style of each type (paragraph, table, character...) and one custom style of each type with the same name.

When mergeDocx runs with the default options, the styles from the first DOCX are used as initial styles and only the style names from the next DOCX to be merged that don't exist in the styles of the first DOCX will be added to the styles content file of the merged output. So, if the same custom style name exists in both the first and the second DOCX, only the first one will be added to the styles.xml. Setting the forceLatestStyles option as true changes this behaviour and the styles from the last DOCX to be merged are used instead of the first DOCX.

This functionality is the same as MS Word. E.g., let's suppose that the Normal custom paragraph style in MS Word is changed. Then a new text with this custom paragraph style is created. Finally the content is copied to another DOCX that has contents that use a custom paragraph style with the same name. As a result, all contents with that custom style will use the same styles. In order to apply other styles for the content copied, it is necessary to create a style with its own, different name.

As styles with the same name than the existing ones aren't added from the next DOCX to be merged, the best approach is creating unique custom style names for the documents to be merged. This can be done with MS Word (LibreOffice or any other DOCX program) if the DOCX is generated using any of these programs or the methods included with phpdocx (such as createParagraphStyle) if the library is used to create the DOCX.

This default behaviour can be changed enabling the renameStyles option, that rename the styles of the DOCX to be merged with unique names to keep them in the final output.

Parameters

firstDocument

The path to the first Word document to merge.

documentArray

Paths array of the Word documents to merge.

finalDocument

The destination path of the merged file.

options

The possible keys and values are (required options are shown with yellow background):

Key Type Description
mergeType int

The possible values are:

  • 0: preserves the sections of the merged document with their respective headers and footers.
  • 1: merges the contents at the end of the last section of the first document.

If the mergeType equals 1 or the last section of the first document is of the "continuous" type, there may be some missalignment of absolutely positioned content in the merged document. This is due to the fact that the absolute positioned content of the second document was layed out with respect the second document page distribution that may change after the merging.

enforceSectionPageBreak bool Enforces a page section break between documents even if the first section type of the merged document is of the continuous type.
numbering string

The possible values are:

  • continue (the page numbering continues in the merged document).
  • restart (the original page numbering of the second document is preserved).

lineBreaks int Inserts the indicated number of line breaks between the contents of the merging files.
forceLatestStyles bool Keeps the last merged document styles, overwriting the previous styles.
renameStyles bool If true, rename styles of the DOCX to be merged with unique names to keep them. False as default.
importEmbeddedFonts bool If true, imports embedded fonts. False as default.
Exceptions

Error while trying to open the (base) template as a zip file.

Code samples

Example #1:

The resulting Word document looks like: