The leading German language PHP web site, PHPHatesMe.com has just published an article in German about Zend_Service_LiveDocx_MailMerge.

The text introduces the component library, explains the benefits of its template-based approach and finally offers some sample applications, which illustrate the work-flow of applications, deploying LiveDocx for document generation.

Click on the following screenshot to read the full article.

Bremen, Germany (February 03, 2009) – Traditionally, the generation of professional looking PDF files with PHP has been a tricky programming task: A number of PHP libraries are available, which allow developers to either convert HTML documents to PDF or programmatically generate PDFs from scratch. Business documents created using the former approach are limited by the capabilities of HTML, while it is extremely tedious to get the layout of documents just right, for those, which are generated using the latter approach.

phpLiveDocx offers a solution to both these problems: Templates, which are created in a WYSIWYG environment (such as a standard word processor) are populated with structured data from PHP. The resulting document can be saved as a PDF, DOCX, DOC or RTF file. The concept is the same as with mail-merge.

The benefits to an enterprise are numerous:

• phpLiveDocx separates template and programming logic, thus a graphic designer can produce the template, while a developer can populate it. Additionally, changes to the layout of a template can be made without any changes to the programming logic.

• Using phpLiveDocx, populating a template is simply a matter of assigning a value to a text field. When PDF templates are to be populated using existing solutions, the x and y coordinates of the position at which text should inserted must be specified. It is very time-consuming to calculate these coordinates and in some cases, not possible at all.

• phpLiveDocx is the PHP5 implementation of the SOAP web service LiveDocx. As such, it is not necessary that an administrator install any further software on the server, in order to use phpLiveDocx. The complex word processing and mail-merge processes take place on the backend platform. This not only lowers maintenance costs, but also reduces the hardware requirements of the client web server.

phpLiveDocx has been authored to fit the architecture of the Zend Framework and follows its extreme simplicity philosophy.

To learn more about phpLiveDocx, read the documentation and download a number of runnable sample applications, please take a look at this article.

If you would like to try out phpLiveDocx for yourself, please download the libraries and sample applications.

To set up an evaluation account for LiveDocx or discuss your individual requirements, please take a look at the official web site. phpLiveDocx is supported by an active community of developers, who are willing to address your specific needs.

• LiveDocx – official web site.
• phpLiveDocx – community implementation in PHP5.
• TX Text Control – technology that powers LiveDocx.

Please feel free to contact me, if you would like to talk about any aspect of phpLiveDocx.

The advantages of the phpLiveDocx method of document creation over the Zend_Pdf method are numerous:

• phpLiveDocx separates template and programming logic. A graphical designer can produce the template, while a developer can take care of populating it. Similarly, changes to the layout of a template can be made without any changes to the programming logic.

• Unlike with Zend_Pdf, in which a template must be painstakingly programmed, phpLiveDocx allows templates to be created in a true WYSIWYG environment, using Microsoft Word, Open Office or TX Template Designer.

• When populating PDF templates with Zend_Pdf, the x and y coordinates of the position at which text should written must be specified. It is very time-consuming to calculate these coordinates and in some cases, not possible at all. Zend_Pdf offers no concept of a text field. Using phpLiveDocx, populating a template is simply a matter of assigning a value to a text field.

• Using the Zend Framework in the current incarnation (v1.7.1), there is no way to create word processing documents in DOCX, DOC or RTF formats. phpLiveDocx makes these file formats available with one single parameter. Generating a DOCX file, for example, is exactly the same procedure as for a PDF.

• The backend service to phpLiveDocx – LiveDocx – is authored by the manufacturer of TX Text Control, a company, which has around 20 years experience in the production of quality word processing components. Customers of LiveDocx are entitled to free telephone and e-mail support.

The manufacturer of the celebrated word processing component TX Text Control has recently brought to market a document creation platform, which provides a very elegant solution to the programmatic creation of well-formatted word processing documents in PDF, DOCX, DOC and RTF formats. The platform, which is SOAP based and hence completely independent of any specific programming language, is called LiveDocx.

The PHP community has put together a PHP5 implementation, called phpLiveDocx, which is released under the New BSD License and can be downloaded from the downloads section of this blog.

The idea of phpLiveDocx is really simple: Indeed, it embodies the extreme simplicity philosophy of the Zend Framework, for which the component has been designed. Using phpLiveDocx, a graphical designer can create a template in Microsoft Word, Open Office or a specialized tool, called TX Template Designer. In the template, s/he can embed any number of text fields, into which, in a second step, data can be populated using phpLiveDocx. The resulting word processing document can be saved as a PDF, DOCX, DOC or RTF file.

Consider the following diagram – it explains the flow of data in a phpLiveDocx application:

The green shape to the left symbolizes a template. The dark blue shape directly beneath symbolizes arbitrary data (in this case, textual data from an XML file). The cloud in the center of the diagram is the LiveDocx service. The resulting document (in this case a very short letter) is symbolized by the light blue shape to the right.

Or, expressed as PHP5 code:

1
2
3
4
5
6
7
8
9
10
11
12
13

$mailMerge = new Zend_Service_LiveDocx_MailMerge();
 
$mailMerge->setUsername('myUsername')
          ->setPassword('myPassword');
 
$mailMerge->setLocalTemplate('template.docx');
 
$mailMerge->assign('firstname', 'Peter');
$mailMerge->assign('user', 'Jacky Hewitt');
 
$mailMerge->createDocument();
 
$document = $mailMerge->retrieveDocument('pdf');

The resulting word processing document, as a PDF file, is stored in the variable $document. Simply by passing docx, doc or rtf, it would have been equally possible to retrieve the document in another supported format.

