LVII. PDF functions

Introduction

You can use the PDF functions in PHP to create PDF files if you have the PDF library by Thomas Merz (available at http://www.pdflib.com/pdflib/index.html; you will also need the JPEG library and the TIFF library to compile this. These two librariess can often cause problems when configuring PHP, so be sure to pay attention to the output of the configure script and fix any problems it reports.

Please consult the documentation for PDFlib shipped with the source distribution of PDFlib. It provides a very good overview of what PDFlib is capable of doing and contains the full and most up-to-date description of all functions.

All of the functions in PDFlib and the PHP module have the same name. The parameters are also identical. You should also understand some of the concepts of PDF or PostScript to efficiently use this module. All lengths and coordinates are measured in PostScript points. There are generally 72 PostScript points to an inch, but this depends on the output resolution.

There is another PHP module for PDF document creation based on FastIO's. ClibPDF. It has a slightly different API. Check the ClibPDF functions section for details.

The PDF module introduces one new type of variable. It is called a pdf object and almost all functions need a pdf object as its first parameter.

Confusion with old PDFlib versions

Starting with PHP 4.0.5, the PHP extension for PDFlib is officially supported by PDFlib GmbH. This means that all the functions described in the PDFlib-manual (V3.00 or greater) are supported by PHP 4 with exactly the same meaning and the same parameters. Only the return values may differ from the PDFlib manual, because the PHP convention of returning false was adopted. For compatibility reasons this binding for PDFlib still supports the old functions, but as stated above they should be replaced by their new versions. PDFlib GmbH will not support any problems arising from the use of these deprecated functions.

Table 1. Deprecated functions and its replacements

Old functionReplacement
PDF_put_image()Not needed anymore.
PDF_execute_image()Not needed anymore.
PDF_get_annotation()PDF_get_bookmark() using the same parameters.
PDF_get_font()PDF_get_value() passing "font" as the second parameter.
PDF_get_fontsize()PDF_get_value() passing "fontsize" as the second parameter.
PDF_get_fontname()PDF_get_parameter() passing "fontname" as the second parameter.
PDF_set_info_creator()PDF_set_info() passing "Creator" as the second parameter.
PDF_set_info_title()PDF_set_info() passing "Title" as the second parameter.
PDF_set_info_subject()PDF_set_info() passing "Subject" as the second parameter.
PDF_set_info_author()PDF_set_info() passing "Author" as the second parameter.
PDF_set_info_keywords()PDF_set_info() passing "Keywords" as the second parameter.
PDF_set_leading()PDF_set_value() passing "leading" as the second parameter.
PDF_set_text_rendering()PDF_set_value() passing "textrendering" as the second parameter.
PDF_set_text_rise()PDF_set_value() passing "textrise" as the second parameter.
PDF_set_horiz_scaling()PDF_set_value() passing "horizscaling" as the second parameter.
PDF_set_text_matrix()Not available anymore
PDF_set_char_spacing()PDF_set_value() passing "charspacing" as the second parameter.
PDF_set_word_spacing()PDF_set_value() passing "wordspacing" as the second parameter.
PDF_set_transition()PDF_set_parameter() passing "transition" as the second parameter.
PDF_open()PDF_new() plus an subsequent call of PDF_open_file()
PDF_set_font()PDF_findfont() plus an subsequent call of PDF_setfont()
PDF_set_duration()PDF_set_value() passing "duration" as the second parameter.
PDF_open_gif()PDF_open_image_file() passing "gif" as the second parameter.
PDF_open_jpeg()PDF_open_image_file() passing "jpeg" as the second parameter.
PDF_open_tiff()PDF_open_image_file() passing "tiff" as the second parameter.
PDF_open_png()PDF_open_image_file() passing "png" as the second parameter.
PDF_get_image_width()PDF_get_value() passing "imagewidth" as the second parameter and the image as the third parameter.
PDF_get_image_height()PDF_get_value() passing "imageheight" as the second parameter and the image as the third parameter.
()()

Hints for installation of PDFlib 3.x

Since version 3.0 of PDFlib you should configure PDFlib with the option --enable-shared-pdflib.

Issues with older versions of PDFlib

Any version of PHP 4 after March 9, 2000 does not support versions of PDFlib older than 3.0.

PDFlib 3.0 or greater is also supported by PHP 3.0.19 and later.

Examples

Most of the functions are fairly easy to use. The most difficult part is probably creating a very simple PDF document at all. The following example should help to get started. It creates test.pdf with one page. The page contains the text "Times Roman outlined" in an outlined, 30pt font. The text is also underlined.

Example 1. Creating a PDF document with PDFlib


<?php
$pdf = PDF_new();
PDF_open_file($pdf, "test.pdf");
PDF_set_info($pdf, "Author", "Uwe Steinmann");
PDF_set_info($pdf, "Title", "Test for PHP wrapper of PDFlib 2.0");
PDF_set_info($pdf, "Creator", "See Author");
PDF_set_info($pdf, "Subject", "Testing");
PDF_begin_page($pdf, 595, 842);
PDF_add_outline($pdf, "Page 1");
PDF_set_font($pdf, "Times-Roman", 30, "host");
PDF_set_value($pdf, "textrendering", 1);
PDF_show_xy($pdf, "Times Roman outlined", 50, 750);
PDF_moveto($pdf, 50, 740);
PDF_lineto($pdf, 330, 740);
PDF_stroke($pdf);
PDF_end_page($pdf);
PDF_close($pdf);
PDF_delete($pdf);
echo "<A HREF=getpdf.php>finished</A>";
?>
      

The script getpdf.php just returns the pdf document.


<?php
$len = filesize($filename);
header("Content-type: application/pdf");
header("Content-Length: $len");
header("Content-Disposition: inline; filename=foo.pdf");
readfile($filename);
?>
       

The PDFlib distribution contains a more complex example which creates a page with an analog clock. Here we use the in memory creation feature of PDFlib, so we don't need any tmp-files. This example converted into PHP using PDFlib looks as the following (you can see the same example in the documentation for the clibpdf module):

Example 2. pdfclock example from PDFlib distribution


<?php
$radius = 200;
$margin = 20;
$pagecount = 10;

$pdf = PDF_new();

if (!PDF_open_file($pdf, "")) {
    print error;
    exit;
};

PDF_set_parameter($pdf, "warning", "true");

PDF_set_info($pdf, "Creator", "pdf_clock.php");
PDF_set_info($pdf, "Author", "Uwe Steinmann");
PDF_set_info($pdf, "Title", "Analog Clock");

while($pagecount-- > 0) {
    PDF_begin_page($pdf, 2 * ($radius + $margin), 2 * ($radius + $margin));

    PDF_set_parameter($pdf, "transition", "wipe");
    PDF_set_value($pdf, "duration", 0.5);
  
    PDF_translate($pdf, $radius + $margin, $radius + $margin);
    PDF_save($pdf);
    PDF_setrgbcolor($pdf, 0.0, 0.0, 1.0);

    /* minute strokes */
    PDF_setlinewidth($pdf, 2.0);
    for ($alpha = 0; $alpha < 360; $alpha += 6) {
        PDF_rotate($pdf, 6.0);
        PDF_moveto($pdf, $radius, 0.0);
        PDF_lineto($pdf, $radius-$margin/3, 0.0);
        PDF_stroke($pdf);
    }

    PDF_restore($pdf);
    PDF_save($pdf);

    /* 5 minute strokes */
    PDF_setlinewidth($pdf, 3.0);
    for ($alpha = 0; $alpha < 360; $alpha += 30) { 
        PDF_rotate($pdf, 30.0);
        PDF_moveto($pdf, $radius, 0.0);
        PDF_lineto($pdf, $radius-$margin, 0.0);
        PDF_stroke($pdf);
    }

    $ltime = getdate();

    /* draw hour hand */
    PDF_save($pdf);
    PDF_rotate($pdf,-(($ltime['minutes']/60.0)+$ltime['hours']-3.0)*30.0);
    PDF_moveto($pdf, -$radius/10, -$radius/20);
    PDF_lineto($pdf, $radius/2, 0.0);
    PDF_lineto($pdf, -$radius/10, $radius/20);
    PDF_closepath($pdf);
    PDF_fill($pdf);
    PDF_restore($pdf);

    /* draw minute hand */
    PDF_save($pdf);
    PDF_rotate($pdf,-(($ltime['seconds']/60.0)+$ltime['minutes']-15.0)*6.0);
    PDF_moveto($pdf, -$radius/10, -$radius/20);
    PDF_lineto($pdf, $radius * 0.8, 0.0);
    PDF_lineto($pdf, -$radius/10, $radius/20);
    PDF_closepath($pdf);
    PDF_fill($pdf);
    PDF_restore($pdf);

    /* draw second hand */
    PDF_setrgbcolor($pdf, 1.0, 0.0, 0.0);
    PDF_setlinewidth($pdf, 2);
    PDF_save($pdf);
    PDF_rotate($pdf, -(($ltime['seconds'] - 15.0) * 6.0));
    PDF_moveto($pdf, -$radius/5, 0.0);
    PDF_lineto($pdf, $radius, 0.0);
    PDF_stroke($pdf);
    PDF_restore($pdf);

    /* draw little circle at center */
    PDF_circle($pdf, 0, 0, $radius/30);
    PDF_fill($pdf);

    PDF_restore($pdf);

    PDF_end_page($pdf);

    # to see some difference
    sleep(1);
}

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=foo.pdf");
print $buf;

PDF_delete($pdf);
?>
      

Table of Contents
PDF_add_annotation — Deprecated: Adds annotation
PDF_add_bookmark — Adds bookmark for current page
PDF_add_launchlink — Add a launch annotation for current page
PDF_add_locallink — Add a link annotation for current page
PDF_add_note — Add a note annotation for current page
pdf_add_outline — Deprecated: Adds bookmark for current page
PDF_add_pdflink — Adds file link annotation for current page
PDF_add_thumbnail — Adds thumbnail for current page
PDF_add_weblink — Adds weblink for current page
PDF_arc — Draws an arc
PDF_arcn — Draws an arc
PDF_attach_file — Adds a file attachement for current page
PDF_begin_page — Starts new page
PDF_begin_pattern — Starts new pattern
PDF_begin_template — Starts new template
PDF_circle — Draws a circle
PDF_clip — Clips to current path
PDF_close — Closes a pdf object
PDF_closepath — Closes path
PDF_closepath_fill_stroke — Closes, fills and strokes current path
PDF_closepath_stroke — Closes path and draws line along path
PDF_close_image — Closes an image
PDF_close_pdi — Close the input PDF document
PDF_close_pdi_page — Close the page handle
PDF_concat — Concatenate a matrix to the CTM
PDF_continue_text — Outputs text in next line
PDF_curveto — Draws a curve
PDF_delete — Deletes a PDF object
PDF_end_page — Ends a page
PDF_endpath — Deprecated: Ends current path
PDF_end_pattern — Finish pattern
PDF_end_template — Finish template
PDF_fill — Fills current path
PDF_fill_stroke — Fills and strokes current path
PDF_findfont — Prepare font for later use with PDF_setfont().
PDF_get_buffer — Fetch the buffer containig the generated PDF data.
PDF_get_font — Deprecated: font handling
PDF_get_fontname — Deprecated: font handling
PDF_get_fontsize — Deprecated: font handling
PDF_get_image_height — Returns height of an image
PDF_get_image_width — Returns width of an image
PDF_get_parameter — Gets certain parameters
PDF_get_pdi_parameter — Get some PDI string parameters
PDF_get_pdi_value — Gets some PDI numerical parameters
PDF_get_value — Gets certain numerical value
PDF_initgraphics — Resets graphic state
PDF_lineto — Draws a line
PDF_makespotcolor — Makes a spotcolor
PDF_moveto — Sets current point
PDF_new — Creates a new pdf object
pdf_open — Deprecated: Open a new pdf object
PDF_open_CCITT — Opens a new image file with raw CCITT data
PDF_open_file — Opens a new pdf object
PDF_open_gif — Deprecated: Opens a GIF image
PDF_open_image — Versatile function for images
PDF_open_image_file — Reads an image from a file
PDF_open_jpeg — Deprecated: Opens a JPEG image
PDF_open_pdi — Opens a PDF file
PDF_open_pdi_page — Prepare a page
PDF_open_png — Deprecated: Opens a PNG image
PDF_open_tiff — Deprecated: Opens a TIFF image
PDF_place_image — Places an image on the page
PDF_place_pdi_page — Places an image on the page
PDF_rect — Draws a rectangle
PDF_restore — Restores formerly saved environment
PDF_rotate — Sets rotation
PDF_save — Saves the current environment
PDF_scale — Sets scaling
PDF_setcolor — Sets fill and stroke color to CMYK values
PDF_setdash — Sets dash pattern
PDF_setflat — Sets flatness
PDF_setfont — Set the current font
PDF_setgray — Sets drawing and filling color to gray value
PDF_setgray_fill — Sets filling color to gray value
PDF_setgray_stroke — Sets drawing color to gray value
PDF_setlinecap — Sets linecap parameter
PDF_setlinejoin — Sets linejoin parameter
PDF_setlinewidth — Sets line width
PDF_setmatrix — Sets current transformation matrix
PDF_setmiterlimit — Sets miter limit
PDF_setpolydash — Sets complicated dash pattern
PDF_setrgbcolor — Sets drawing and filling color to rgb color value
PDF_setrgbcolor_fill — Sets filling color to rgb color value
PDF_setrgbcolor_stroke — Sets drawing color to rgb color value
PDF_set_border_color — Sets color of border around links and annotations
PDF_set_border_dash — Sets dash style of border around links and annotations
PDF_set_border_style — Sets style of border around links and annotations
PDF_set_char_spacing — Deprecated: Sets character spacing
pdf_set_duration — Deprecated: Sets duration between pages
PDF_set_font — Deprecated: Selects a font face and size
PDF_set_horiz_scaling — Sets horizontal scaling of text
PDF_set_info — Fills a field of the document information
PDF_set_leading — Deprecated: Sets distance between text lines
PDF_set_parameter — Sets certain parameters
PDF_set_text_pos — Sets text position
PDF_set_text_rendering — Deprecated: Determines how text is rendered
pdf_set_text_rise — Deprecated: Sets the text rise
pdf_set_text_matrix — Deprecated: Sets the text matrix
PDF_set_value — Sets certain numerical value
pdf_set_word_spacing — Depriciated: Sets spacing between words
PDF_show — Output text at current position
PDF_show_boxed — Output text in a box
PDF_show_xy — Output text at given position
PDF_skew — Skews the coordinate system
PDF_stringwidth — Returns width of text using current font
PDF_stroke — Draws line along path
PDF_translate — Sets origin of coordinate system
PDF_open_memory_image — Opens an image created with PHP's image functions