LXIII. PDF funkce

Introduction

Pokud máte PDF knihovnu od Thomase Merze (dostupná z http://www.pdflib.com/pdflib/index.html), můžete používat PDF funkce na tvorbu PDF souborů; ke kompilaci budete potřebovat také JPEG knihovnu a TIFF knihovnu. Tyto dvě knihovny poměrně často dělají potíže při konfiguraci PHP. Při řešení případných problémů se řiďte chybovými zprávami configure skriptu.

Věnujte prosím pozornost výborné dokumentaci pdflib, která je součástí distribuce zdrojového kódu. Poskytuje velmi dobrý přehled schopností pdflib. Většina funkcí pdflib a příslušného PHP modulu má stejné jméno. Argumenty jsou také identické. Pokud chcete tento modul využívat opravdu efektivně, měli byste chápat také některé z konceptů PDF nebo Postscriptu. Všechny rozměry a koordináty se udávají v Postscriptových bodech. Obecně je 72 PostScriptových bodů na palec, ale závisí to na výstupním rozlišení.

Existuje další PHP modul na tvorbu PDF dokumentů, založený na ClibPDF od firmy FastIO. Má mírně jinou API. Detaily viz ClibPDF funkce.

Tento PDF modul zavádí nový typ proměnné. Nazývá se pdfdoc. pdfdoc je pointer na PDF dokument a téměř všechny funkce ho vyžadují jako svůj první argument.

Zmatek se starými verzemi pdflib

Od úplného začátky podpory PDF v PHP — od pdflib 0.6 — došlo k mnoha změnám zvláště v API pdflib. Většinu těchto změn PHP nějak zakrylo, některé vyžadovaly změnu PHP API. Od pdflib 3.x se API snad stabilizovala, a PHP 4 přijala tuto verzi jako mimimální pro podporu PDF. Následkem toho mnoho funkcí dříve či později zmizí nebo bude nahraženo alternativami. Podpora pdflib 0.6 už byla naprosto ukončena. Následující tabulka vyjmenovává všechny funkce, které jsou od PHP 4.0.2 zastaralé a měly by být nahraženy jejich novějšími verzemi.

Tabulka 1. Zastaralé funkce a jejich náhrady

Stará funkceNáhrada
pdf_put_image()Není potřeba.
pdf_get_font()pdf_get_value() s "font" jako druhý argument.
pdf_get_fontsize()pdf_get_value() s "fontsize" jako druhý argument.
pdf_get_fontname()pdf_get_parameter() s "fontname" jako druhý argument.
pdf_set_info_creator()pdf_set_info() s "Creator" jako druhý argument.
pdf_set_info_title()pdf_set_info() s "Title" jako druhý argument.
pdf_set_info_subject()pdf_set_info() s "Subject" jako druhý argument.
pdf_set_info_author()pdf_set_info() s "Author" jako druhý argument.
pdf_set_info_keywords()pdf_set_info() s "Keywords" jako druhý argument.
pdf_set_leading()pdf_set_value() s "leading" jako druhý argument.
pdf_set_text_rendering()pdf_set_value() s "textrendering" jako druhý argument.
pdf_set_text_rise()pdf_set_value() s "textrise" jako druhý argument.
pdf_set_horiz_scaling()pdf_set_value() s "horizscaling" jako druhý argument.
pdf_set_text_matrix()neexistuje
pdf_set_char_spacing()pdf_set_value() s "charspacing" jako druhý argument.
pdf_set_word_spacing()pdf_set_value() s "wordspacing" jako druhý argument.
pdf_set_transition()pdf_set_parameter() s "transition" jako druhý argument.
pdf_set_duration()pdf_set_value() s "duration" jako druhý argument.
pdf_open_gif()pdf_open_image_file() s "gif" jako druhý argument.
pdf_open_jpeg()pdf_open_image_file() s "jpeg" jako druhý argument.
pdf_open_tiff()pdf_open_image_file() s "tiff" jako druhý argument.
pdf_open_png()pdf_open_image_file() s "png" jako druhý argument.
pdf_get_imagewidth()pdf_get_value() s "imagewidth" jako druhý argument a obrázkem jako třetí argument.
pdf_get_imageheight()pdf_get_value() s "imageheight" jako druhý argument a obrázkem jako třetí argument.
()()

Rady pro instalaci pdflib 3.x

Od pdflib 3.0 by se pdflib měla konfigurovat s volbou --enable-shared-pdflib.

Problémy se staršími verzemi pdflib

Pokud používáte pdflib 2.01, zkontrolujte, jak je tato knihovna nainstalována. Měli byste mít soubor libpdf.so, nebo link na něj. Verze 2.01 vytváří soubor libpdf2.01.so, který se nedá najít při linkování testovacího souboru v configure. Budete muset vytvořit symbolický link z libpdf.so na libpdf2.01.so.

Ve verzi 2.20 přibyly další změny v API pdflib a podpora čínských a japonských fontů. Pokud používáte pdflib 2.20 buďte opatrní při generování PDF dokumentů v paměti. Do verze pdflib 3.0 by mohlo být nestabilní. Argument kódování v pdf_set_font() se změnil na řetězec. To znamená, že místo např. 4 musíte použít 'winansi'.

Pokud používáte pdflib 2.30, nemáte k dispozici pdf_set_text_matrix(). Přestala být podporována. Obecnou radou je zjistit si případné změny v release notes používané verze pdflib.

Žádná verze PHP 4 od data 9. března 2000 nepodporuje podflib starší než 3.0. Na druhou stranu, PHP 3 by se nemělo používat s novější verzí pdflib než 2.01.

Ukázky

Většina funkcí se používá docela snadno. Nejtěžší je zřejmě vůbec nějaký jednoduchý PDF dokument vůbec vytvořit. Následující ukázka by měla pomoci začít. Vytvoří soubor test.pdf s jednou stránkou. Tato stránka obsahuje text "Times Roman outlined" napsaný 30ti bodovým obrysem. Text je také podtržený.

Příklad 1. Tvorba PDF dokumentu s pdflib


<?php
$fp = fopen("test.pdf", "w");
$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);
fclose($fp);
echo "<A HREF=getpdf.php>finished</A>";
?>
      

