How dynamic PDFs can help you
When I found out that dynamic PDFs could be created in PHP, my first thought was: “That’s great, but what can dynamic PDF files actually do for me?” As far as I was concerned, PDF support was more trouble than it was worth.
However, as I started playing with the PDF support in PHP, I soon realized that there are all sorts of ways that I could use the PDF features of PHP to make my Web sites (and even my business) more efficient.
For instance, by scanning already existing documents into a PDF form, you can then create a PHP script that fills in all of the information on the form perfectly, which either the user (or you) can print quickly and easily.
This is particularly useful for organizations that already have established means for processing documents through the conventional paper format, but want to also take advantage of the Internet. With the help of PHP, an organization can take information online from the user without requiring any changes in how the forms are processed.
How PHP creates/modifies PDF files
PHP creates PDF files through the help of Thomas Merz’s PDFlib. There are over 100 different PDF functions available to you that allow you to control nearly every aspect of the PDF file you are working with. Because of the wealth of functions PHP supports when dealing with PDF files, I can only introduce you to the fundamentals of creating a PHP file dynamically in PHP. This process of creating a basic PDF file can be broken down into seven steps:
- Create / Open the PDF file
- Insert the Document information into the PDF (document title, author, etc.)
- Create a page
- Output Content of the page
- End the page
- Close the PDF
- Output the PDF
- Clean up
Note that steps three through five can be repeated a necessary and that this is a very rough outline of the steps taken into creating a full-fledged PDF document. This outline is only provided to introduce you to the steps required and each step will be discussed in more detail in the next section.
Note: Because of the sheer number of PDF functions available in PHP, it is recommended that you consult the PHP manual for details regarding the complete list of abilities PHP has when dealing with PDF documents.
Step 1 – Creating/Opening the PDF file
PDF files can either be created or opened from within PHP. We’ll start by creating a new PDF object using the
PDF_new() function and then instruct PHP to create a new PDF document by using the
PDF_open_file() function. The syntax for these functions is:
$var = PDF_new();
int PDF_open_file(<pdf object>, [filename]);
$var represents the variable to store the PDF object reference (to be used in the next function in place of
<pdf object>) and
[filename] represents an optional parameter specifying an already existing PDF file to open. If no filename is specified, then a new PDF document is created.
$pdf = PDF_new();
Step 2 – Setting Document information
Now that we have started our PDF file, the next step is to fill in the PDF document information (author, title, creator, subject, etc). This is done through the
PDF_set_info() function. The syntax for
PDF_set_info(<pdf_object>, <property string>, <value>);
<property string> represents the property title (such as “author”) and
<value> represents the value to set the particular property.
PDF_set_info($pdf, "author", "John Coggeshall");
PDF_set_info($pdf, "title", "Zend.com Example");
PDF_set_info($pdf, "creator", "Zend.com");
PDF_set_info($pdf, "subject", "Code Gallery Spotlight");
Step 3 – Creating a page in the PDF document
Now that we have opened the PDF file and set the document information, the next step is to create a page in the document. This is done through the use of the
PDF_begin_page() function. The syntax for
PDF_begin_page(<pdf object>, <page width>, <page height>);
<page width> and
<page height> are the page width and height (in postscript points). In our example, we’ll create a square page with a width and height of 450 points (about 6 and a quarter inches):
What is a Postscript point?
Postscript points represent 1/72 of a printed inch. The reason the PDF format uses these so-called “postscript points” rather than pixels is that a pixel cannot be cut in half (there is no “a half pixel”), while postscript points can be cut in half (1/144th of an inch). Although some PDF rendering devices can distort this measurement by assuming 1 point equals 1 pixel, the 72 points per inch conversion hold true for all hard copy.
Step 4 – Output the page content
At this point, we are finally ready to output the content to our PDF document. This process can range from extremely simple to extremely complex depending on the nature of the document.
For our example, we’ll be simply setting our font and outputting a single line of text mid-page. In order to accomplish this, we need to first find an acceptable font (using
PDF_setfont()) and then output the string to the PDF document using
Getting ready to use a font
In order for a font to be used from within a PDF document, it first must be initialized through the use of the
PDF_findfont() function. The syntax for
PDF_findfont() is a follows:
int PDF_findfont(<pdf object>, <fontname>, <encoding>,<embed>)
<fontname> is the string name of the font,
<encoding> represents the encoding type to be used (“builtin”, “macroman”, “Winans”, or “host”) and
<embed> represents a Boolean determining if the specified font should be embedded within the PDF document. Embedding of the font within the document is only necessary for the 14 fonts that do not exist in the PDF definition. The 14 fonts that can be safely used without being embedded are:
- Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique
- Helvetica, Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique
- Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic
- Symbol, ZapfDingbats
If the desired typeface does not exist in the above list, it must be embedded into the document to be rendered properly.
Using the Font
Once a font has been initialized, the font can be set as the current “brush” (or the typeface that text will be rendered in). Setting the current font to be used in the PDF document can be done through the use of the
PDF_setfont() function. The syntax for
PDF_setfont(<pdf object>, <font id>, <size>);
<font id> represents the font handle returned from
<size> is the size to render the font at.
Now that you have initialized and selected font, the next logical step is to use the font in the PDF document. This can be done a number of ways, but you will be using the
PDF_show_xy() in today’s discussion. As the name implies,
PDF_show_xy() allows you to output text starting at a specific x-y coordinate in the document. The syntax for
PDF_show_xy(<pdf object>, <string>, <x value>, <y value>);
<string> the parameter represents the text to output at the coordinate represented by
<x value> and
PDF_show_xy($pdf, "Hello, Dynamic PDFs!", 5, 225);
…which, in the example PDF document we are creating would output the string “Hello, Dynamic PDFs!” 5 points from the left edge of the document halfway down the page (450 / 2 = 225)
Step 5 – Ending the Page
Once you have completed a page, the next step is to signify that we are done with the current page by calling
PDF_end_page() in the following fashion…
<pdf object> represents the handle to the PDF object as in the previous examples.
Step 6 – Closing the PDF file
After you have completed your PDF creation process (as stated earlier, steps three through five can be repeated as necessary) the next step is to close the PDF file.
Closing the PDF file does not mean that the file will be outputted (or saved) but rather simply means you are finished compiling your PDF document. At this point, PHP will finalize the document, release any resources (such as fonts initialized), and ready it to be outputted. This task is accomplished by calling the
PDF_close() a function which has the following syntax…
<pdf object> again represents the handle to the PDF object as in the previous examples.
Step 7 – Outputting the PDF file (Getting the buffer)
At this point, you have created a complete PDF document that is ready to be displayed to the user or stored in the file system. The next question is how to get the data that comprises the PDF file itself. The answer lies in the next PDF function I’ll introduce,
As the name implies,
PDF_get_buffer() is used to retrieve the contents of the buffer for a given PDF object in PHP. This buffer (because of all the steps taken prior to this) contains the complete PDF “file” that can be either directly written to the file system using the standard PHP calls, or outputted to the browser through the use of appropriate headers and an echo statement.
Today, I will only discuss outputting the PDF file directly from the buffer to the browser. However, if you are more interested in saving the PDF file to the file system, I will point out where how and where the file output should take place.
Now let’s look at the syntax for
$var = PDF_get_buffer(<pdf object>);
$var represents the variable to store the contents of the PDF buffer and
<pdf object> is our very familiar handle to the PDF object.
Outputting the Buffer to the browser
Now that you have the complete PDF file in a PHP variable (
$buffer) we only need to send the file to the browser. Unfortunately, we cannot just be outputting the PDF file to the browser with an echo statement without first informing the browser the nature of the content we are sending.
This is done through the use of three separate headers in the following format…
Content-Disposition: inline; filename=<filename>
<length> is replaced with the length of the PDF buffer and
<filename> is replaced with the filename to be given to the PDF once it is received by the browser (any valid filename will do, as long as it ends in .pdf). Once the headers have been sent only then can the contents of the PDF buffer be sent through a simple echo command?
header("Content-Disposition: inline; filename=zend.pdf");
Note: If you prefer to save the PDF file to the file system (or perhaps output the file to both the file system and browser) you can do so at this point simply by sending the complete contents of
$buffer to a file opened in binary-write mode.
Step 8 – Cleaning up
At this point, we are done with our PDF file and can safely delete it from memory through the use of the
That’s it! It may seem a little daunting, but in general, all PDFs are created in a similar way with only the content (steps two and four) and the output method (step seven) really changing.
As I’ve noted, there is much more that can be done using PHP to create dynamic PDF files. Not only can new PDF files be created, but previously created files can also be created and modified making the PHP support of the PDF format extremely useful in many circumstances.