Although the above example could have been implemented using Zend_Pdf – given that the developer has sufficient patience and time to get the positioning of the inserted text just right and that the output document is a PDF file – there are certain types of document formatting, which make the deployment of the Zend Framework component extremely tedious.

Consider the following template file, which is part of a software license agreement. Using this template, a software manufacturer can generate a license agreement for a specific software and licensee. The text fields are represented as %textFieldName%.

Agreement for %software% between %company% and %licensee%

Subject of agreement
The subject of this agreement is the software %software%, the operating manuals, online help files and all other accompanying material. It will be referred to henceforth as %software%.

Grant of license
%company% grants %licensee% a non-exclusive, non-transferable, personal and worldwide license to use one copy of %software% in the development of an end-user application, as described in section 3 (below). This license is for a single developer and not for an entire company. If additional programmers wish to use %software%, additional copies must be licensed.

In this template, there is the additional problem that it is impossible to know in advance exactly at which coordinates text should be inserted. The position of the text fields depends upon the length of the content in the previous text field. In the title of the agreement, for example, the value for %company% must be inserted at two entirely different coordinates, if %software% has the value Ace Downloader or Magical Compression Suite Deluxe Edition Pro. The resulting documents would look as follows:

Agreement for Ace Downloader between MegaSoft Corp and Peter Paul

and

Agreement for Magical Compress Suite Deluxe Edition Pro between MegaSoft Corp and Peter Paul

As the name of the first software has only 14 characters, %company% appears on the first line, whereas in the second example, %software% has 44 characters, hence pushing the second and third text field onto the next line.

Using phpLiveDocx, the developer does not have to worry about the plethora of possible layout and formatting options in a word processing document. All s/he needs to know is the names of the text fields. phpLiveDocx has been designed from the ground up to make the creation of word processing documents a pain-free process, thus increasing the productivity of the developer.

Towards the middle of the Ralf’s article in PHP Magazin, in a section which talks about how to populate PDF templates, the author expresses some concern about how tricky it is to get the positioning of pseudo text fields just right in a PDF template (an English translation of this passage is directly after the quotation):

In der Regel werden die PDF-Vorlagen verwendet, um am bestimmten Stellen im Dokument variable Inhalte einzufügen. Da Zend_Pdf intern mit Punkten (1/72 eines Inches) arbeitet, kann die Platzierung von Texten mit PDF-Vorlagen aus anderem Quellen durchaus problematisch werden.

Ich habe diese einmal mit deiner PDF-Vorlage umsetzen müssen, die die zu füllenden Textfelder nicht nach Punkten, sondern eher wahllos auf der Seite verteilt hatte. Es kann schon bei einer Vorlage, die nur aus einer DIN-A4-Seite besteht, aber 20 bis 30 Felder hat, die es zu befühlen gilt, ein paar Stunden dauern, bis man alle Texte einigermaßen gut platziert hat. Der Begriff “Pixelschubser” bekommt da eine ganz neue Bedeutung.

The above quotation can be translated into English as follows:

Typically, PDF templates are used to insert content into documents at pre-defined positions. As Zend_Pdf internally uses points (1/72 of an inch), it can be tricky to get the positioning of text just right in PDF templates originating from sources other than the Zend Framework.

Once I had the task of programmatically populating a PDF template in which text fields were not specified in points, but were rather haphazardly placed all over the page. It can take several hours until you get the positioning of text just right in an A4 document with 20 to 30 text fields. The term “pixel-pimping” takes on a completely new meaning.

To illustrate how the population of PDF templates works with the Zend Framework, Ralf presents an example, which is available on the cover DVD of the magazine or can be downloaded. The logic is as follows:

1. Load a PDF file with Zend_Pdf.
2. Loop through each piece of text, which should be inserted into the template and specify its x and y coordinates, using the drawText() method. For example:

   $page->drawText('Henry', 200, 620);

3. Render and save the PDF file.

The problem here, is that with Zend_Pdf, there is no concept of a text field. For example, it is not possible to specify that a placeholder is called firstName and then programmatically set the value of firstName to say Henry. Instead, it is necessary to specify that at position 200, 620 Henry should be written. It is therefore, very understandable when Ralf writes: The term “pixel-pimping” takes on a completely new meaning.

For each an every piece of text, which should be inserted into a document, exact coordinates must be specified – a very time consuming, nerve-wracking and consequently error prone task.

Furthermore, to be able to use Zend_Pdf at all, the exact coordinates at which text should be inserted must be known in advance. For example, should the graphical design department change the design of say an invoice, then a programmer must update his/her code in the PDF generation process, re-specifying coordinates as applicable. This makes Zend_Pdf a very brittle solution: One small change in the PDF template and the generated PDF document is broken.

In a similar vein, many legacy word processing documents are not stored as PDF files at all. In a typical office environment, the vast majority of documents are stored in DOC and more currently, DOCX formats. These documents often contain text fields (or merge fields, as they are called by Microsoft), into which data can be injected. In the current incarnation of the Zend Framework (v1.7.1) there is no provision whatsoever to load these file formats, let alone populate them with data from disparate data sources.

In the December 2008 – January 2009 issue of the German language magazine PHP Magazin, a five page article by Ralf Eggert was published, in which he discusses the Zend Framework component Zend_Pdf.

In the following four blog posts, I would like to present an alternative and considerably easier way of document generation with the Zend Framework.

1. Document generation with Zend_Pdf
2. Introducing a more elegant solution
3. Advantages of phpLiveDocx over Zend_Pdf
4. Try phpLiveDocx out today!