Notes on the PDFlib binding for PHP Overview ======== The binary distribution of PDFlib supports using PDFlib as a loadable module in PHP. This implies some restrictions, but simplifies PDFlib deployment a lot. Using PDFlib as a loadable module is the recommended way for using PDFlib with PHP. If the loadable module does not fit your needs, the binary distribution also includes a precompiled PDFlib library (libpdf.*), to be used in your custom build process for PHP. This will allow you to integrate PDFlib (including the PDI functionality) into your own PHP build process. Please note that the binary distribution is for commercial licensing only. If you want to use the PDF import library PDI you _must_ use the binary distribution, since PDI is not available in source form. Of course you may also use PDFlib for PHP with the source distribution, but since there are so many PHP configuration options we will only give a rough overview how to do this. Summary: - "Loadable Module (DSO)" The recommended way for using PDFlib with PHP. - "Rebuild PHP" If the loadable module does not fit your needs, or if DSO modules are not supported on your platform, you can rebuild PHP with PDFlib support. Caution: this requires more effort than the loadable module. - "Fonts" Explains how to integrate your own fonts to be used with PDFlib. - "Samples" How to set up the supplied PDFlib examples. Loadable Module =============== Use the PDFlib loadable module from the "bind/php/" directory of the PDFlib binary distribution. The name of the loadable module depends on the platform: - Windows: php_pdf.dll - Linux: libpdf_php.so - Other Unix systems: libpdf_php.* with the appropriate shared library suffix The following conditions must be met in order to use PDFlib as a loadable module: - PHP on your platform must support DSOs. This is the case on Windows and many Unix platforms, but not all. For example, PHP does not support DSOs on Mac OS X. - 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 many Linux distributions) you must rebuild PHP with the "-with-pdflib=no" configure option. (*HINT* for maintainers of linux distributions: include PDFlib support for PHP as DSO, this allows easier updates) - The PDFlib loadable module (libpdf_php.*/php_pdf.dll) must be placed in the directory specified in the php.ini variable "extension_dir". - php.ini must include the line "safe_mode=Off". - php.ini must include the line "enable_dl=On". - Several properties of your PHP version must match the loadable module of PDFlib. The supplied binary modules for PDFlib have been built as follows: - nondebug version - for supported PHP version numbers see "bind/php/ - thread-safe (only relevant for Windows) If you get an error message similar to the following your PHP version number does not match that of the PDFlib module: Warning: pdf: Unable to initialize module Module compiled with debug=0, thread-safety=1 module API=20001214 PHP compiled with debug=0, thread-safety=1 module API=20001222 All of these options must match. If you can't meet the above conditions you must choose to "Rebuild PHP" as described below (or ask us whether your combination will be available soon). Installing the module on Windows: - Our DLLs have been tested with the binary PHP distribution which is available from http://www.php.net. - The PDFlib binary distribution for Windows contains several DLLs for different versions of PHP. Currently we offer the following flavors: - "php-4.0.6\php_pdf.dll" was built for php4.0.6 - "php-4.1.0\php_pdf.dll" was built for php4.1.0/php4.1.1/php4.2.0 - "php-4.2.1\php_pdf.dll" was built for php4.2.1 - For the PHP installation please follow the documentation of your PHP distribution and copy "bind/php//php_pdf.dll" to \winnt\system32. Installing the module on Unix: - The PDFlib binary distribution for Unix contains several shared libraries for different versions of PHP. Currently we offer the following flavors: - "php-4.0.6\libpdf_php.*" was built for php4.0.6 - "php-4.1.0\libpdf_php.*" was built for php4.1.0/php4.1.1/php4.2.0 - "php-4.2.1\libpdf_php.*" was built for php4.2.1 - Copy the file libpdf_php.* from the directory "bind/php/" of the PDFlib binary distribution to the directory which is specified in the "extension_dir" line in php.ini. Using the module: - If you decide to load PDFlib each time PHP starts insert one line in php.ini: extension=php_pdf.dll (on Windows) or extension = libpdf_php.so (on Unix) (Note: this requires PHP 4.0.5 or above) and restart apache, so that the changes are recognized. You may check whether the installation did work. If you don't find a PDF section please check your logfiles for the reason. - Without the "extension = ..." line in php.ini you must include the following line in your PHP scripts: dl("php_pdf.dll"); (on Windows) or dl("libpdf_php.so"); (on Unix) Rebuild PHP =========== When recompiling PHP using the library from the binary distribution of PDFlib you have to use the library located in the "bind/c" directory of the PDFlib distribution. Note: Building PDFlib for PHP from the source code of PDFlib is not supported by PDFlib GmbH since we supply precompiled binaries (although it should work, and therefore you will find hints how to do it below). Unix - Unpack the PDFlib binary distribution to , or unpack the PDFlib source distribution to , and issue the command $ ./configure; make; make install - Copy some PDFlib support files for PHP to your PHP source tree (check the section "Support Files" below to see which files apply to your PHP version. $ cp /bind/php/ext/pdf/ /ext/pdf and rebuild the PHP configure script in the PHP directory: $ ./buildconf - For rebuilding PHP add the following to your PHP configure options: --with-pdflib=/bind/c or if building PDFlib from source: --with-pdflib[=] where will typically be something like /usr/local or similar (the directory where "lib" and "include" for PDFlib reside). - Now rebuild PHP as usual, and install it. Windows - Create PDFlib.lib from the PDFlib sources. Change the project settings to create a "Multithreaded DLL" library named pdflib.lib. - Copy the required PDFlib support files (see below) for PHP to your PHP source tree. C:\> copy \bind\php\ext\pdf\ \ext\pdf - Now rebuild php_pdf.dll. Support files The following files have to be copied from bind/php/ext/pdf to the ext/pdf directory of your PHP source tree. Which files are needed depends on the PHP version you use: PHP-4.0.6: config.php-406+.m4 -> config.m4 pdf.c -> pdf.c PHP-4.1.0/4.1.1 config.php-406+.m4 -> config.m4 pdf.c -> pdf.c PHP-4.2.1 config.php-406+.m4 -> config.m4 pdf.c -> pdf.c Fonts ===== If you need special fonts or encodings you have to copy the contents of the "fonts" directory of the PDFlib distribution to some directory on your system. Inform PDFlib about the location of these files by one of the following methods: - Set the PDFLIBRESOURCE environment variable. This has to be done in a way that the apache/php/pdflib process will recognise it, e.g. in your apache start script. - PDF_set_parameter($p, "resourcefile", "/path/to/pdflib.upr"); PDF_set_parameter($p, "prefix", "/path/to/fonts"); - Use PDF_set_parameter() to set all font-specific information "FontAFM", "FontPFM", "FontOutline", "Encoding". See the PDFlib manual for details. - Place "pdflib.upr" whereever the current directory is while executing your script (not recommended). Samples ======= To use the samples: - Copy some files: $ cp bind/php/*.php .../htdocs # (to your htdocs directory) $ cp doc/PDFlib-manual.pdf .../htdocs # (to your htdocs) $ cp doc/PDFlib-purchase-order.pdf .../htdocs # (to your htdocs) $ cp test/nesrin.jpg .../htdocs # (to your htdocs) - point your browser to the sample files - enjoy the generated PDFs