CXXI. PDF Functions

Introduction

The PDF functions in PHP can create PDF files using the PDFlib library which was initially created by Thomas Merz and is now maintained by PDFlib GmbH.

The documentation in this section is only meant to be an overview of the available functions in the PDFlib library and should not be considered an exhaustive reference. For the full and detailed explanation of each function, consult the PDFlib Reference Manual which is included in all PDFlib packages distributed by PDFlib GmbH. It provides a very good overview of what PDFlib is capable of doing and contains the most up-to-date documentation of all functions.

For a jump start we urge you to take a look at the programming samples which are contained in all PDFlib distribution packages. These samples demonstrate basic text, vector, and graphics output as well as higher-level functions, such as the PDF import facility (PDI).

All of the functions in PDFlib and the PHP module have identical function names and parameters. Unless configured otherwise, 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. Please see the PDFlib Reference Manual included in the PDFlib distribution for a more thorough explanation of the coordinate system used.

With version 6, PDFlib offers an object-oriented API for PHP 5 in addition to the function-oriented API for PHP 4. The main difference is the following:

In PHP 4, first a PDF resource has to be retrieved with a function call like

$p = PDF_new().

This PDF resource is used as the first parameter in all further function calls, such as in

PDF_begin_document($p, "", "").

In PHP 5 however, a PDFlib object is created with

$p = new PDFlib().

This object offers all PDFlib API functions as methods, e.g. as with

$p->begin_document("", "").

In addition, exceptions have been introduced in PHP 5 which are supported by PDFlib 6 and later as well.

Please see the examples below for more information.

Note: If you're interested in alternative free PDF generators that do not utilize external PDF libraries, see this related FAQ.

Requirements

PDFlib Lite is available as open source. However, the PDFlib Lite license allows free use only under certain conditions. PDFlib Lite supports a subset of PDFlib's functionality; please see the PDFlib web site for details. The full version of PDFlib is available for download at http://www.pdflib.com/products/pdflib-family/, but requires that you purchase a license for commercial use.

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 4.0 or greater is supported by PHP 4.3.0 and later.

Installation

This PECL extension is not bundled with PHP. Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: http://pecl.php.net/package/pdflib.

To get these functions to work in PHP < 4.3.9, you have to compile PHP with --with-pdflib[=DIR]. DIR is the PDFlib base install directory, defaults to /usr/local.

Resource Types

PDF_new() creates a new PDFlib object required by most PDF functions.

Remarks about Deprecated PDFlib Functions

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 Reference Manual are supported by PHP 4 with exactly the same meaning and the same parameters. However, with PDFlib Version 5.0.4 or higher all parameters have to be specified. For compatibility reasons, this binding for PDFlib still supports most of the deprecated functions, but they should be replaced by their new versions. PDFlib GmbH will not support any problems arising from the use of these deprecated functions. The documentation in this section indicates old functions as "Deprecated" and gives the replacement function to be used instead.

Examples

Most of the functions are fairly easy to use. The most difficult part is probably creating your first PDF document. The following example should help to get you started. It is developed for PHP 4 and creates the file hello.pdf with one page. It defines some document info field contents, loads the Helvetica-Bold font and outputs the text "Hello world! (says PHP)".

Example 1. Hello World example from PDFlib distribution for PHP 4

<?php
$p
= PDF_new();

/*  open new PDF file; insert a file name to create the PDF on disk */
if (PDF_begin_document($p, "", "") == 0) {
    die(
"Error: " . PDF_get_errmsg($p));
}

PDF_set_info($p, "Creator", "hello.php");
PDF_set_info($p, "Author", "Rainer Schaaf");
PDF_set_info($p, "Title", "Hello world (PHP)!");

PDF_begin_page_ext($p, 595, 842, "");

$font = PDF_load_font($p, "Helvetica-Bold", "winansi", "");