Skript getpdf.php pouze vrátí vytvořený pdf dokument.


<?php
$fp = fopen("test.pdf", "r");
header("Content-type: application/pdf");
fpassthru($fp);
fclose($fp);
?>
       

Distribuce pdflib obsahuje rozsáhlejší ukázku, která obsahuje sérii stránek s analogovými hodinami. Tato ukázka převedená do PHP vypadá takto (stejnou ukázku najdete v dokumentaci k clibpdf modulu):

Příklad 2. pdfclock ukázka z pdflib distribuce


<?php
$pdffilename = "clock.pdf";
$radius = 200;
$margin = 20;
$pagecount = 40;

$fp = fopen($pdffilename, "w");
$pdf = pdf_open($fp);
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_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);
}

$pdf = pdf_close($pdf);
fclose($fp);
echo "<A HREF=getpdf.php?filename=".$pdffilename.">finished</A>";
?>
      

PHP skript getpdf.php pouze vrátí výtvořený PDF dokument.


<?php
$fp = fopen($filename, "r");
header("Content-type: application/pdf");
fpassthru($fp);
fclose($fp);
?>
      

Obsah
pdf_set_info -- Vyplnit položku informací o dokumentu
pdf_open -- Otevřít nový PDF dokument
pdf_close -- Zavřít PDF dokument
pdf_begin_page -- Začít novou stranu
pdf_end_page -- Ukončit stranu
pdf_show -- Umístit text na aktuální pozici
pdf_show_boxed -- Vytisknout text v rámečku
pdf_show_xy -- Vytisknout text na určené pozici
pdf_set_font -- Určit font a velikost
pdf_set_leading -- Nastavit vzdálenost mezi řádky
pdf_set_parameter -- Nastavit určité parametry
pdf_get_parameter -- Zjistit hodnotu parametru
pdf_set_value -- Sets certain numerical value
pdf_get_value -- Gets certain numerical value
pdf_get_image_height -- Returns height of an image
pdf_get_image_width -- Returns width of an image
pdf_set_text_rendering -- Determines how text is rendered
pdf_set_horiz_scaling -- Sets horizontal scaling of text
pdf_set_text_rise -- Sets the text rise
pdf_set_text_matrix -- Sets the text matrix
pdf_set_text_pos -- Sets text position
pdf_set_char_spacing -- Sets character spacing
pdf_set_word_spacing -- Sets spacing between words
pdf_skew -- Skews the coordinate system
pdf_continue_text -- Outputs text in next line
pdf_stringwidth -- Returns width of text using current font
pdf_save -- Saves the current environment
pdf_restore -- Restores formerly saved environment
pdf_translate -- Sets origin of coordinate system
pdf_scale -- Sets scaling
pdf_rotate -- Sets rotation
pdf_setflat -- Sets flatness
pdf_setlinejoin -- Sets linejoin parameter
pdf_setlinecap -- Sets linecap parameter
pdf_setmiterlimit -- Sets miter limit
pdf_setlinewidth -- Sets line width
pdf_setdash -- Sets dash pattern
pdf_moveto -- Sets current point
pdf_curveto -- Draws a curve
pdf_lineto -- Draws a line
pdf_circle -- Draws a circle
pdf_arc -- Draws an arc
pdf_rect -- Draws a rectangle
pdf_closepath -- Closes path
pdf_stroke -- Draws line along path
pdf_closepath_stroke -- Closes path and draws line along path
pdf_fill -- Fills current path
pdf_fill_stroke -- Fills and strokes current path
pdf_closepath_fill_stroke -- Closes, fills and strokes current path
pdf_endpath -- Ends current path
pdf_clip -- Clips to current path
pdf_setgray_fill -- Sets filling color to gray value
pdf_setgray_stroke -- Sets drawing color to gray value
pdf_setgray -- Sets drawing and filling color to gray value
pdf_setrgbcolor_fill -- Sets filling color to rgb color value
pdf_setrgbcolor_stroke -- Sets drawing color to rgb color value
pdf_setrgbcolor -- Sets drawing and filling color to rgb color value
pdf_add_outline -- Adds bookmark for current page
pdf_set_transition -- Sets transition between pages
pdf_set_duration -- Sets duration between pages
pdf_open_gif -- Opens a GIF image
pdf_open_png --  Opens a PNG image
pdf_open_image_file -- Reads an image from a file
pdf_open_memory_image -- Opens an image created with PHP's image functions
pdf_open_jpeg -- Opens a JPEG image
pdf_open_tiff -- Opens a TIFF image
pdf_close_image -- Closes an image
pdf_place_image -- Places an image on the page
pdf_put_image -- Stores an image in the PDF for later use
pdf_execute_image -- Places a stored image on the page
pdf_add_annotation -- Adds annotation
pdf_set_border_style -- Sets style of border around links and annotations
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