|Classes of Christian Vigh||PHP RTF Tools||help/README.merger.md||Download|
The RtfMerger class allows you to combine the contents of several Rtf files into a single one. It can be used for mass printing or for storing a set of related files into a single archive.
Unlike all the other classes of this package that process Rtf contents, this class does not inherit from RtfDocument.
Merging Rtf files is fairly simple ; first, create a instance of the RtfMerger class ; you can supply a list of files to be merged together, or add them later by calling the Add() method :
The above example specified the names of the files to be merged ; but you can also give instances of the RtfDocument class, such as in the example below :
So you can see that you can specify both strings (filenames) and objects inheriting from the RtfDocument class ; however, the way strings are handled can be modified. You can tell for example that every string specified either to the class constructor or to the Add() method should be considered as pure Rtf contents, instead of being seen as a file name. This can be done by specifying the RtfMerger::RTFMERGE\_STRINGS\_AS\_DATA option to the constructor, or by setting the Options property :
Other version :
Now, every data you will add as a string will be considered as Rtf data, not as a filename :
To save merged contents to a file, you can use the SaveTo() method :
or you can get the merged contents as a string, provided you are sure that everything will fit into memory :
The following paragraphs describe the methods and properties available in the RtfMerger class.
Basically, you can specify the documents to be merged when invoking the constructor or the Add() method. Nothing will happen until you call either the SaveTo() or AsString() methods.
This means that you can add as many documents as you like before merging them ; this will have a very little impact on the available memory if you are using document objects inheriting from the RtfFileDocument class.
To avoid memory exhaustion when you have many big documents to be merged together, the preferred solution will be to use document objects of class RtfFileDocument or RtfFileTemplater (if you use template).
The constructor has the following signature :
Every $doc parameter can be either an object inheriting from the RtfDocument class, or the path of an Rtf file, or direct Rtf contents (see the Add() method for an explanation).
The $options parameter specifies whether the strings specified to the constructor or the Add() method should be considered as filenames or Rtf contents (see the Options property for further explanations on this parameter).
The order of the parameters has no importance.
$merger -> Add ( $document )
Adds a document to the list of documents to be merged.
The specified document can be either an object inheriting from the RtfDocument base class, or a string.
In the latter case, the string will be interpreted differently depending on the bits set in the Options property :
$merger -> AsString ( )
Returns the merged contents of all the documents that have been added either through the class constructor or the Add() method.
$merger -> SaveTo ( $filename )
Saves the merged contents of all the documents that have been added either through the class constructor or the Add() method to the specified filename.
A combination of the following flags :
When nothing is specified, the RTFMERGE\_STRINGS\_AS\_FILENAMES flag is the default option.
A string containing Rtf code to be used to separate each document being merged. The default string is :
which creates a new section (hence a page break). Note that the are not necessary ; they just put a line break in the Rtf source code, which could help you to identify document separator if you are editing the merged document using a text editor such as Notepad.
To put a line break between each merged document, just do the following :
To simply catenate Rtf documents without any separation, set the DocumentSeparator property to the empty string :
Document information properties
Each individual document to be merged contains its own set of information ; this can be for example the author name, the document title, some comments or keywords to be associated with the document, and so on.
It will not be possible to merge all this information coming from multiple documents to be merged ; this is why the following set of properties can be defined before the final document is generated (if not specified, they will not appear in the merged contents) :
Note that none of the above information will be included in the generated merge file if you do not explicitly specify them.