PDF_setfont($p, $font, 24.0);
PDF_set_text_pos($p, 50, 700);
PDF_show($p, "Hello world!");
PDF_continue_text($p, "(says PHP)");
PDF_end_page_ext($p, "");

PDF_end_document($p, "");

$buf = PDF_get_buffer($p);
$len = strlen($buf);

header("Content-type: application/pdf");
header("Content-Length: $len");
header("Content-Disposition: inline; filename=hello.pdf");
print
$buf;

PDF_delete($p);
?>

The following example comes with the PDFlib distribution for PHP 5. It uses the new exception handling and object encapsulation features available in PHP 5. It creates the file hello.pdf with one page. It defines some document info field contents, loads the Helvetica-Bold font and outputs the text "Hello world! (says PHP)".

Example 2. Hello World example from PDFlib distribution for PHP 5

<?php

try
{
    
$p = new PDFlib();

    
/*  open new PDF file; insert a file name to create the PDF on disk */
    
if ($p->begin_document("", "") == 0) {
        die(
"Error: " . $p->get_errmsg());
    }

    
$p->set_info("Creator", "hello.php");
    
$p->set_info("Author", "Rainer Schaaf");
    
$p->set_info("Title", "Hello world (PHP)!");

    
$p->begin_page_ext(595, 842, "");

    
$font = $p->load_font("Helvetica-Bold", "winansi", "");

    
$p->setfont($font, 24.0);
    
$p->set_text_pos(50, 700);
    
$p->show("Hello world!");
    
$p->continue_text("(says PHP)");
    
$p->end_page_ext("");

    
$p->end_document("");

    
$buf = $p->get_buffer();
    
$len = strlen($buf);

    
header("Content-type: application/pdf");
    
header("Content-Length: $len");
    
header("Content-Disposition: inline; filename=hello.pdf");
    print
$buf;
}
catch (PDFlibException $e) {
    die(
"PDFlib exception occurred in hello sample:\n" .
    
"[" . $e->get_errnum() . "] " . $e->get_apiname() . ": " .
    
$e->get_errmsg() . "\n");
}
catch (Exception $e) {
    die(
$e);
}
$p = 0;
?>

