How to use PDFlib with PHP

1 Scope of this Document

This document tries to explain various possibilities for successfully deploying PDFlib as
a PHP extension. The generic term PDFlib is used to designate one of the following dis-
tinct products:
> PDFlib Lite, the open-source subset of PDFlib
> The commercial PDFlib product
> PDFlib+PDI, a commercial superset of PDFlib which also contains the PDF Import Li-
brary (PDI)
> PDFlib Personalization Server (PPS), a superset of PDFlib+PDI with advanced block
filling features for personalizing PDF documents.

The methods for deploying any of these products as a PHP extension are the same in all
cases. However, only one product can be used at a time. Similarly, multiple versions of
these products cannot be deployed at the same time. Note that the evaluation versions
of commercial PDFlib products will be fully functional, but will display a demo stamp
across all generated PDF pages unless a valid license key is applied.
This document applies to the following software versions:
> PDFlib 5 and 6, as well as all maintenance versions of each
> PHP 4.2.0 or above, and PHP 5 as well as all maintenance versions of each.

Where applicable, version-specific information is provided separately.

Scope of this Document 1

2 Classify your System – and yourself
2.1 Platforms where PHP reliably supports DSOs
Loadable PHP extension modules implemented as DSOs (dynamic shared objects, also
called dynamic link library DLL) are the recommended method of using PDFlib with
PHP. PHP supports dynamic loading of extensions from DSOs on the following plat-
forms (only platforms supported by PDFlib GmbH are mentioned here; there may be
more):
> Windows
> Linux on x86 and ia64
> Linux on PPC
> Linux on zSeries
> FreeBSD 4 and 5 on x86
> OpenBSD on x86
> Solaris 7/8/9 on Sparc

Using commercial PDFlib packages with PHP on platforms with DSO support. PDFlib
GmbH makes available packages with precompiled binary PDFlib DSOs for several plat-
forms and PHP versions. If such a package is available for your combination of platform
and PHP proceed with Section 5, »Deploying the PDFlib DSO«.
If a PDFlib DSO is not available you need the appropriate precompiled PDFlib C lib-
rary for your platform (available for all platforms supported by PDFlib GmbH), and
must build a PDFlib DSO for PHP according to Section 6, »Building a DSO from a PDFlib
C library«.

Using PDFlib Lite with PHP on platforms with DSO support. In order to use PDFlib Lite
you need PDFlib source code, and must proceed according to Section 7, »Building PDFlib
Lite from Source«. Once you’ve done this you must build a PDFlib DSO for PHP accord-
ing to Section 6, »Building a DSO from a PDFlib C library«.

2.2 Platforms where PHP does not reliably support DSOs

In our experience PHP does not support dynamic loading of extensions on the follow-
ing platforms:
> IBM AIX
> Mac OS X is somewhat special: although some kind of DSO support is available in
PHP, we do not consider it as reliable and robust enough.

Using commercial PDFlib packages with PHP on platforms without DSO support. You
need the appropriate precompiled PDFlib C library for your platform, and must rebuild
PHP according to Section 8, »Building PHP with statically linked PDFlib«.

Using PDFlib Lite with PHP on platforms without DSO support. In order to use PDFlib
Lite you need PDFlib Lite source code and must first build a PDFlib Lite C library accord-
ing to Section 7, »Building PDFlib Lite from Source«. Next, you must rebuild PHP accord-
ing to Section 8, »Building PHP with statically linked PDFlib«.

2 The PDFlib-in-PHP HowTo November 19, 2004

2.3 Other Platforms
There may be other platforms which are supported by PHP, but where we don’t know
about the status of DSO support. PDFlib GmbH does not support the use of PDFlib with
PHP on any of these platforms.
You may be able to make PDFlib with PHP work on such a platform by rolling your
own PHP binary. However, be warned that this requires high skills and motivation, and
may nevertheless result in frustration instead of working software. After all, there are
good reasons why we don’t support certain combinations.

2.4 Required Skill Levels

Making PDFlib work with PHP requires various skill levels depending on your operating
system platform. In the following we will classify tasks according to the following skill
sets:
> A PHP Web programmer knows how to write code for PHP, but doesn’t have experi-
ence with other languages or general system administration tasks. The PHP pro-
grammer usually has access to other people who are responsible for performing con-
figuration tasks.
> A sysadmin feels comfortable working with PEAR and other command-line tools, hap-
pily edits php.ini and does not hesitate to restart the Web server (i.e. Apache or IIS) if
required for installation or configuration purposes. Appropriate permissions (access
rights) to do all this are also part of the sysadmin profile.
> A C developer has access to a C development environment (header files, compiler,
linker, associated system libraries) and can work with configure scripts and Make-
files or corresponding IDE features.

