<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.17 $ -->
 <reference id="ref.pdf">
  <title>PDF functions </title>
  <titleabbrev>PDF</titleabbrev>

  <partintro>
   <section id="pdf.intro">
    &reftitle.intro;
    <simpara>
    The PDF functions in PHP can create PDF files using the PDFlib
    library created by <ulink url="&url.pdflib.merz;">Thomas
    Merz</ulink>.
    </simpara>
    <simpara>
    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.  Please consult the
    documentation included in the source distribution of PDFlib for
    the full and detailed explanation of each function here.  It
    provides a very good overview of what PDFlib is capable of doing
    and contains the most up-to-date documentation of all functions.
    </simpara>
    <simpara>
     All of the functions in PDFlib and the PHP module have identical
     function names and parameters. You will need to understand some
     of the basic concepts of PDF and PostScript to efficiently use
     this extension.  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 documentation included with the source distribution of
     PDFlib for a more thorough explanation of the coordinate system
     used.
    </simpara>
    <simpara> 
     Please note that most of the PDF functions require a
     <parameter>pdfdoc</parameter> as its first parameter. Please
     see the <link linkend="pdf.examples">examples</link> below for more
     information.
    </simpara>
    <note>
     <simpara>
      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>.
     </simpara>
    </note>
    <note>
     <simpara>
      This extension has been moved to <ulink url="&url.pecl;">PECL</ulink> as
      of PHP 4.3.9.
     </simpara>
    </note>
   </section>

   <section id="pdf.requirements">
    &reftitle.required;
    <para>
     PDFlib is available for download at <ulink
     url="&url.pdf;">&url.pdf;</ulink>, but requires that you purchase
     a license for commercial use. The <ulink
     url="&url.jpeg;">JPEG</ulink> and <ulink
     url="&url.tiff;">TIFF</ulink> libraries are required to compile
     this extension.
    </para>

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

   &reference.pdf.configure;

   <section id="pdf.configuration">
    &reftitle.runtime;
    &no.config;
   </section>


   <section id="pdf.oldlibs.confusion">
    <title>Confusion with old PDFlib versions</title> 
   <simpara>
    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 manual (V3.00 or greater) are
    supported by PHP 4 with exactly the same meaning and the same
    parameters. Only the return values may differ from the PDFlib
    manual, because the PHP convention of returning
    &false; was adopted. For compatibility reasons,
    this binding for PDFlib still supports the old 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.
   </simpara>
    <para>
     <table>
      <title>Deprecated functions and their replacements</title>
      <tgroup cols="2">
       <thead>
        <row>
         <entry>Old function</entry>
         <entry>Replacement</entry>
        </row>
       </thead>
       <tbody>
        <row>
         <entry><function>pdf_put_image</function></entry>
         <entry>Not needed anymore.</entry>
        </row> 
        <row>
         <entry><function>pdf_execute_image</function></entry>
         <entry>Not needed anymore.</entry>
        </row> 
        <row>
         <entry><function>pdf_get_annotation</function></entry>
         <entry><function>pdf_get_bookmark</function> using the same
         parameters.</entry>
        </row>
        <row>
         <entry><function>pdf_get_font</function></entry>
         <entry><function>pdf_get_value</function> passing
         <literal>"font"</literal> as the second parameter.</entry>
        </row>
        <row>
         <entry><function>pdf_get_fontsize</function></entry>
         <entry><function>pdf_get_value</function> passing 
                  <literal>"fontsize"</literal> as the second parameter.</entry>
        </row>
        <row>
         <entry><function>pdf_get_fontname</function></entry>
         <entry><function>pdf_get_parameter</function>  passing    
         <literal>"fontname"</literal> as the second parameter.</entry>
        </row>
        <row>
         <entry><function>pdf_set_info_creator</function></entry>
         <entry><function>pdf_set_info</function> passing    
         <literal>"Creator"</literal> as the second parameter.</entry>
        </row>
        <row>
         <entry><function>pdf_set_info_title</function></entry>
         <entry><function>pdf_set_info</function> passing
         <literal>"Title"</literal> as the second parameter.</entry>
        </row>
        <row>
         <entry><function>pdf_set_info_subject</function></entry>
         <entry><function>pdf_set_info</function> passing
         <literal>"Subject"</literal> as the second parameter.</entry>
        </row>
        <row>
         <entry><function>pdf_set_info_author</function></entry>
         <entry><function>pdf_set_info</function> passing
         <literal>"Author"</literal> as the second parameter.</entry>
        </row>
        <row>
         <entry><function>pdf_set_info_keywords</function></entry>
         <entry><function>pdf_set_info</function> passing
         <literal>"Keywords"</literal> as the second parameter.</entry>
        </row>
        <row>
         <entry><function>pdf_set_leading</function></entry>
         <entry><function>pdf_set_value</function> passing
         <literal>"leading"</literal> as the second parameter.</entry>
        </row>
        <row>
         <entry><function>pdf_set_text_rendering</function></entry>
         <entry><function>pdf_set_value</function> passing
         <literal>"textrendering"</literal> as the second parameter.</entry>
        </row>
        <row>
         <entry><function>pdf_set_text_rise</function></entry>
         <entry><function>pdf_set_value</function> passing
         <literal>"textrise"</literal> as the second parameter.</entry>
        </row>
        <row>
         <entry><function>pdf_set_horiz_scaling</function></entry>
         <entry><function>pdf_set_value</function> passing
         <literal>"horizscaling"</literal> as the second parameter.</entry>
        </row>
        <row>
         <entry><function>pdf_set_text_matrix</function></entry>
         <entry>Not available anymore</entry>
        </row>
        <row>
         <entry><function>pdf_set_char_spacing</function></entry>
         <entry><function>pdf_set_value</function> passing
         <literal>"charspacing"</literal> as the second parameter.</entry>
        </row>
        <row>
         <entry><function>pdf_set_word_spacing</function></entry>
         <entry><function>pdf_set_value</function> passing
         <literal>"wordspacing"</literal> as the second parameter.</entry>
        </row>
        <row>
         <entry><function>pdf_set_transition</function></entry>
         <entry><function>pdf_set_parameter</function> passing
         <literal>"transition"</literal> as the second parameter.</entry>
        </row>
        <row>
         <entry><function>pdf_open</function></entry>
         <entry><function>pdf_new</function> plus an subsequent call
          of <function>pdf_open_file</function></entry>
        </row>
        <row>
         <entry><function>pdf_set_font</function></entry>
         <entry><function>pdf_findfont</function> plus an subsequent call
          of <function>pdf_setfont</function></entry>
        </row>
        <row>
         <entry><function>pdf_set_duration</function></entry>
         <entry><function>pdf_set_value</function> passing
         <literal>"duration"</literal> as the second parameter.</entry>
        </row>
        <row>
         <entry><function>pdf_open_gif</function></entry>
         <entry><function>pdf_open_image_file</function> passing
         <literal>"gif"</literal> as the second parameter.</entry>
        </row>
        <row>
         <entry><function>pdf_open_jpeg</function></entry>
         <entry><function>pdf_open_image_file</function> passing
         <literal>"jpeg"</literal> as the second parameter.</entry>
        </row>
        <row>
         <entry><function>pdf_open_tiff</function></entry>
         <entry><function>pdf_open_image_file</function> passing
         <literal>"tiff"</literal> as the second parameter.</entry>
        </row>
        <row>
         <entry><function>pdf_open_png</function></entry>
         <entry><function>pdf_open_image_file</function> passing
         <literal>"png"</literal> as the second parameter.</entry>
        </row>
        <row>
         <entry><function>pdf_get_image_width</function></entry>
         <entry><function>pdf_get_value</function> passing
         <literal>"imagewidth"</literal> as the second parameter and the image
         as the third parameter.</entry>
        </row>
        <row>
         <entry><function>pdf_get_image_height</function></entry>
         <entry><function>pdf_get_value</function> passing
         <literal>"imageheight"</literal> as the second parameter and the
         image as the third parameter.</entry>
        </row>
       </tbody>
      </tgroup>
     </table>
    </para>
   </section>

   <section id="pdf.examples">
    &reftitle.examples;
    <simpara>
     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 creates <filename>test.pdf</filename>
     with one page. The page contains the text "Times Roman outlined" in an
     outlined, 30pt font. The text is also underlined.
    </simpara>
    <para>
     <example>
      <title>Creating a PDF document with PDFlib</title>
      <programlisting role="php">