Table of Contents
PDF_activate_item -- Activate structure element or other content item
PDF_add_annotation -- Add annotation [deprecated]
PDF_add_bookmark -- Add bookmark for current page [deprecated]
PDF_add_launchlink -- Add launch annotation for current page [deprecated]
PDF_add_locallink -- Add link annotation for current page [deprecated]
PDF_add_nameddest -- Create named destination
PDF_add_note -- Set annotation for current page [deprecated]
PDF_add_outline -- Add bookmark for current page [deprecated]
PDF_add_pdflink -- Add file link annotation for current page [deprecated]
PDF_add_table_cell -- Add a cell to a new or existing table
PDF_add_textflow -- Create Textflow or add text to existing Textflow
PDF_add_thumbnail -- Add thumbnail for current page
PDF_add_weblink -- Add weblink for current page [deprecated]
PDF_arc -- Draw a counterclockwise circular arc segment
PDF_arcn -- Draw a clockwise circular arc segment
PDF_attach_file -- Add file attachment for current page [deprecated]
PDF_begin_document -- Create new PDF file
PDF_begin_font -- Start a Type 3 font definition
PDF_begin_glyph -- Start glyph definition for Type 3 font
PDF_begin_item -- Open structure element or other content item
PDF_begin_layer -- Start layer
PDF_begin_page_ext -- Start new page
PDF_begin_page -- Start new page [deprecated]
PDF_begin_pattern -- Start pattern definition
PDF_begin_template_ext -- Start template definition
PDF_begin_template -- Start template definition [deprecated]
PDF_circle -- Draw a circle
PDF_clip -- Clip to current path
PDF_close_image -- Close image
PDF_close_pdi_page -- Close the page handle
PDF_close_pdi -- Close the input PDF document [deprecated]
PDF_close -- Close pdf resource [deprecated]
PDF_closepath_fill_stroke -- Close, fill and stroke current path
PDF_closepath_stroke -- Close and stroke path
PDF_closepath -- Close current path
PDF_concat -- Concatenate a matrix to the CTM
PDF_continue_text -- Output text in next line
PDF_create_3dview -- Create 3D view
PDF_create_action -- Create action for objects or events
PDF_create_annotation -- Create rectangular annotation
PDF_create_bookmark -- Create bookmark
PDF_create_field -- Create form field
PDF_create_fieldgroup -- Create form field group
PDF_create_gstate -- Create graphics state object
PDF_create_pvf -- Create PDFlib virtual file
PDF_create_textflow -- Create textflow object
PDF_curveto -- Draw Bezier curve
PDF_define_layer -- Create layer definition
PDF_delete_pvf -- Delete PDFlib virtual file
PDF_delete_table -- Delete table object
PDF_delete_textflow -- Delete textflow object
PDF_delete -- Delete PDFlib object
PDF_encoding_set_char -- Add glyph name and/or Unicode value
PDF_end_document -- Close PDF file
PDF_end_font -- Terminate Type 3 font definition
PDF_end_glyph -- Terminate glyph definition for Type 3 font
PDF_end_item -- Close structure element or other content item
PDF_end_layer -- Deactivate all active layers
PDF_end_page_ext -- Finish page
PDF_end_page -- Finish page
PDF_end_pattern -- Finish pattern
PDF_end_template -- Finish template
PDF_endpath -- End current path
PDF_fill_imageblock -- Fill image block with variable data
PDF_fill_pdfblock -- Fill PDF block with variable data
PDF_fill_stroke -- Fill and stroke path
PDF_fill_textblock -- Fill text block with variable data
PDF_fill -- Fill current path
PDF_findfont -- Prepare font for later use [deprecated]
PDF_fit_image -- Place image or template
PDF_fit_pdi_page -- Place imported PDF page
PDF_fit_table -- Place table on page
PDF_fit_textflow -- Format textflow in rectangular area
PDF_fit_textline -- Place single line of text
PDF_get_apiname -- Get name of unsuccessfull API function
PDF_get_buffer -- Get PDF output buffer
PDF_get_errmsg -- Get error text
PDF_get_errnum -- Get error number
PDF_get_font -- Get font [deprecated]
PDF_get_fontname -- Get font name [deprecated]
PDF_get_fontsize -- Font handling [deprecated]
PDF_get_image_height -- Get image height [deprecated]
PDF_get_image_width -- Get image width [deprecated]
PDF_get_majorversion -- Get major version number [deprecated]
PDF_get_minorversion -- Get minor version number [deprecated]
PDF_get_parameter -- Get string parameter
PDF_get_pdi_parameter -- Get PDI string parameter [deprecated]
PDF_get_pdi_value -- Get PDI numerical parameter [deprecated]
PDF_get_value -- Get numerical parameter
PDF_info_font -- Query detailed information about a loaded font
PDF_info_matchbox -- Query matchbox information
PDF_info_table -- Retrieve table information
PDF_info_textflow -- Query textflow state
PDF_info_textline -- Perform textline formatting and query metrics
PDF_initgraphics -- Reset graphic state
PDF_lineto -- Draw a line
PDF_load_3ddata -- Load 3D model
PDF_load_font -- Search and prepare font
PDF_load_iccprofile -- Search and prepare ICC profile
PDF_load_image -- Open image file
PDF_makespotcolor -- Make spot color
PDF_moveto -- Set current point
PDF_new -- Create PDFlib object
PDF_open_ccitt -- Open raw CCITT image [deprecated]
PDF_open_file -- Create PDF file [deprecated]
PDF_open_gif -- Open GIF image [deprecated]
PDF_open_image_file -- Read image from file [deprecated]
PDF_open_image -- Use image data [deprecated]
PDF_open_jpeg -- Open JPEG image [deprecated]
PDF_open_memory_image -- Open image created with PHP's image functions [not supported]
PDF_open_pdi_page -- Prepare a page
PDF_open_pdi -- Open PDF file [deprecated]
PDF_open_tiff -- Open TIFF image [deprecated]
PDF_pcos_get_number -- Get value of pCOS path with type number or boolean
PDF_pcos_get_stream -- Get contents of pCOS path with type stream, fstream, or string
PDF_pcos_get_string -- Get value of pCOS path with type name, string, or boolean
PDF_place_image -- Place image on the page [deprecated]
PDF_place_pdi_page -- Place PDF page [deprecated]
PDF_process_pdi -- Process imported PDF document
PDF_rect -- Draw rectangle
PDF_restore -- Restore graphics state
PDF_resume_page -- Resume page
PDF_rotate -- Rotate coordinate system
PDF_save -- Save graphics state
PDF_scale -- Scale coordinate system
PDF_set_border_color -- Set border color of annotations [deprecated]
PDF_set_border_dash -- Set border dash style of annotations [deprecated]
PDF_set_border_style -- Set border style of annotations [deprecated]
PDF_set_char_spacing -- Set character spacing [deprecated]
PDF_set_duration -- Set duration between pages [deprecated]
PDF_set_gstate -- Activate graphics state object
PDF_set_horiz_scaling -- Set horizontal text scaling [deprecated]
PDF_set_info_author -- Fill the author document info field [deprecated]
PDF_set_info_creator -- Fill the creator document info field [deprecated]
PDF_set_info_keywords -- Fill the keywords document info field [deprecated]
PDF_set_info_subject -- Fill the subject document info field [deprecated]
PDF_set_info_title -- Fill the title document info field [deprecated]
PDF_set_info -- Fill document info field
PDF_set_layer_dependency -- Define relationships among layers
PDF_set_leading -- Set distance between text lines [deprecated]
PDF_set_parameter -- Set string parameter
PDF_set_text_matrix -- Set text matrix [deprecated]
PDF_set_text_pos -- Set text position
PDF_set_text_rendering -- Determine text rendering [deprecated]
PDF_set_text_rise -- Set text rise [deprecated]
PDF_set_value -- Set numerical parameter
PDF_set_word_spacing -- Set spacing between words [deprecated]
PDF_setcolor -- Set fill and stroke color
PDF_setdash -- Set simple dash pattern
PDF_setdashpattern -- Set dash pattern
PDF_setflat -- Set flatness
PDF_setfont -- Set font
PDF_setgray_fill -- Set fill color to gray [deprecated]
PDF_setgray_stroke -- Set stroke color to gray [deprecated]
PDF_setgray -- Set color to gray [deprecated]
PDF_setlinecap -- Set linecap parameter
PDF_setlinejoin -- Set linejoin parameter
PDF_setlinewidth -- Set line width
PDF_setmatrix -- Set current transformation matrix
PDF_setmiterlimit -- Set miter limit
PDF_setpolydash -- Set complicated dash pattern [deprecated]
PDF_setrgbcolor_fill -- Set fill rgb color values [deprecated]
PDF_setrgbcolor_stroke -- Set stroke rgb color values [deprecated]
PDF_setrgbcolor -- Set fill and stroke rgb color values [deprecated]
PDF_shading_pattern -- Define shading pattern
PDF_shading -- Define blend
PDF_shfill -- Fill area with shading
PDF_show_boxed -- Output text in a box [deprecated]
PDF_show_xy -- Output text at given position
PDF_show -- Output text at current position
PDF_skew -- Skew the coordinate system
PDF_stringwidth -- Return width of text
PDF_stroke -- Stroke path
PDF_suspend_page -- Suspend page
PDF_translate -- Set origin of coordinate system
PDF_utf16_to_utf8 -- Convert string from UTF-16 to UTF-8
PDF_utf32_to_utf16 -- Convert string from UTF-32 to UTF-16
PDF_utf8_to_utf16 -- Convert string from UTF-8 to UTF-16