It may help to classify yourself according to these types of developers. The remainder of
this document describes tasks which require at least sysadmin or C developer skills. PHP
developers without additional knowledge or assistance will not be able to perform the
required steps without assistance.

Classify your System – and yourself 3

 3 Testing your Installation
After you installed the PDFlib extension for PHP using any of the methods discussed in
this document you may want to test your installation in order to see whether every-
thing works as expected.

The PHP info page. You can test the success of your PDFlib installation and configura-
tion with the following mini PHP script:
<?phpinfo()?>

If you don't find a PDF section check your log files to find the reason. If the output creat-
ed by phpinfo( ) contains the line PDFlib GmbH Binary Version you are using a precompiled
PDFlib DSO provided by PDFlib GmbH. If you see a line PDFlib GmbH Version you are us-
ing your own PDFlib DSO or custom PHP with a statically linked PDFlib. The version
number of the PECL module which has been used to build the PDFlib extension will also
be shown.

Note If the output of phpinfo( ) shows only »PDFlib Version« you are using an old PDFlib extension
wrapper from a PHP 4 distribution. This combination is not supported.

The PDFlib examples. The PDFlib distribution packages include with two flavours of
examples which you can use to test your installation. In the php-43x directory you will
find the old-style examples using the functional API. These examples can be used for
PHP 4 and PHP5 .
In the php-50x directory you can find the new object-oriented examples. These will
work only with PHP 5 or above. To use the examples proceed as follows:
> Copy some files to your htdocs directory:
$ cp bind/php/php-<version>/*.php .../htdocs
$ cp bind/data/* .../htdocs/data

> point your browser to the URLs of the examples

> enjoy the generated PDFs

4 The PDFlib-in-PHP HowTo November 19, 2004

4 PDFlib in Hosting Environments
You are running a site at a web hosting provider. In this case there are various consid-
erations (we can ignore the case where a PDFlib extension for PHP is already installed
since there’s nothing more to do):
> Some providers do not allow custom PHP extensions; in this case you are out of luck.
> With some providers you can maintain your own copy of php.ini, while others don’t
allow this. If you can’t edit php.ini and this file contains enable_dl=Off you are out of
luck.

You are a web hosting provider. As a provider you should be aware of the following:
> Although PDFlib Lite source code is freely available, and many Linux and PHP distri-
butions contain PDFlib Lite, the PDFlib Lite license does not cover free use of PDFlib
Lite on a Web hoster’s systems.
> You can install commercial PDFlib DSOs even without obtaining a license. In this sit-
uation you can install one of the precompiled PDFlib DSOs supplied by PDFlib GmbH
without a license key (i.e. a demo stamp will be created). Those among your custom-
ers who wish to commercially use it can obtain a commercial license to disable the
demo stamp. In other words, you can offer PDFlib without the need for obtaining a li-
cense for all of your servers. The recommended method is to install the PDFlib DSO
in some globally accessible directory, and set the extension= line in php.ini appropri-
ately.
> Alternatively, if (like an increasing number of providers) you believe in PDFlib avail-
ability as a competitive advantage, you can obtain a site license which covers all your
servers and customers. Individual users will no longer be required to obtain a license
on their own in this case. Please contact PDFlib GmbH if you are interested in more
details.

PDFlib in Hosting Environments 5

5 Deploying the PDFlib DSO
Requirements:
> skill level: sysadmin
> the PDFlib DSO (either precompiled from a binary package provided by PDFlib
GmbH, or built on your own)
> working PHP binary

This section applies to the prebuilt DSOs distributed by PDFlib GmbH, as well as to DSOs
which you have built yourself.

5.1 Installing the PDFlib DSO on Windows

The PDFlib DSOs for Windows (actually DLLs) have been tested with the binary PHP dis-
tribution which is available from http://www.php.net. You will find PDFlib DSOs for vari-
ous versions of PHP on Windows in the following location of the uncompressed pack-
age:
bind/php/php-<version>/libpdf_php.dll

For the PHP installation process please follow the documentation of your PHP distribu-
tion, and copy the PDFlib DSO to the directory which is specified in the extension_dir line
in php.ini.

5.2 Installing the PDFlib DSO on Unix

The PDFlib DSOs for various Unix platforms are available for different versions of PHP.
You will find PDFlib DSOs in the following location of the uncompressed package:
bind/php/php-<version>libpdf_php.so (adjust the shared library suffix if necessary)

Copy the PDFlib DSO to the directory which is specified in the extension_dir line in
php.ini.

5.3 Using the PDFlib DSO

Loading the PDFlib DSO in php.ini. If you decide to load PDFlib every time PHP starts,
insert one line in php.ini
extension=libpdf_php.dll (on Windows)

or
extension=libpdf_php.so (on Unix; adjust the shared library suffix if necessary)

and restart your Web server so that the changes are recognized.

Loading the PDFlib DSO explicitly in your PHP script. Without the extension line in
php.ini you must include the following line in your PHP scripts:
dl("libpdf_php.dll"); (on Windows)

6 The PDFlib-in-PHP HowTo November 19, 2004

 or
dl("libpdf_php.so"); (on Unix; adjust the shared library suffix if necessary)

In this case your php.ini must contain the following lines:

safe_mode=Off
enable_dl=On

The line extension_dir is not relevant in this case. Note that for security reasons this
method is no longer recommended; many Web hosters do not allow it.

5.4 Common Problems with PDFlib DSOs

Older version of PDFlib built into the PHP binary. PDFlib support must not already
have been compiled into your PHP version. If your PHP already includes PDFlib support
(this is the case for versions of PHP distributed with some Linux distributions) but you
need a newer PDFlib version you must first obtain a PHP binary without builtin PDFlib
support (either by locating the appropriate binary, or rebuilding it yourself. This works
similar to Section 8, »Building PHP with statically linked PDFlib«, but you must rebuild
PHP with the following configure option:
-with-pdflib=no

Note Maintainers of Linux and PHP distributions should include PDFlib support for PHP as DSO be-
cause this facilitates updates.

Binary characteristics of PHP and PDFlib DSO must match. Several properties of your
PHP binary must match those of the PDFlib DSO. These properties are determined when
building PHP, and cannot be changed afterwards. The precompiled DSOs for PDFlib have
been built as follows:
> non-debug version
> for supported PHP versions see bind/php/php-<version>
> thread-safe (mostly relevant for Windows)

If you see an error message similar to the following when trying to load the PDFlib DSO,
your PHP build number does not match that of the PDFlib module:
Warning: pdf: Unable to initialize module
Module compiled with debug=0, thread-safety=0 module API=20020429
PHP compiled with debug=0, thread-safety=1 module API=20020429

All of these options must match.

Deploying the PDFlib DSO 7

6 Building a DSO from a PDFlib C library
Requirements:
> Skill level: sysadmin
> a precompiled PDFlib C library (either precompiled from a binary package provided
by PDFlib GmbH, or built on your own from PDFlib Lite source code)
> PECL package for PDFlib
> PEAR (if available; highly recommended)

6.1 Building the PDFlib DSO with PEAR

The simplest way to build a PDFlib extension for PHP is to use the PECL module for
PDFlib, and build it with the pear command provided by PHP. PEAR (PHP Extension and
Application Repository) and PECL (a repository for PHP Extensions) are part of the PHP
project. The pear tool is included with PHP 4.3.0 and above, but can also be installed for
older versions. If you don't have pear installed with your PHP installation, or it does not
work properly for some reason you should try to get the latest version of pear.
To build and install the PDFlib extension you have to call
$ pear install pdflib

and supply the path where PDFlib is installed at the following prompt:
path to pdflib installation? : $HOME/pdflib-6.0.x/bind/c

This will create a PDFlib module called pdf.so (or similar, depending on platform). After
building the extension you should check your php.ini to make sure that the extension
was added properly, and restart Apache to activate the new module.

Other issues with PECL/PEAR and PDFlib.

> Trying to build the PECL package with GD support may fail, since PHP does not yet
support building PECL packages which use GD. Until this PHP issue is resolved you
have to copy the GD header files manually to /usr/include/php (or wherever the PHP
header files are located in your installation).

6.2 Building the PDFlib DSO without PEAR

Although it is possible to build a PDFlib DSO without PEAR, this method is not support-
ed, and not described here.

8 The PDFlib-in-PHP HowTo November 19, 2004

7 Building PDFlib Lite from Source
Requirements:
> Skill level: C developer
> PDFlib Lite source code

On Unix systems (for Windows see readme-source-windows.txt in the PDFlib Lite distri-
bution) unpack the PDFlib Lite source code, change to the created directory, and issue
the following commands:
$ ./configure
$ make
$ make install

This will create a PDFlib Lite C library. For more details see readme-source-unix.txt in the
PDFlib Lite distribution.
The last step in the sequence above will install the library and include files to some
local directory. By default these files will be installed to some system directory, which
means that sysadmin permissions are required. However, you can also install to some
private (non-privileged) directory by using the --prefix option in the initial call to the
configure script, e.g.
$ ./configure --prefix=$HOME

Note that the installation will automatically create libs and include subdirectories under
the specified prefix.

Building PDFlib Lite from Source 9

8 Building PHP with statically linked PDFlib
Requirements:
> Skill level: C developer, preferably with experience in building large software sys-
tems, plus sysadmin
> PDFlib C library (either built from PDFlib Lite source code, or obtained as a precom-
piled commercial PDFlib C library)
> PHP source code
> PECL package for PDFlib

If DSOs don’t work in your situation you must rebuild PHP from source code in order to
include PDFlib support. This step must be done within the PHP build process. Below you
will find an overview on how to achieve this, but you’ll have to refer the PHP documen-
tation for more details.

Building PHP. Unpack PHP, configure and build it to your needs. We recommend to
initially try this without PDFlib support in order to get accustomed with the process.

Prepare the PDFlib C library. For the commercial PDFlib product: unpack the PDFlib C
library and note the full path to the bind/c directory in this package.
For PDFlib Lite: build the PDFlib Lite C library according to Section 7, »Building PDFlib
Lite from Source«.

Prepare the PECL Package. Create an ext/pdf directory in your PHP source tree. Unpack
the PECL package for PDFlib, and move the content of this package (including pdf.c, php_
pdf.h and others) to the ext/pdf directory of your PHP source tree.

Put everything together. Change to the PHP source directory and follow these steps:
# rebuild the PHP configure script:
$ ./buildconf --force

# configure and build PHP with PDFlib support:

$ ./configure --with-pdflib=<pdflib source directory>/bind/c <other-php-options>
....
Thank you for using PHP.
config.status: creating php5.spec
config.status: creating main/build-defs.h
config.status: creating scripts/phpize
config.status: creating scripts/php-config
config.status: creating sapi/cli/php.1
config.status: creating main/php_config.h
config.status: executing default commands

$ make
....
Build complete.
(It is safe to ignore warnings about tempnam and tmpnam).

# install it as root
$ sudo make install

# probably you have to configure your Web server to load the new php module

10 The PDFlib-in-PHP HowTo November 19, 2004

 # restart apache (i.e. sudo apachectl restart)

Notes for Mac OS X.

> On Mac OS X pear install will fail if no libtoolize is available. Either install it from the
Apple Developer Tools CD, or try to change libtoolize to glibtoolize in the phpize script
on your system.
> If the configure script fails on Mac OS X you must set the LDFLAGS environment vari-
able appropriately. Use the as following commands in the C shell (tcsh or csh):
$ setenv LDFLAGS "-framework Carbon"

In the Bourne shell use the following commands:

$ LDFLAGS='-framework Carbon'
$ export LDFLAGS

Building PHP with statically linked PDFlib 11

9 Resources
> Latest version of this document:
http://www.pdflib.com/support/faq.html
> Precompiled PDFlib binary packages with DSOs for PHP:
http://www.pdflib.com/products/pdflib/download/index.html
> PDFlib Lite source code:
http://www.pdflib.com/products/pdflib/download-source.html
> The PDFlib mailing list:
http://groups.yahoo.com/group/pdflib
> PDFlib support for commercial licensees:
support@pdflib.com
> General information on installing PHP:
http://www.php.net/install
> PECL package for PDFlib:
http://pecl.php.net/package/pdflib
> PEAR:
http://pear.php.net
> PEAR and PECL support:
http://pear.php.net/support.php and http://pecl.php.net/support.php
> Instructions on getting the latest version of PEAR:
http://pear.php.net/manual/en/installation.getting.php
> PHP source code:
http://www.php.net/downloads.php
> Comprehensive list of PHP-related links:
http://www.php.net/links.php

12 The PDFlib-in-PHP HowTo November 19, 2004