From 2481980043a4a7854d27ddb7c1b3a063153dbe7a Mon Sep 17 00:00:00 2001 From: Uwe Steinmann Date: Thu, 31 Aug 2000 14:58:33 +0000 Subject: [PATCH] - lots of cleanups in pdf documentation - table of old functions which be used anymore - remove everything concerning pdflib 0.6 - add missing function documentation git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@31603 c90b9560-bf6c-de11-be94-00142212c4b1 --- functions/pdf.xml | 504 +++++++++++++++++++++++++++------------------- 1 file changed, 295 insertions(+), 209 deletions(-) diff --git a/functions/pdf.xml b/functions/pdf.xml index a7d3ee79c0..061c69eb84 100644 --- a/functions/pdf.xml +++ b/functions/pdf.xml @@ -3,215 +3,297 @@ PDF - - - You can use the PDF functions in PHP to create PDF files if you - have the PDF library by Thomas Merz (available at - &url.pdf;; - you will also need the JPEG library - and the TIFF library to - compile this. These two libs also quite often make problems when - configuring php. Follow the messages of configure to fix possible - problems. If you use pdflib 2.01 check how the lib was installed. - There should be file or link libpdf.so. Version 2.01 just creates - a lib with the name libpdf2.01.so which cannot be found when linking - the test programm in configure. You will have to create a symbolic - link from libpdf.so to libpdf2.01.so.). - - - Version 2.20 of pdflib has introduced more changes to its API and - support for chinese and japanese fonts. This unfortunately causes - some changes of the pdf module of php4 (not php3). If you use pdflib 2.20 - handle the in memory generation of PDF documents with care. Until - pdflib 3.0 is released it might be unstable. The encoding parameter - of pdf_set_font has changed to a string. This - means that instead of e.g. 4 you have to use 'winansi'. - - - If you use pdflib 2.30 the pdf_set_text_matrix - will have gone. It is not supported any more. In general it is a good - advise to consult the release notes of the used version of pdflib - for possible changes. - - - Since version 3.0 of pdflib you should configure pdflib with the option - --enable-shared-pdflib. - - - Any version of PHP4 after March, 9th 2000 do not support versions - of pdflib older than 3.0. PHP3 on the other hand should not be used - with version newer than 2.01. - - - Please consult the excellent documentation for - pdflib shipped with the source distribution of pdflib. - It provides a very good overview of what pdflib capable of doing. - Most 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. - - - Currently all versions of pdflib are supported. It - is recommended that you use the newest version since it has more - features and fixes some problems which required a patch for the old - version. Unfortunately, the changes of the pdflib API in 2.x - compared to 0.6 have - been so severe that even some PHP functions had to be altered. Here - is a list of changes: - - - - - The Info structure does not exist anymore. Therefore the function - pdf_get_info is obsolete and the functions - pdf_set_info_creator, - pdf_set_info_title, - pdf_set_info_author, - pdf_set_info_subject and - pdf_set_info_keywords do not take the - info structure as the first parameter but the pdf document. This - also means that the pdf document must be opened before these functions - can be called. The above functions can and should also be replaced by - pdf_set_info + + Introduction + + You can use the PDF functions in PHP to create PDF files if you + have the PDF library by Thomas Merz (available at + &url.pdf;; + you will also need the JPEG library + and the TIFF library to + compile this. These two libs also quite often make problems when + configuring php. Follow the messages of configure to fix possible + problems. + + + Please consult the excellent documentation for + pdflib shipped with the source distribution of pdflib. + It provides a very good overview of what pdflib capable of doing. + Most 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 two new type of variable. + It is called pdfdoc + pdfdoc is a pointer to a pdf document and + almost all functions need it as its first parameter. - - - - The way a new document is opened has changed. The function - pdf_open takes only one parameter which is - the file handle of a file opened with fopen. - - - - - - There were some more changes with the release 2.01 of pdflib which - should be covered by PHP. Some functions are not required anymore - (e.g. pdf_put_image). You will get a warning so - don't be shocked. - - - The pdf module introduces two new types of variables (if pdflib 2.x - is used it is only one new type). They are called - pdfdoc and pdfinfo - (pdfinfo is not existent if pdflib 2.x is used. - pdfdoc is a pointer to a pdf document and - almost all functions need it as its first parameter. - pdfinfo contains meta data about the PDF - document. It has to be set before pdf_open is - called. - - The following is only true for pdflib 0.6. Read the pdflib - manual for newer version - - In order to output text into a PDF document you will need to provide - the afm file for each font. Afm files contain font metrics for a - Postscript font. By default these afm files are searched - for in a directory named 'fonts' relative to the directory where the - PHP script is located. (Again, this was true for pdflib 0.6, newer - versions do not not neccessarily need the afm files.) - - - Most of the functions are fairly easy to use. The most difficult part - is probably to create a very simple pdf document at all. The following - example should help to get started. It uses the PHP functions for - pdflib 0.6. It creates the file test.pdf - with one page. The page contains the text "Times-Roman" in an - outlined 30pt font. The text is also underlined. + + + Confusion with old pdflib versions + + Since the very begining of PDF support in PHP — starting with + pdflib 0.6 — + there has been tons of changes especially to the pdflib API. Most of + these changes has been somehow covered by PHP, some has even required + changes to the PHP API. Since pdflib + 3.x the API seems to be stabilzed and PHP4 has adopted the version as a + minimum requirement for PDF support. The consequence will be that many + functions will disappear or be replaced by alternatives sooner or later. + Support for pdflib 0.6 is already completely given up. + The following table list all the functions which are deprecated + in PHP 4.02 and should be replaced by their new versions. + + + + Deprecated functions and its replacements + + + + Old function + Replacement + + + + + pdf_put_image + Not needed anymore. + + + 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_set_duration + pdf_set_value passing + "duration" as the second parameter. + + + pdf_open_gif + pdf_open_image_filepassing + "gif" as the second parameter. + + + pdf_open_jpeg + pdf_open_image_filepassing + "jpeg" as the second parameter. + + + pdf_open_tiff + pdf_open_image_filepassing + "tiff" as the second parameter. + + + pdf_open_png + pdf_open_image_filepassing + "png" as the second parameter. + + + pdf_get_imagewidth + pdf_get_valueassing + "imagewidth" as the second parameter and the image + as the third parameter. + + + pdf_get_imageheight + pdf_get_valueassing + "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 + + If you use pdflib 2.01 check how the lib was installed. + There should be a file or a to link libpdf.so. Version 2.01 just creates + a lib with the name libpdf2.01.so which cannot be found when linking + the test programm in configure. You will have to create a symbolic + link from libpdf.so to libpdf2.01.so.). + + + Version 2.20 of pdflib has introduced more changes to its API and + support for chinese and japanese fonts. This unfortunately causes + some changes of the pdf module of php4 (not php3). If you use pdflib 2.20 + handle the in memory generation of PDF documents with care. Until + pdflib 3.0 is released it might be unstable. The encoding parameter + of pdf_set_font has changed to a string. This + means that instead of e.g. 4 you have to use 'winansi'. + + + If you use pdflib 2.30 the pdf_set_text_matrix + will have gone. It is not supported any more. In general it is a good + advise to consult the release notes of the used version of pdflib + for possible changes. + + + Any version of PHP4 after March, 9th 2000 do not support versions + of pdflib older than 3.0. PHP3 on the other hand should not be used + with version newer than 2.01. + + + + Examples + + Most of the functions are fairly easy to use. The most difficult part + is probably to create a very simple pdf document at all. The following + example should help to get started. + It creates the file test.pdf + with one page. The page contains the text "Times-Roman" in an + outlined 30pt font. The text is also underlined. + + - Creating a PDF document with pdflib 0.6 + Creating a PDF document with pdflib <?php $fp = fopen("test.pdf", "w"); -$info = PDF_get_info(); -pdf_set_info_author($info, "Uwe Steinmann"); -PDF_set_info_title($info, "Test for PHP wrapper of PDFlib 0.6"); -PDF_set_info_author($info, "Name of Author"); -pdf_set_info_creator($info, "See Author"); -pdf_set_info_subject($info, "Testing"); -$pdf = PDF_open($fp, $info); -PDF_begin_page($pdf, 595, 842); -PDF_add_outline($pdf, "Page 1"); -pdf_set_font($pdf, "Times-Roman", 30, 4); -pdf_set_text_rendering($pdf, 1); -PDF_show_xy($pdf, "Times Roman outlined", 50, 750); +$pdf = PDF_open($fp); +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_end_page($pdf); +pdf_close($pdf); fclose($fp); -echo "<A HREF=getpdf.php3>finished</A>"; +echo "<A HREF=getpdf.php>finished</A>"; ?> - - - - - - The PHP script getpdf.php3 just outputs the pdf document. - - - + + + The script getpdf.php just returns the pdf document. + + + <?php $fp = fopen("test.pdf", "r"); header("Content-type: application/pdf"); fpassthru($fp); fclose($fp); ?> - - - - Doing the same with pdflib 2.x looks like the following: - - - Creating a PDF document with pdflib 2.x - -<?php -$fp = fopen("test.pdf", "w"); -$pdf = PDF_open($fp); -pdf_set_info_author($pdf, "Uwe Steinmann"); -PDF_set_info_title($pdf, "Test for PHP wrapper of PDFlib 2.0"); -PDF_set_info_author($pdf, "Name of Author"); -pdf_set_info_creator($pdf, "See Author"); -pdf_set_info_subject($pdf, "Testing"); -PDF_begin_page($pdf, 595, 842); -PDF_add_outline($pdf, "Page 1"); -pdf_set_font($pdf, "Times-Roman", 30, 4); -pdf_set_text_rendering($pdf, 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); -fclose($fp); -echo "<A HREF=getpdf.php3>finished</A>"; -?> - - - The PHP script getpdf.php3 is the same as above. - - - The pdflib distribution contains a more complex example which - creates a serious of pages with an analog clock. This example - converted into PHP using pdflib 2.x looks as the following (you - can see the same example in the documentation for the - clibpdf module): - - - pdfclock example from pdflib 2.x distribution - + + + + + + The pdflib distribution contains a more complex example which + creates a serious of pages with an analog clock. This example + converted into PHP using pdflib looks as the following (you + can see the same example in the documentation for the + clibpdf module): + + + + pdfclock example from pdflib distribution + <?php $pdffilename = "clock.pdf"; $radius = 200; @@ -220,15 +302,15 @@ $pagecount = 40; $fp = fopen($pdffilename, "w"); $pdf = pdf_open($fp); -pdf_set_info_creator($pdf, "pdf_clock.php3"); -pdf_set_info_author($pdf, "Uwe Steinmann"); -pdf_set_info_title($pdf, "Analog Clock"); +pdf_set_info($pdf, "Creator", "pdf_clock.php3"); +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_transition($pdf, 4); /* wipe */ - pdf_set_duration($pdf, 0.5); + pdf_set_parameter($pdf, "transition", "wipe"); + pdf_set_value($pdf, "duration", 0.5); pdf_translate($pdf, $radius + $margin, $radius + $margin); pdf_save($pdf); @@ -298,11 +380,12 @@ while($pagecount-- > 0) { $pdf = pdf_close($pdf); fclose($fp); -echo "<A HREF=getpdf.php3?filename=".$pdffilename.">finished</A>"; +echo "<A HREF=getpdf.php?filename=".$pdffilename.">finished</A>"; ?> - - - The PHP script getpdf.php3 just outputs the pdf document. + + + The PHP script getpdf.php just outputs the pdf document. + <?php $fp = fopen($filename, "r"); @@ -310,9 +393,10 @@ header("Content-type: application/pdf"); fpassthru($fp); fclose($fp); ?> - - - + + + + @@ -744,14 +828,14 @@ pdf_close($pdfdoc); string pdf_get_parameter int pdf document string name - double modifier + double modifier The PDF_get_parameter function gets several parameters of pdflib which are of the type string. The function parameter modifier characterizes the parameter to get. - If the modifier is not needed it has to be 0. + If the modifier is not needed it has to be 0 or not passed at all. See also PDF_get_value, PDF_set_value, @@ -796,14 +880,14 @@ pdf_close($pdfdoc); double pdf_get_value int pdf document string name - double modifier + double modifier The PDF_get_value function gets several numerical parameters of pdflib. The function parameter modifier characterizes the parameter to get. - If the modifier is not needed it has to be 0. + If the modifier is not needed it has to be 0 or not passed at all. See also PDF_set_value, PDF_get_parameter, @@ -941,6 +1025,8 @@ pdf_close($pdfdoc); The PDF_set_text_matrix function sets a matrix which describes a transformation applied on the current text font. The matrix has to passed as an array with six elements. + This function is not available anymore since pdflib 2.3 +