Creating PDF Files in PHP

Article Publication Date: May 8, 2001
Article URL: http://www.zend.com/zend/spotlight/creatingpdfmay1.php

By John Coggeshall

About the Code Author
Introduction
How dynamic PDFs can help you
How PHP creates/modifies PDF files
Step 1 - Creating/Opening the PDF file
Step 2 - Setting Document information
Step 3 - Creating a page in the PDF document
Step 4 - Output the page content
Step 5 - Ending the Page
Step 6 - Closing the PDF file
Step 7 - Outputting the PDF file (Getting the buffer)
Step 8 - Cleaning up
Final Notes

About the Code Author

Hermawan Haryanto is a Web application developer with over six years of Web site development experience and provides Web application development services internationally. He holds the position of CEO in his company, www.WaroengKemang.com, where he is also the primary Web developer. His knowledge of Web development extends into PHP, MySQL, ASP, SQL Server and much more.
Introduction

The PDF (or portable document format) file is an amazingly versatile format for transferring what usually starts as a hard copy version of a document over the Internet. Many companies use the PDF format to transfer contracts, manuals, and other documents over the Internet without trying to convert them to HTML or changing the format of the document in any way.

In fact, the only real drawback to PDF files is that a special reader is required to view them -- but even that is free to download on the Internet. Today I'll show you how you can create PDF files in PHP dynamically with Hermawan Haryanto's submission, Save to PDF.
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 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 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]);

Where $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 a already existing PDF file to open. If no filename is specified, then a new PDF document is created.
<?php

$pdf = PDF_new();
PDF_open_file($pdf);

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

PDF_set_info(<pdf_object>, <property string>, <value>);

Where <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() is:

PDF_begin_page(<pdf object>, <page width>, <page height>);

Where <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):
PDF_begin_page($pdf, 450, 450);
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 because a pixel cannot be cut in half (there is no "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 holds 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_findfont() and PDF_setfont()) and then output the string to the PDF document using PDF_show_xy().
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>)

Where <fontname> is the string name of the font, <encoding> represents the encoding type to be used ("builtin", "macroman", "winansi", 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.
$font = PDF_findfont($pdf, "Helvetica-Bold", "winansi",0);
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() is...

PDF_setfont(<pdf object>, <font id>, <size>);

...where <font id> represents the font handle returned from PDF_findfont() and <size> is the size to render the font at.
PDF_setfont($pdf, $font, 12);
Outputting Text

Now that you have initialized and selected a 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 the 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() is...

PDF_show_xy(<pdf object>, <string>, <x value>, <y value>);

...where the <string> parameter represents the text to output at the coordinate represented by <x value> and <y value>.
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_end_page(<pdf object>);

...where the <pdf object> represents the handle to the PDF object as in the previous examples.
PDF_end_page($pdf);
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() function which has the following syntax...

PDF_close(<pdf object>)

...where the <pdf object> again represents the handle to the PDF object as in the previous examples.
PDF_close($pdf);
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, PDF_get_buffer().

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 the how and where the file output should take place.

Now let's look at the syntax for PDF_get_buffer():

$var = PDF_get_buffer(<pdf object>);

...where $var represents the variable to store the contents of the PDF buffer and <pdf object> is our very familiar handle to the PDF object.
$buffer = PDF_get_buffer($pdf);
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 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-type: application/pdf

Content-Length: <length>

Content-Disposition: inline; filename=<filename>

...where <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-type: application/pdf");
header("Content-Length: ".strlen($buffer));
header("Content-Disposition: inline; filename=zend.pdf");

echo $buffer

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 PDF_delete() function:
PDF_delete($pdf);
?>

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.
Final Notes

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.

If you are interested in reading more about how PHP can work with PDF files, consult the PHP manual on PDF support and experiment. As always, feel free to contact me at john@zend.com if you have any specific questions regarding today's discussion. Many thanks to Hermawan for his contribution to the Code Gallery and for today's Code Gallery Spotlight topic!
About John Coggeshall

John Coggeshall is a PHP consultant and author who started losing sleep over PHP around five years ago. Lately you'll find him losing sleep meeting deadlines for books or online columns on a wide range of PHP topics. You can find his work online at O'Reilly Networks onlamp.com and Zend Technologies, or at his website http://www.coggeshall.org/.

John has also contributed to WROX Press' Professional PHP4 Programming and is currently in the progress of writing the PHP Developer's Handbook published by Sams Publishing.
Originally Posted by Skylinux @ 2005-12-11 01:28:52

No Comments yet .....