Documents and Pages (Programming PHP)

10.2. Documents and Pages

A PHP document is made up of a number of pages. Each page contains text and/or images. This section shows you how to make a document, create pages in that document, put text onto the pages, and send the pages back to the browser when you're done.

10.2.1. A Simple Example

Let's start with a simple PDF document. Example 10-1 simply places "Hello world!" on a page and then displays the resulting PDF document.

Example 10-1. Hello world in PDF

<?php 
 $pdf = pdf_new( ); 
 pdf_open_file($pdf);
 pdf_set_info($pdf,'Creator','hello.php'); 
 pdf_set_info($pdf,'Author','Rasmus Lerdorf'); 
 pdf_set_info($pdf,'Title','Hello world (PHP)'); 
 pdf_begin_page($pdf,612,792); 

 $font = pdf_findfont($pdf,'Helvetica-Bold','host',0);        
 pdf_setfont($pdf,$font,38.0); 
 pdf_show_xy($pdf,'Hello world!',50,700);

 pdf_end_page($pdf); 
 pdf_set_parameter($pdf, "openaction", "fitpage");
 pdf_close($pdf); 

 $buf = pdf_get_buffer($pdf); 
 $len = strlen($buf);
 header('Content-Type: application/pdf');
 header("Content-Length: $len");
 header('Content-Disposition: inline; filename=hello.pdf');
 echo $buf;
 pdf_delete($pdf);
?>

Example 10-1 follows the basic steps involved in creating a PDF document: creating a new document, setting some metadata for the document, creating a page, and writing text to the page. Figure 10-1 shows the output of Example 10-1.

Figure 10-1. Hello world in a PDF document

10.2.2. Initializing the Document

In Example 10-1, we started by calling pdf_new( ), to create a new PDF data structure, followed by pdf_open_file( ) , to open a new document. pdf_open_file( ) takes an optional second argument that, when set, specifies the filename to which to write the PDF data:

pdf_open_file(pdf [, filename ]);

The output of pdf_open_file( ) is sent to stdout if the filename is "-". If no filename argument is provided, the PDF data is written to a memory buffer, which can later be fetched by calling pdf_get_buffer( ). The latter approach is the one we used in Example 10-1.

10.2.3. Setting Metadata

The pdf_set_info( ) function inserts information fields into the PDF file:

pdf_set_info(pdf, fieldname, value);

There are five standard field names: Subject, Author, Title, Creator, and Keywords. You can also add arbitrary information fields, as we did in Example 10-1.

In addition to informational fields, the pdflib library has various parameters that you can change with pdf_get_parameter( ) and pdf_set_parameter( ):

$value = pdf_get_parameter(pdf, name);
pdf_set_parameter(pdf, name, value);

A useful parameter to set is openaction, which lets you specify the zoom (magnification) of the file when it's opened. The values "fitpage", "fitwidth", and "fitheight" fit the file to the complete page, the width of the page, and the height of the page, respectively. If you don't set openaction, your document is displayed at whatever zoom the viewer had set at the time the document was opened.

10.2.4. Creating a Page

A page starts with a call to pdf_begin_page( ) and ends with a call to pdf_end_page( ):

pdf_end_page(pdf);

You specify the paper size in points in the call to pdf_begin_page( ). Table 10-1 shows some typical sizes.

Table 10-1. Paper sizes

Page format	Width	Height
US-Letter	612	792
US-Legal	612	1008
US-Ledger	1224	792
11 x 17	792	1224
A0	2380	3368
A1	1684	2380
A2	1190	1684
A3	842	1190
A4	595	842
A5	421	595
A6	297	421
B5	501	709

Here is some typical begin/end page code:

<?php
 pdf_begin_page($pdf, 612, 792);  // US-Letter
 // code to create actual page content would go here 
 pdf_end_page($pdf);
?>

10.2.5. Outputting Basic Text

To put text on a page, you must select the font you want to use, set the default font to be that font at a particular size, and then add the text. For example:

$font = pdf_findfont($pdf, "Times-Roman", "host", 0);
pdf_setfont($pdf, $font, 48);
pdf_show_xy($pdf, "Hello, World", 200, 200);

With PDF documents, the (0,0) coordinate indicates the bottom-left corner of the page. In later sections we'll examine the different aspects of fonts and text layout and explain these functions in detail.

10.2.6. Terminating and Streaming a PDF Document

Call pdf_close( ) to complete the PDF document. If no filename was provided in the pdf_open_file( ) call, you can now use the pdf_get_buffer( ) function to fetch the PDF buffer from memory. To send the file to the browser, you must send Content-Type, Content-Disposition, and Content-Length HTTP headers, as shown in Example 10-1. Finally, call pdf_delete( ) to free the PDF file once it's sent to the browser.