LXXVI. PDF Funktionen

Einleitung

Mit Hilfe der PDF-Bibliothek von Thomas Merz können mit PHP PDF Dateien erzeugt werden. Die Bibliothek ist unter http://www.pdflib.com/pdflib/index.html; verfügbar. Zudem sind noch zwei weitere Bibliotheken notwendig, die JPEG Bibliothek und die TIFF Bibliothek, um PHP zu übersetzen. Diese beiden Bibliothek bereiten häufig Probleme bei der Konfiguration von PHP. Sie sollten unbedingt die Meldungen des Konfigurations-Skripts befolgen, um aufkommende Probleme zu lösen.

Beachten sie zudem die excellente Dokumentation die mit pdflib ausgeliefert wird. Sie gibt einen guten Überblick über die Möglichkeiten von pdflib.

Die meisten Funktionen in pdflib sind in ähnlicher Form auch in PHP vorhanden. Die Parameter sind in der Regel auch identisch. Sie sollten zudem die Grundkonzepte von PDF und Postscript verstanden haben, um das PDF Module effizient nutzen zu können.

Alle Längen und Koordinatenangaben sind in Postscript-Punkten gemessen. Für gewöhnlich entsprechen 72 PostScript-Punkte 1 Inch, was jedoch von der Auflösung des Ausgabegeräts abhängt.

Neben diesem Modul gibt es noch ein weiteres zur Erzeugung von PDF-Dateien basierend auf der Bibliothek ClibPDF von FastIO. Es hat eine geringfügig andere Programmierschnittstelle. Schauen Sie in die Funktionsübersicht für weitere Details.

Das PDF Module von PHP verwendet einen neuen Type von Variable Er wird pdfdoc genannt. pdfdoc ist ein Zeiger auf das PDF Dokument und wird bei fast allen Funktion als erster Parameter erwartet.

Altlasten

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.

Tabelle 1. Deprecated functions and its replacements

Old functionReplacement
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_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_imagewidth()pdf_get_value() passing "imagewidth" as the second parameter and the image as the third parameter.
pdf_get_imageheight()pdf_get_value() passing "imageheight" as the second parameter and the image as the third parameter.
()()

Tips zur Installation von pdflib 3.x

Seit Version 3.0 von pdflib sollten sie pdflib mit der configure-Option --enable-shared-pdflib konfigurieren.

Verwenden alter pdflib Versionen

Mit Version 2.20 von pdflib wurden einige Veränderungen an der API vorgenommen. Zudem ist Unterstützung für asiatische Zeichensätze hinzugekommen. Dies hat leider auch zu Änderungen am php4-Modul geführt (nicht php3). Wenn Sie pdflib 2.20 benutzen, dann sollten Sie die Erzeugung von Dokumenten im Speicher mit Vorsicht benutzen. Bis zur entgültigen Version 3.0 von pdflib könnte dies instabil sein. Der encoding Parameter der Funktion pdf_set_font() hat sich in eine Zeichenkette geändert. Dies bedeutet, dass anstatt von beispielsweise 4 jetzt 'winansi' verwendet werden muss.

Wenn Sie die Version 2.30 von pdflib verwenden, dann steht Ihnen die Funktion pdf_set_text_matrix() nicht mehr zur Verfügung. Diese Funktion wurde komplett entfernt. Grundsätzlich ist es ratsam die release notes der verwendeten Version von pdflib zu lesen.

Versionen von PHP4 die nach dem 9. März 2000 erscheinen unterstützen nur noch die Versionen >3.0 von pdflib. PHP3 sollte hingegen nicht mit Versionen >2.01 verwendet werden.

Bei Gebrauch von pdflib 2.01 sollte überprüft werden, ob die Bibliothek richtig installiert wurde. Es sollte die Datei oder ein Verweis libpdf.so im Installationsverzeichnis von pdflib existieren. Version 2.01 erzeugt nur die Bibliothek mit dem Namen libpdf2.01.so, die so nicht vom Linker des Systems gefunden werden kann. In diesem Fall müssen Sie den Verweis von libpdf.so nach libpdf2.01.so selbst anlegen.

