archived-doc-de/reference/pdf/reference.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- Purpose: utilspec.nontext -->
<!-- Membership: pecl, external -->

 <reference id="ref.pdf">
  <title>PDF-Funktionen</title>
  <titleabbrev>PDF</titleabbrev>

  <partintro>
   <section id="pdf.intro">
    &reftitle.intro;
    <para>
     PDF-Dateien lassen sich in PHP mithilfe der PDFlib-Bibliothek erzeugen.
     Die PDFlib-Bibliothek stammt ursprünglich von Thomas Merz und wurde
     dann von der <ulink url="www.pdflib.com">PDFlib GmbH</ulink> übernommen.
    </para>
    <para>
     Die vorliegende Beschreibung gibt nur eine kurze Übersicht über die 
     in PDFlib verfügbaren Funktionen. Eine ausführliche Behandlung
     der einzelnen Funktionen finden Sie im PDFlib-Referenzhandbuch, das
     in allen PDFlib-Paketen der PDFlib GmbH enthalten ist. Das 
     PDFlib-Referenzhandbuch liefert nicht nur eine detaillierte Übersicht
     über alle Eigenschaften von PDFlib, sondern auch eine stets aktuelle
     Beschreibung aller Funktionen.
    </para>
    <para>
     Zum schnellen Einstieg sollten Sie sich unbedingt die Code-Beispiele
     ansehen, die in jedem PDFlib-Paket enthalten sind. Die Code-Beispiele
     zeigen die elementare Ausgabe von Text, Vektorgrafik und Rasterbildern
     sowie weiterführende Funktionen, z.B. zum PDF-Import (PDI).
    </para>
    <para>
     Alle Funktionen haben in PDFlib und im PHP-Modul identische
     Funktionsnamen und -parameter. Sofern nicht anders konfiguriert, werden
     Längen- und Koordinatenangaben in PostScript-Punkten gemessen. Ein Zoll
     hat normalerweise 72 PostScript-Punkte, dies hängt jedoch von der 
     Auflösung der Ausgabe ab. Eine ausführliche Beschreibung des 
     Koordinatensystems finden Sie im PDFlib-Referenzhandbuch, das in der 
     PDFlib-Distribution enthalten ist.
    </para>
	<para>
     Ab Version 6 bietet PDFlib zusätzlich zum funktionsorientierten API für
     PHP 4 ein ein objektorientiertes API für PHP 5. Die Verwendung
     unterscheidet sich im wesentlichen in folgenden Punkten:
	</para>   
    <para>
     In PHP 4 müssen Sie sich zunächst eine PDF-Ressource besorgen,
     zum Beispiel mit folgenden Funktionsaufruf: 
    </para>   
    <para>
     $p = PDF_new().
    </para>   
    <para>
     Die erhaltene PDF-Ressource verwenden Sie dann als ersten Parameter
     in allen weiteren Funktionsaufrufen, so zum Beipiel in:
    </para>   
    <para>
     PDF_begin_document($p, "", "").
    </para>   
    <para>
     In PHP 5 dagegen wird mit folgendem Funktionsaufruf ein PDFlib-Objekt
     erzeugt: 
    </para>   
    <para>
	 $p = new PDFlib().
    </para>   
    <para>
     Dieses Objekt enthält alle PDFlib-API-Funktionen als Methoden,
     zum Beispiel:
	</para>   
    <para>
     $p->begin_document("", "").
    </para>   
    <para>
     Zudem wurden in PHP 5 Exceptions eingeführt. Diese werden von PDFlib
     ab Version 6 ebenfalls unterstützt.
	</para>   
    <para> 
     Weitere Informationen finden Sie in den 
     <link linkend="pdf.examples">Beispielen</link> weiter unten.
    </para>
    <note>
     <para>
      Wenn Sie an weiterer frei verfügbarer Software zur PDF-Erzeugung
      interessiert sind, die keine externe PDF-Bibliothek verwendet, können
      Sie sich <link linkend="faq.using.freepdf">in dieser FAQ</link> informieren.
     </para>
    </note>
   </section>

   <section id="pdf.requirements">
    &reftitle.required;
    <para>
     PDFlib Lite ist als Open Source verfügbar. Die Lizenz von PDFlib Lite
     erlaubt den kostenlosen Einsatz aber nur unter bestimmten Bedingungen.
     PDFlib Lite unterstützt eine Teilmenge von PDFlib angebotenen Funktionen;
     Einzelheiten hierzu finden Sie auf der PDFlib-Website. Die
     PDFlib-Vollversion kann von <ulink url="&url.pdf;">&url.pdf;</ulink>
     heruntergeladen werden. Zum kommerziellen Einsatz müssen Sie jedoch
     eine Lizenz erwerben. 
    </para>
   </section>

   <section id="pdf.oldlibs.hints">
    <title>Anmerkungen zu älteren PDFlib-Versionen</title>
    <para>
     PDFlib vor Version 3 wird von PHP 4 nach 9. März 2000 nicht mehr 
     unterstützt.
    </para>
    <para>
     PDFlib ab Version 4 wird von PHP ab Version 4.3 unterstützt.
    </para>
   </section>

   &reference.pdf.configure;

   <section id="pdf.resources">
    &reftitle.resources;
    &no.resource;
   </section>

   <section id="pdf.oldlibs">
    <title>Anmerkungen zu veralteten PDF-Funktionen</title> 
   <para>
    Seit PHP 4.0.5 wird die PHP-Erweiterung für PDFlib von der PDFlib GmbH
    offiziell unterstützt. Das bedeutet, dass alle im PDFlib-Referenzhandbuch
    beschriebenen Funktionen von PHP 4 mit den beschriebenen Parametern und
    der beschriebenen Funktionalität unterstützt werden. Seit PDFlib Version 
    5.0.4 müssen alle Parameter auch übergeben werden. Zur Kompatibilität
    unterstützt PDFlib weiterhin die meisten der inzwischen veralteten
    Funktionen, diese sollten jedoch durch entsprechende neue Funktionen
    ersetzt werden. PDFlib GmbH bietet keinerlei Unterstützung bei Problemen
    mit veralteten Funktionen. Die vorliegende Beschreibung kennzeichnet
    veraltete Funktionen und gibt die stattdessen zu verwendenden Funktionen
    an. 
   </para>
   </section>

   <section id="pdf.examples">
    &reftitle.examples;
    <para>
     Die meisten Funktionen sind einfach zu verwenden. Sobald Sie ein
     PDF-Dokument erstellt haben, ist die schwierigste Aufgabe schon
     erledigt. Das folgende Code-Beispiel soll Ihnen den Einstieg erleichtern.
     Es wurde für PHP 4 entwickelt und erstellt eine einseitige Datei namens
     <filename>hello.pdf</filename>. Das Beispiel definiert den Inhalt einiger
     Dokumentinfofelder, lädt die Schrift Helvetica-Bold und gibt den Text
	 "Hello world! (says PHP)" aus.
    </para>
    <para>
     <example>
      <title>Beispiel "Hello World" der PDFlib-Distribution für PHP 4</title>
      <programlisting role="php">
<![CDATA[
<?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);
?>
]]>
      </programlisting>
     </example>
    </para>
	   
    <para>
     Das folgende Code-Beispiel ist in der PDFlib-Distribution für PHP 5
     enthalten. Es verwendet die in PHP 5 erstmalig verfügbare Funktionalität
     zur Ausnahmebehandlung und Objektkapselung. Das Beispiel erstellt eine
     einseitige Datei namens <filename>hello.pdf</filename>. Es definiert den
     Inhalt einiger Dokumentinfofelder, lädt die Schrift Helvetica-Bold und
     gibt den Text "Hello world! (says PHP)" aus.
    </para>
    <para>
     <example>
      <title>Beispiel "Hello World" der PDFlib-Distribution für PHP 5</title>
      <programlisting role="php">
<![CDATA[
<?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;
?>
]]>
      </programlisting>
     </example>
    </para>
   </section>
  </partintro>

  &reference.pdf.functions;

 </reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->