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

 <reference id="ref.pdf">
  <title>PDF &Functions;</title>
  <titleabbrev>PDF</titleabbrev>

  <partintro>
   <section id="pdf.intro">
    &reftitle.intro;
    <para>
     The PDF functions in PHP can create PDF files using the PDFlib
     library which was initially created by Thomas Merz and is now
     maintained by <ulink url="&url.pdf;">PDFlib GmbH</ulink>.
    </para>
    <para>
     The documentation in this section is only meant to be an overview
     of the available functions in the PDFlib library and should not be
     considered an exhaustive reference. For the full and detailed 
	 explanation of each function, consult the PDFlib Reference Manual
	 which is included in all PDFlib packages distributed by PDFlib GmbH.
     It provides a very good overview of what PDFlib is capable of doing
     and contains the most up-to-date documentation of all functions.
    </para>
    <para>
     For a jump start we urge you to take a look at the programming samples
     which are contained in all PDFlib distribution packages. These samples
     demonstrate basic text, vector, and graphics output as well as 
     higher-level functions, such as the PDF import facility (PDI).
    </para>
    <para>
     All of the functions in PDFlib and the PHP module have identical
     function names and parameters. Unless configured otherwise, 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. Please see the PDFlib Reference Manual
     included in the PDFlib distribution for a more thorough explanation
     of the coordinate system used.
    </para>
	<para>
     With version 6, PDFlib offers an object-oriented API for PHP 5 in 
     addition to the function-oriented API for PHP 4. The main difference is
     the following:
	</para>   
    <para>
     In PHP 4, first a PDF resource has to be retrieved with a function call
     like 
    </para>   
    <para>
     $p = PDF_new().
    </para>   
    <para>
     This PDF resource is used as the first parameter in all further function
     calls, such as in
    </para>   
    <para>
     PDF_begin_document($p, "", "").
    </para>   
    <para>
     In PHP 5 however, a PDFlib object is created with
    </para>   
    <para>
	 $p = new PDFlib().
    </para>   
    <para>
     This object offers all PDFlib API functions as methods, e.g. as with
	</para>   
    <para>
     $p->begin_document("", "").
    </para>   
    <para>
     In addition, exceptions have been introduced in PHP 5 which are
     supported by PDFlib 6 and later as well.
	</para>   
    <para> 
     Please see the <link linkend="pdf.examples">examples</link> below for
	 more information.
    </para>
    <note>
     <para>
      If you're interested in alternative free PDF generators that do not 
      utilize external PDF libraries, see <link linkend="faq.using.freepdf">
      this related FAQ</link>.
     </para>
    </note>
   </section>

   <section id="pdf.requirements">
    &reftitle.required;
    <para>
     PDFlib Lite is available as open source. However, the
     PDFlib Lite license allows free use only under certain conditions.
     PDFlib Lite supports a subset of PDFlib's functionality; please see the
     PDFlib web site for details. The full version of PDFlib is available for
     download at <ulink url="&url.pdf;">&url.pdf;</ulink>, but requires that
     you purchase a license for commercial use.
    </para>
   </section>

   <section id="pdf.oldlibs.hints">
    <title>Issues with older versions of PDFlib</title>
    <para>
     Any version of PHP 4 after March 9, 2000 does not support versions
     of PDFlib older than 3.0.
    </para>
    <para>
     PDFlib 4.0 or greater is supported by PHP 4.3 and later.
    </para>
   </section>

   &reference.pdf.configure;

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

   <section id="pdf.oldlibs">
    <title>Remarks about Deprecated PDFlib Functions</title> 
   <para>
    Starting with PHP 4.0.5, the PHP extension for PDFlib is
    officially supported by PDFlib GmbH. This means that all the
    functions described in the PDFlib Reference Manual are
    supported by PHP 4 with exactly the same meaning and the same
    parameters. However, with PDFlib Version 5.0.4 or higher all parameters
	have to be specified. For compatibility reasons, this binding for PDFlib
    still supports most of the deprecated functions, but they
    should be replaced by their new versions. PDFlib GmbH will not
    support any problems arising from the use of these deprecated
    functions. The documentation in this section indicates old functions as
	"Deprecated" and gives the replacement function to be used instead. 
   </para>
   </section>

   <section id="pdf.examples">
    &reftitle.examples;
    <para>
     Most of the functions are fairly easy to use. The most difficult part
     is probably creating your first PDF document. The following
     example should help to get you started. It is developed for PHP 4 and 
     creates the file <filename>hello.pdf</filename> with one page.
	 It defines some document info field contents, loads the Helvetica-Bold
	 font and outputs the text "Hello world! (says PHP)".
    </para>
    <para>
     <example>
      <title>Hello World example from PDFlib distribution for 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>
     The following example comes with the PDFlib distribution for PHP 5.
	 It uses the new exception handling and object encapsulation features
	 available in PHP 5. It creates the file <filename>hello.pdf</filename>
     with one page. It defines some document info field contents, loads the
     Helvetica-Bold font and outputs the text "Hello world! (says PHP)".
    </para>
    <para>
     <example>
      <title>Hello World example from PDFlib distribution for 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
-->