Beispiele

Die meisten Funktionen sind sehr einfach zu benutzen. Das Schwierigste wird wohl sein, überhaupt ein einfaches PDF-Dokument zu erstellen. Das folgende Beispiel soll die ersten Schritte erleichtern. Dieses Skript erstellt die PDF-Datei test.pdf, welche nur aus einer Seite besteht. Auf der Seite befindet sich der Text "Times Roman outlined" in einem outlined, 30pt Zeichensatz. Der Text ist zudem unterstrichen.

Beispiel 1. Erstellung eines PDF Dokuments mit pdflib

<?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.php>finished</A>";
?>

Das PHP-Skript getpdf.php liefert nur das PDF-Dokument.

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

Die pdflib-Distribution enthält ein komplizierteres Beispiel, welches ein Reihe Seiten erstellt die jeweils eine analoge Uhr mit der aktuellen Uhrzeit enthalten. Dieses Beispiel in ein PHP-Skript umgesetzt sieht wie folgt aus (das gleiche Beispiel wird auch in der Dokumentation zum cpdf Modul verwendet):

Beispiel 2. pdfclock Beispiel aus der pdflib Distribution

<?php
$pdffilename = "clock.pdf";
$radius = 200;
$margin = 20;
$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");

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_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>";
?>

Das PHP-Skript getpdf.php liefert wiederum nur das Dokument.

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

