VI. ClibPDF functions

ClibPDF lets you create PDF documents with PHP. It is available at FastIO but it isn't free software. You should definitely read the licence before you start playing with ClibPDF. If you cannot fullfil the licence agreement consider using pdflib by Thomas Merz, which is also very powerful. ClibPDF functionality and API is similar to Thomas Merz's pdflib but, according to FastIO, ClibPDF is faster and creates smaller documents. This may have changed with the new version 2.0 of pdflib. A simple benchmark (the pdfclock.c example from pdflib 2.0 turned into a php script) actually shows no difference in speed at all. The file size is also similar if compression is turned off. So, try them both and see which one does the job for you.

This documentation should be read alongside the ClibPDF manual since it explains the library in much greater detail.

Many functions in the native ClibPDF and the PHP module, as well as in pdflib, have the same name. All functions except for cpdf_open() take the handle for the document as their first parameter. Currently this handle is not used internally since ClibPDF does not support the creation of several PDF documents at the same time. Actually, you should not even try it, the results are unpredictable. I can't oversee what the consequences in a multi threaded environment are. According to the author of ClibPDF this will change in one of the next releases (current version when this was written is 1.10). If you need this functionality use the pdflib module.

Note: The function cpdf_set_font() has changed since PHP3 to support asian fonts. The encoding parameter is no longer an integer but a string.

One big advantage of ClibPDF over pdflib is the possibility to create the pdf document completely in memory without using temporary files. It also provides the ability to pass coordinates in a predefined unit length. This is a handy feature but can be simulated with pdf_translate().

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 you get started. It creates a document with one page. The page contains the text "Times-Roman" in an outlined 30pt font. The text is underlined.

Example 1. Simple ClibPDF Example

  1 
  2 <?php
  3 $cpdf = cpdf_open(0);
  4 cpdf_page_init($cpdf, 1, 0, 595, 842);
  5 cpdf_add_outline($cpdf, 0, 0, 0, 1, "Page 1");
  6 cpdf_set_font($cpdf, "Times-Roman", 30, "WinAnsiEncoding");
  7 cpdf_set_text_rendering($cpdf, 1);
  8 cpdf_text($cpdf, "Times Roman outlined", 50, 750);
  9 cpdf_moveto($cpdf, 50, 740);
 10 cpdf_lineto($cpdf, 330, 740);
 11 cpdf_stroke($cpdf);
 12 cpdf_finalize($cpdf);
 13 Header("Content-type: application/pdf");
 14 cpdf_output_buffer($cpdf);
 15 cpdf_close($cpdf);
 16 ?>
 17

The pdflib distribution contains a more complex example which creates a series of pages with an analog clock. Here is that example converted into PHP using the ClibPDF extension:

Example 2. pdfclock example from pdflib 2.0 distribution

  1 
  2 <?php
  3 $radius = 200;
  4 $margin = 20;
  5 $pagecount = 40;
  6 
  7 $pdf = cpdf_open(0);
  8 cpdf_set_creator($pdf, "pdf_clock.php3");
  9 cpdf_set_title($pdf, "Analog Clock");
 10   
 11 while($pagecount-- > 0) {
 12   cpdf_page_init($pdf, $pagecount+1, 0, 2 * ($radius + $margin), 2 * ($radius + $margin), 1.0);
 13   
 14   cpdf_set_page_animation($pdf, 4, 0.5, 0, 0, 0);  /* wipe */
 15   
 16   cpdf_translate($pdf, $radius + $margin, $radius + $margin);
 17   cpdf_save($pdf);
 18   cpdf_setrgbcolor($pdf, 0.0, 0.0, 1.0);
 19   
 20   /* minute strokes */
 21   cpdf_setlinewidth($pdf, 2.0);
 22   for ($alpha = 0; $alpha < 360; $alpha += 6)
 23     {
 24     cpdf_rotate($pdf, 6.0);
 25     cpdf_moveto($pdf, $radius, 0.0);
 26     cpdf_lineto($pdf, $radius-$margin/3, 0.0);
 27     cpdf_stroke($pdf);
 28     }
 29   
 30   cpdf_restore($pdf);
 31   cpdf_save($pdf);
 32  
 33   /* 5 minute strokes */
 34   cpdf_setlinewidth($pdf, 3.0);
 35   for ($alpha = 0; $alpha < 360; $alpha += 30)
 36   {
 37     cpdf_rotate($pdf, 30.0);
 38     cpdf_moveto($pdf, $radius, 0.0);
 39     cpdf_lineto($pdf, $radius-$margin, 0.0);
 40     cpdf_stroke($pdf);
 41   }
 42 
 43   $ltime = getdate();
 44 
 45   /* draw hour hand */
 46   cpdf_save($pdf);
 47   cpdf_rotate($pdf, -(($ltime['minutes']/60.0) + $ltime['hours'] - 3.0) * 30.0);
 48   cpdf_moveto($pdf, -$radius/10, -$radius/20);
 49   cpdf_lineto($pdf, $radius/2, 0.0);
 50   cpdf_lineto($pdf, -$radius/10, $radius/20);
 51   cpdf_closepath($pdf);
 52   cpdf_fill($pdf);
 53   cpdf_restore($pdf);
 54 
 55   /* draw minute hand */
 56   cpdf_save($pdf);
 57   cpdf_rotate($pdf, -(($ltime['seconds']/60.0) + $ltime['minutes'] - 15.0) * 6.0);
 58   cpdf_moveto($pdf, -$radius/10, -$radius/20);
 59   cpdf_lineto($pdf, $radius * 0.8, 0.0);
 60   cpdf_lineto($pdf, -$radius/10, $radius/20);
 61   cpdf_closepath($pdf);
 62   cpdf_fill($pdf);
 63   cpdf_restore($pdf);
 64 
 65   /* draw second hand */
 66   cpdf_setrgbcolor($pdf, 1.0, 0.0, 0.0);
 67   cpdf_setlinewidth($pdf, 2);
 68   cpdf_save($pdf);
 69   cpdf_rotate($pdf, -(($ltime['seconds'] - 15.0) * 6.0));
 70   cpdf_moveto($pdf, -$radius/5, 0.0);
 71   cpdf_lineto($pdf, $radius, 0.0);
 72   cpdf_stroke($pdf);
 73   cpdf_restore($pdf);
 74 
 75   /* draw little circle at center */
 76   cpdf_circle($pdf, 0, 0, $radius/30);
 77   cpdf_fill($pdf);
 78 
 79   cpdf_restore($pdf);
 80 
 81   cpdf_finalize_page($pdf, $pagecount+1);
 82 }
 83 
 84 cpdf_finalize($pdf);
 85 Header("Content-type: application/pdf");
 86 cpdf_output_buffer($pdf);
 87 cpdf_close($pdf);
 88 ?>
 89

