- lots of cleanups in pdf documentation

- table of old functions which be used anymore
- remove everything concerning pdflib 0.6
- add missing function documentation


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@31603 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Uwe Steinmann 2000-08-31 14:58:33 +00:00
parent d4174f0aa3
commit 2481980043

View file

@ -3,215 +3,297 @@
<titleabbrev>PDF</titleabbrev>
<partintro>
<simpara>
You can use the PDF functions in PHP to create PDF files if you
have the PDF library by Thomas Merz (available at
<ulink url="&url.pdf;">&url.pdf;</ulink>;
you will also need <ulink url="&url.jpeg;">the JPEG library</ulink>
and <ulink url="&url.tiff;">the TIFF library</ulink> to
compile this. These two libs also quite often make problems when
configuring php. Follow the messages of configure to fix possible
problems. If you use pdflib 2.01 check how the lib was installed.
There should be file or link libpdf.so. Version 2.01 just creates
a lib with the name libpdf2.01.so which cannot be found when linking
the test programm in configure. You will have to create a symbolic
link from libpdf.so to libpdf2.01.so.).
</simpara>
<simpara>
Version 2.20 of pdflib has introduced more changes to its API and
support for chinese and japanese fonts. This unfortunately causes
some changes of the pdf module of php4 (not php3). If you use pdflib 2.20
handle the in memory generation of PDF documents with care. Until
pdflib 3.0 is released it might be unstable. The encoding parameter
of <function>pdf_set_font</function> has changed to a string. This
means that instead of e.g. 4 you have to use 'winansi'.
</simpara>
<simpara>
If you use pdflib 2.30 the <function>pdf_set_text_matrix</function>
will have gone. It is not supported any more. In general it is a good
advise to consult the release notes of the used version of pdflib
for possible changes.
</simpara>
<simpara>
Since version 3.0 of pdflib you should configure pdflib with the option
<literal>--enable-shared-pdflib</literal>.
</simpara>
<simpara>
Any version of PHP4 after March, 9th 2000 do not support versions
of pdflib older than 3.0. PHP3 on the other hand should not be used
with version newer than 2.01.
</simpara>
<simpara>
Please consult the excellent documentation for
pdflib shipped with the source distribution of pdflib.
It provides a very good overview of what pdflib capable of doing.
Most of the functions in pdflib
and the PHP module have the same name. The parameters are also
identical. You should also understand some of the concepts of PDF
or Postscript to efficiently use this module.
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.
</simpara>
<simpara>
There is another PHP module for pdf document creation based on
<ulink url="&url.cpdf;">FastIO's</ulink>.
ClibPDF. It has a slightly different API. Check the
<link linkend="ref.cpdf">ClibPDF functions</link> section for
details.
</simpara>
<simpara>
Currently all versions of pdflib are supported. It
is recommended that you use the newest version since it has more
features and fixes some problems which required a patch for the old
version. Unfortunately, the changes of the pdflib API in 2.x
compared to 0.6 have
been so severe that even some PHP functions had to be altered. Here
is a list of changes:
</simpara>
<itemizedlist>
<listitem>
<simpara>
The Info structure does not exist anymore. Therefore the function
<function>pdf_get_info</function> is obsolete and the functions
<function>pdf_set_info_creator</function>,
<function>pdf_set_info_title</function>,
<function>pdf_set_info_author</function>,
<function>pdf_set_info_subject</function> and
<function>pdf_set_info_keywords</function> do not take the
info structure as the first parameter but the pdf document. This
also means that the pdf document must be opened before these functions
can be called. The above functions can and should also be replaced by
<function>pdf_set_info</function>
<sect1>
<title>Introduction</title>
<simpara>
You can use the PDF functions in PHP to create PDF files if you
have the PDF library by Thomas Merz (available at
<ulink url="&url.pdf;">&url.pdf;</ulink>;
you will also need <ulink url="&url.jpeg;">the JPEG library</ulink>
and <ulink url="&url.tiff;">the TIFF library</ulink> to
compile this. These two libs also quite often make problems when
configuring php. Follow the messages of configure to fix possible
problems.
</simpara>
<simpara>
Please consult the excellent documentation for
pdflib shipped with the source distribution of pdflib.
It provides a very good overview of what pdflib capable of doing.
Most of the functions in pdflib
and the PHP module have the same name. The parameters are also
identical. You should also understand some of the concepts of PDF
or Postscript to efficiently use this module.
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.
</simpara>
<simpara>
There is another PHP module for pdf document creation based on
<ulink url="&url.cpdf;">FastIO's</ulink>.
ClibPDF. It has a slightly different API. Check the
<link linkend="ref.cpdf">ClibPDF functions</link> section for
details.
</simpara>
<simpara>
The pdf module introduces two new type of variable.
It is called <parameter>pdfdoc</parameter>
<parameter>pdfdoc</parameter> is a pointer to a pdf document and
almost all functions need it as its first parameter.
</simpara>
</listitem>
<listitem>
<simpara>
The way a new document is opened has changed. The function
<function>pdf_open</function> takes only one parameter which is
the file handle of a file opened with <function>fopen</function>.
</simpara>
</listitem>
</itemizedlist>
<simpara>
There were some more changes with the release 2.01 of pdflib which
should be covered by PHP. Some functions are not required anymore
(e.g. <function>pdf_put_image</function>). You will get a warning so
don't be shocked.</simpara>
<simpara>
The pdf module introduces two new types of variables (if pdflib 2.x
is used it is only one new type). They are called
<parameter>pdfdoc</parameter> and <parameter>pdfinfo</parameter>
(<parameter>pdfinfo</parameter> is not existent if pdflib 2.x is used.
<parameter>pdfdoc</parameter> is a pointer to a pdf document and
almost all functions need it as its first parameter.
<parameter>pdfinfo</parameter> contains meta data about the PDF
document. It has to be set before <function>pdf_open</function> is
called.</simpara>
<note><simpara>The following is only true for pdflib 0.6. Read the pdflib
manual for newer version</simpara></note>
<simpara>
In order to output text into a PDF document you will need to provide
the afm file for each font. Afm files contain font metrics for a
Postscript font. By default these afm files are searched
for in a directory named 'fonts' relative to the directory where the
PHP script is located. (Again, this was true for pdflib 0.6, newer
versions do not not neccessarily need the afm files.)</simpara>
<simpara>
Most of the functions are fairly easy to use. The most difficult part
is probably to create a very simple pdf document at all. The following
example should help to get started. It uses the PHP functions for
pdflib 0.6. It creates the file test.pdf
with one page. The page contains the text "Times-Roman" in an
outlined 30pt font. The text is also underlined.</simpara>
</sect1>
<sect1>
<title>Confusion with old pdflib versions</title>
<simpara>
Since the very begining of PDF support in PHP &mdash; starting with
pdflib 0.6 &mdash;
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.
</simpara>
<para>
<table>
<title>Deprecated functions and its 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_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_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_imagewidth</function></entry>
<entry><function>pdf_get_value</function>assing
<literal>"imagewidth"</literal> as the second parameter and the image
as the third parameter.</entry>
</row>
<row>
<entry><function>pdf_get_imageheight</function></entry>
<entry><function>pdf_get_value</function>assing
<literal>"imageheight"</literal> as the second parameter and the
image as the third parameter.</entry>
</row>
<row>
<entry><function></function></entry>
<entry><function></function></entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</sect1>
<sect1>
<title>Hints for installation of pdflib 3.x</title>
<simpara>
Since version 3.0 of pdflib you should configure pdflib with the option
<literal>--enable-shared-pdflib</literal>.
</simpara>
</sect1>
<sect1>
<title>Issues with older versions of pdflib</title>
<simpara>
If you use pdflib 2.01 check how the lib was installed.
There should be a file or a to link libpdf.so. Version 2.01 just creates
a lib with the name libpdf2.01.so which cannot be found when linking
the test programm in configure. You will have to create a symbolic
link from libpdf.so to libpdf2.01.so.).
</simpara>
<simpara>
Version 2.20 of pdflib has introduced more changes to its API and
support for chinese and japanese fonts. This unfortunately causes
some changes of the pdf module of php4 (not php3). If you use pdflib 2.20
handle the in memory generation of PDF documents with care. Until
pdflib 3.0 is released it might be unstable. The encoding parameter
of <function>pdf_set_font</function> has changed to a string. This
means that instead of e.g. 4 you have to use 'winansi'.
</simpara>
<simpara>
If you use pdflib 2.30 the <function>pdf_set_text_matrix</function>
will have gone. It is not supported any more. In general it is a good
advise to consult the release notes of the used version of pdflib
for possible changes.
</simpara>
<simpara>
Any version of PHP4 after March, 9th 2000 do not support versions
of pdflib older than 3.0. PHP3 on the other hand should not be used
with version newer than 2.01.
</simpara>
</sect1>
<sect1>
<title>Examples</title>
<simpara>
Most of the functions are fairly easy to use. The most difficult part
is probably to create a very simple pdf document at all. The following
example should help to get started.
It creates the file <filename>test.pdf</filename>
with one page. The page contains the text "Times-Roman" in an
outlined 30pt font. The text is also underlined.
</simpara>
<para>
<example>
<title>Creating a PDF document with pdflib 0.6</title>
<title>Creating a PDF document with pdflib</title>
<programlisting>
&lt;?php
$fp = fopen("test.pdf", "w");
$info = PDF_get_info();
pdf_set_info_author($info, "Uwe Steinmann");
PDF_set_info_title($info, "Test for PHP wrapper of PDFlib 0.6");
PDF_set_info_author($info, "Name of Author");
pdf_set_info_creator($info, "See Author");
pdf_set_info_subject($info, "Testing");
$pdf = PDF_open($fp, $info);
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 = 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);
pdf_end_page($pdf);
pdf_close($pdf);
fclose($fp);
echo "&lt;A HREF=getpdf.php3>finished&lt;/A>";
echo "&lt;A HREF=getpdf.php>finished&lt;/A>";
?>
</programlisting>
</example>
<para>
The PHP script getpdf.php3 just outputs the pdf document.
<informalexample>
<programlisting>
</programlisting>
<simpara>
The script <filename>getpdf.php</filename> just returns the pdf document.
</simpara>
<informalexample>
<programlisting>
&lt;?php
$fp = fopen("test.pdf", "r");
header("Content-type: application/pdf");
fpassthru($fp);
fclose($fp);
?>
</programlisting>
</informalexample>
Doing the same with pdflib 2.x looks like the following:
<example>
<title>Creating a PDF document with pdflib 2.x</title>
<programlisting>
&lt;?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 "&lt;A HREF=getpdf.php3>finished&lt;/A>";
?>
</programlisting>
<para>
The PHP script getpdf.php3 is the same as above.</para>
</example>
The pdflib distribution contains a more complex example which
creates a serious of pages with an analog clock. This example
converted into PHP using pdflib 2.x looks as the following (you
can see the same example in the documentation for the
<link linkend="ref.cpdf">clibpdf module)</link>:
<example>
<title>pdfclock example from pdflib 2.x distribution</title>
<programlisting>
</programlisting>
</informalexample>
</example>
</para>
<para>
The pdflib distribution contains a more complex example which
creates a serious of pages with an analog clock. This example
converted into PHP using pdflib looks as the following (you
can see the same example in the documentation for the
<link linkend="ref.cpdf">clibpdf module)</link>:
</para>
<para>
<example>
<title>pdfclock example from pdflib distribution</title>
<programlisting>
&lt;?php
$pdffilename = "clock.pdf";
$radius = 200;
@ -220,15 +302,15 @@ $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");
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_transition($pdf, 4); /* wipe */
pdf_set_duration($pdf, 0.5);
pdf_set_parameter($pdf, "transition", "wipe");
pdf_set_value($pdf, "duration", 0.5);
pdf_translate($pdf, $radius + $margin, $radius + $margin);
pdf_save($pdf);
@ -298,11 +380,12 @@ while($pagecount-- > 0) {
$pdf = pdf_close($pdf);
fclose($fp);
echo "&lt;A HREF=getpdf.php3?filename=".$pdffilename.">finished&lt;/A>";
echo "&lt;A HREF=getpdf.php?filename=".$pdffilename.">finished&lt;/A>";
?>
</programlisting>
<para>
The PHP script getpdf.php3 just outputs the pdf document.
</programlisting>
<simpara>
The PHP script <filename>getpdf.php</filename> just outputs the pdf document.
</simpara>
<programlisting>
&lt;?php
$fp = fopen($filename, "r");
@ -310,9 +393,10 @@ header("Content-type: application/pdf");
fpassthru($fp);
fclose($fp);
?>
</programlisting></para>
</example></para>
</partintro>
</programlisting>
</example></para>
</sect1>
</partintro>
<refentry id="function.pdf-get-info">
<refnamediv>
@ -744,14 +828,14 @@ pdf_close($pdfdoc);
<funcdef>string <function>pdf_get_parameter</function></funcdef>
<paramdef>int <parameter>pdf document</parameter></paramdef>
<paramdef>string <parameter>name</parameter></paramdef>
<paramdef>double <parameter>modifier</parameter></paramdef>
<paramdef>double <parameter><optional>modifier</optional></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <function>PDF_get_parameter</function> function gets several
parameters of pdflib which are of the type string. The function parameter
<parameter>modifier</parameter> characterizes the parameter to get.
If the modifier is not needed it has to be 0.</para>
If the modifier is not needed it has to be 0 or not passed at all.</para>
<para>
See also <function>PDF_get_value</function>,
<function>PDF_set_value</function>,
@ -796,14 +880,14 @@ pdf_close($pdfdoc);
<funcdef>double <function>pdf_get_value</function></funcdef>
<paramdef>int <parameter>pdf document</parameter></paramdef>
<paramdef>string <parameter>name</parameter></paramdef>
<paramdef>double <parameter>modifier</parameter></paramdef>
<paramdef>double <parameter><optional>modifier</optional></parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <function>PDF_get_value</function> function gets several
numerical parameters of pdflib. The function parameter
<parameter>modifier</parameter> characterizes the parameter to get.
If the modifier is not needed it has to be 0.</para>
If the modifier is not needed it has to be 0 or not passed at all.</para>
<para>
See also <function>PDF_set_value</function>,
<function>PDF_get_parameter</function>,
@ -941,6 +1025,8 @@ pdf_close($pdfdoc);
The <function>PDF_set_text_matrix</function> function sets
a matrix which describes a transformation applied on the current
text font. The matrix has to passed as an array with six elements.</para>
<note><simpara>This function is not available anymore since pdflib 2.3
</simpara></note>
</refsect1>
</refentry>