Inhaltsverzeichnis
pdf_add_annotation -- Fügt eine Anmerkung hinzu
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 -- Fügt Lesemarke zur aktuellen Seite hinzu
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 -- Zeichnet einen Kreisbogen
pdf_arcn -- Draws an arc (clockwise)
pdf_attach_file -- Adds a file attachement for current page
pdf_begin_page -- Beginnt eine neue Seite
pdf_begin_pattern -- Starts new pattern
pdf_begin_template -- Starts new template
pdf_circle -- Zeichnet einen Kreis
pdf_clip -- Begrenzt alle Zeichenoperation auf den aktuellen Pfad
pdf_close_image -- Schließt ein Bild
pdf_close_pdi_page --  Close the page handle
pdf_close_pdi --  Close the input PDF document
pdf_close -- Schließt ein PDF-Dokument
pdf_closepath_fill_stroke -- Schließt, füllt und zeichnet eine Linie entlang des Pfades
pdf_closepath_stroke -- Schließt einen Pfad und zeichnet eine Linie entlang des Pfades
pdf_closepath -- Schließt einen Pfad
pdf_concat -- Concatenate a matrix to the CTM
pdf_continue_text -- Schreibt den Text in die nächste Zeile
pdf_curveto -- Zeichnet eine Kurve
pdf_delete -- Deletes a PDF object
pdf_end_page -- Beendet eine Seite
pdf_end_pattern -- Finish pattern
pdf_end_template -- Finish template
pdf_endpath -- Beendet den aktuellen Pfad
pdf_fill_stroke -- Füllt den aktuellen Pfad und zeichnet eine Linie entlang des Pfades
pdf_fill -- Füllt den aktuellen Pfad
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 -- Liefert die Höhe eines Bildes
pdf_get_image_width -- Liefert die Breite eines Bildes
pdf_get_majorversion --  Returns the major version number of the PDFlib
pdf_get_minorversion --  Returns the minor version number of the PDFlib
pdf_get_parameter -- Liefert verschiedene Parameter
pdf_get_pdi_parameter -- Get some PDI string parameters
pdf_get_pdi_value -- Gets some PDI numerical parameters
pdf_get_value -- Liefert verschiedene numerische Werte
pdf_initgraphics -- Resets graphic state
pdf_lineto -- Zeichnet eine Linie
pdf_makespotcolor -- Makes a spotcolor
pdf_moveto -- Setzt die aktuelle Position
pdf_new -- Creates 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 -- Öffnet ein GIF-Bild
pdf_open_image_file -- Liest ein Bild aus einer Datei
pdf_open_image -- Versatile function for images
pdf_open_jpeg -- Öffnet ein JPEG-Bild
pdf_open_memory_image -- Liest ein Bild, das mit PHP erzeugt wurde
pdf_open_pdi_page --  Prepare a page
pdf_open_pdi --  Opens a PDF file
pdf_open_png -- Öffnet ein PNG-Bild
pdf_open_tiff -- Öffnet ein TIFF-Bild
pdf_open -- Öffnet ein neues PDF-Dokument
pdf_place_image -- Plaziert ein Bild auf der Seite
pdf_place_pdi_page -- Places an image on the page
pdf_rect -- Zeichnet ein Rechteck
pdf_restore -- Stellt eine zuvor gesicherte Umgebung wieder her
pdf_rotate -- Setzt die Rotation
pdf_save -- Sichert die aktuelle Umgebung
pdf_scale -- Setzt den Skalierungsfaktor
pdf_set_border_color -- Setzt die Farbe der Umrandung von Verweisen und Anmerkungen
pdf_set_border_dash -- Setzt das Muster für gestrichelte Linien als Umrandung von Verweisen und Anmerkungen
pdf_set_border_style -- Setzt den Stil der Umrandung von Verweisen und Anmerkungen
pdf_set_char_spacing -- Setzt den Abstand zwischen Zeichen
pdf_set_duration -- Setzt die Zeitdauer bis zur nächsten Seite
pdf_set_font -- Wählt einen Zeichensatz und dessen Größe aus
pdf_set_horiz_scaling -- Setzt die horizontale Skalierung bei der Textausgabe
pdf_set_info_author --  Fills the author field of the document
pdf_set_info_creator --  Fills the creator field of the document
pdf_set_info_keywords --  Fills the keywords field of the document
pdf_set_info_subject --  Fills the subject field of the document
pdf_set_info_title --  Fills the title field of the document
pdf_set_info -- Setzt Info-Feld der Dokumenteninformation
pdf_set_leading -- Setzt den Abstand zwischen zwei Textzeilen
pdf_set_parameter -- Setzt verschiedene Parameter
pdf_set_text_matrix -- Setzt die Text-Matrix
pdf_set_text_pos -- Setzt die Textposition
pdf_set_text_rendering -- Bestimmt wie der Text ausgegeben werden soll
pdf_set_text_rise -- Setzt die Textverschiebung
pdf_set_value -- Setzt verschiedene numerische Werte
pdf_set_word_spacing -- Setzt den Abstand zwischen Wörtern
pdf_setcolor -- Sets fill and stroke color
pdf_setdash -- Setzt das Muster für gestrichelte Linien
pdf_setflat -- Sets flatness
pdf_setfont -- Set the current font
pdf_setgray_fill -- Setzt die Füllfarbe auf einen Grauwert
pdf_setgray_stroke -- Setzt die Zeichenfarbe auf einen Grauwert
pdf_setgray -- Setzt die Zeichen- und Füllfarbe auf einen Grauwert
pdf_setlinecap -- Setzt den Type der Linienenden
pdf_setlinejoin -- Setzt die Verbindungsart von Linien
pdf_setlinewidth -- Setzt die Linienbreite
pdf_setmatrix -- Sets current transformation matrix
pdf_setmiterlimit -- Sets miter limit
pdf_setpolydash -- Sets complicated dash pattern
pdf_setrgbcolor_fill -- Setzt die Füllfarbe auf einen Farbwert
pdf_setrgbcolor_stroke -- Setzt die Zeichenfarbe auf einen Farbwert
pdf_setrgbcolor -- Setzt die Zeichen- und Füllfarbe auf einen Farbwert
pdf_show_boxed -- Schreibt einen Text in eine Box
pdf_show_xy -- Schreibt einen Text an die angegebene Position
pdf_show -- Schreibt einen Text an die aktuelle Position
pdf_skew -- Schert das Koordinatensystem
pdf_stringwidth -- Liefert die benötigte Breite einer Zeichenkette mit dem aktuelle Zeichensatz
pdf_stroke -- Zeichnet eine Linie entlang eines Pfades
pdf_translate -- Setzt den Ursprung des Koordinatenssystems