<![CDATA[
<?php
$pdf = pdf_new();
pdf_open_file($pdf, "test.pdf");
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");
$font = pdf_findfont($pdf, "Times New Roman", "winansi", 1);
pdf_setfont($pdf, $font, 10);
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_delete($pdf);
echo "<A HREF=getpdf.php>finished</A>";
?>
]]>
      </programlisting>
     </example>

      The script <filename>getpdf.php</filename> just returns the pdf document.

     <example>
      <title>Outputting a precalculated PDF</title>
      <programlisting role="php">
<![CDATA[
<?php
$len = filesize($filename);
header("Content-type: application/pdf");
header("Content-Length: $len");
header("Content-Disposition: inline; filename=foo.pdf");
readfile($filename);
?>
]]>
      </programlisting>
     </example>
    </para>
    <para>
     The PDFlib distribution contains a more complex example which
     creates a page with an analog clock. Here we use the in-memory
     creation feature of PDFlib to alleviate the need to use temporary
     files. The example was converted to PHP from the PDFlib example.
     (The same example is available in the <link
     linkend="ref.cpdf">CLibPDF</link> documentation.)
    </para>
    <para>
     <example>
      <title>pdfclock example from PDFlib distribution</title>
      <programlisting role="php">
<![CDATA[
<?php
$radius = 200;
$margin = 20;
$pagecount = 10;

$pdf = pdf_new();

if (!pdf_open_file($pdf, "")) {
    echo error;
    exit;
};

pdf_set_parameter($pdf, "warning", "true");

pdf_set_info($pdf, "Creator", "pdf_clock.php");
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);

    # to see some difference
    sleep(1);
}

pdf_close($pdf);

$buf = pdf_get_buffer($pdf);
$len = strlen($buf);

header("Content-type: application/pdf");
header("Content-Length: $len");
header("Content-Disposition: inline; filename=foo.pdf");
echo $buf;

pdf_delete($pdf);
?>
]]>
      </programlisting>
     </example>
    </para>
   </section>

   <section id="pdf.seealso">
    &reftitle.seealso;
    <note>
     <para>
      An alternative PHP module for PDF document creation based on
      <ulink url="&url.cpdf;">FastIO's</ulink> ClibPDF is
      available. Please see the <link linkend="ref.cpdf">ClibPDF</link>
      section for details. Note that <link
      linkend="ref.cpdf">ClibPDF</link> has a slightly different API
      than PDFlib.
     </para>
    </note>
   </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
-->