Table of Contents
cpdf_global_set_document_limits — Sets document limits for any pdf document
cpdf_set_creator — Sets the creator field in the pdf document
cpdf_set_title — Sets the title field of the pdf document
cpdf_set_subject — Sets the subject field of the pdf document
cpdf_set_keywords — Sets the keywords field of the pdf document
cpdf_open — Opens a new pdf document
cpdf_close — Closes the pdf document
cpdf_page_init — Starts new page
cpdf_finalize_page — Ends page
cpdf_finalize — Ends document
cpdf_output_buffer — Outputs the pdf document in memory buffer
cpdf_save_to_file — Writes the pdf document into a file
cpdf_set_current_page — Sets current page
cpdf_begin_text — Starts text section
cpdf_end_text — Ends text section
cpdf_show — Output text at current position
cpdf_show_xy — Output text at position
cpdf_text — Output text with parameters
cpdf_set_font — Select the current font face and size
cpdf_set_leading — Sets distance between text lines
cpdf_set_text_rendering — Determines how text is rendered
cpdf_set_horiz_scaling — Sets horizontal scaling of text
cpdf_set_text_rise — Sets the text rise
cpdf_set_text_matrix — Sets the text matrix
cpdf_set_text_pos — Sets text position
cpdf_set_char_spacing — Sets character spacing
cpdf_set_word_spacing — Sets spacing between words
cpdf_continue_text — Output text in next line
cpdf_stringwidth — Returns width of text in current font
cpdf_save — Saves current enviroment
cpdf_restore — Restores formerly saved enviroment
cpdf_translate — Sets origin of coordinate system
cpdf_scale — Sets scaling
cpdf_rotate — Sets rotation
cpdf_setflat — Sets flatness
cpdf_setlinejoin — Sets linejoin parameter
cpdf_setlinecap — Sets linecap aparameter
cpdf_setmiterlimit — Sets miter limit
cpdf_setlinewidth — Sets line width
cpdf_setdash — Sets dash pattern
cpdf_moveto — Sets current point
cpdf_rmoveto — Sets current point
cpdf_curveto — Draws a curve
cpdf_lineto — Draws a line
cpdf_rlineto — Draws a line
cpdf_circle — Draw a circle
cpdf_arc — Draws an arc
cpdf_rect — Draw a rectangle
cpdf_closepath — Close path
cpdf_stroke — Draw line along path
cpdf_closepath_stroke — Close path and draw line along path
cpdf_fill — Fill current path
cpdf_fill_stroke — Fill and stroke current path
cpdf_closepath_fill_stroke — Close, fill and stroke current path
cpdf_clip — Clips to current path
cpdf_setgray_fill — Sets filling color to gray value
cpdf_setgray_stroke — Sets drawing color to gray value
cpdf_setgray — Sets drawing and filling color to gray value
cpdf_setrgbcolor_fill — Sets filling color to rgb color value
cpdf_setrgbcolor_stroke — Sets drawing color to rgb color value
cpdf_setrgbcolor — Sets drawing and filling color to rgb color value
cpdf_add_outline — Adds bookmark for current page
cpdf_set_page_animation — Sets duration between pages
cpdf_import_jpeg — Opens a JPEG image
cpdf_place_inline_image — Places an image on the page
cpdf_add_annotation — Adds annotation

This PHP manual is Copyright © 1997, 1998, 1999, 2000 the PHP Documentation Group. It has been licensed under the GPL. Permission granted for display on the Abscissa Tech web site on March 9, 2000. The most recent PHP documentation is available at http://www.php.net/.