readme.txt
1===================================
2Notes on the PDFlib binding for PHP
3===================================
4
5The binary distribution of PDFlib supports using PDFlib as a loadable
6module (DSO) in PHP. This implies some restrictions, but simplifies PDFlib
7deployment a lot. Using PDFlib as a loadable module is the recommended
8way for using PDFlib with PHP.
9
10If the loadable module does not fit your needs, the binary distribution
11also includes a precompiled PDFlib library (bind/c/lib/libpdf.*), to be used in
12your custom build process for PHP. This will allow you to integrate PDFlib
13(including the PDI functionality) into your own PHP build process.
14
15Please note that only PDFlib Lite is available in source form.
16PDFlib, PDFlib+PDI, and the PDFlib Personalization Server (PPS) are
17available for commercial licensing only, and therefore require a
18binary package.
19
20If your distribution does not contain the expected binaries, please contact
21bindings@pdflib.com. We only include binaries for the most common PHP versions
22to not overload the download package. Please include the platform and the
23exact PHP version you are looking for.
24
25Of course you may also use PDFlib for PHP with the source distribution, but
26since there are so many PHP configuration options we will only give a rough
27overview how to do this.
28
29Summary of this document:
30
31- "Loadable Module (DSO)"
32 The recommended way for using PDFlib with PHP.
33 If you could not find a DSO for your PHP version/platform in the distribution
34 please contact bindings@pdflib.com.
35
36- "Rebuild PHP"
37 If the loadable module does not fit your needs, or if DSO modules are not
38 supported on your platform, you can rebuild PHP with PDFlib support.
39 Caution: this requires substantially more effort than the loadable module.
40
41- "Samples"
42 How to set up the supplied PDFlib examples.
43
44
45Loadable Module
46===============
47
48Use the PDFlib loadable module from the "bind/php/<phpversion>" directory
49of the PDFlib binary distribution. The name of the loadable module depends
50on the platform:
51
52 - Windows: libpdf_php.dll
53 - Linux: libpdf_php.so
54 - Other Unix systems: libpdf_php.* with the appropriate shared
55 library suffix
56
57The following conditions must be met in order to use PDFlib as a
58loadable module:
59
60 - PHP on your platform must support DSOs. This is the case on Windows
61 and many Unix platforms, but not all. For example, PHP does not support
62 DSOs on Mac OS X before PHP 4.3.0.
63
64 - PDFlib support must not already have been compiled into your PHP version.
65 If your PHP already includes PDFlib support (this is the case for
66 versions of PHP distributed with many Linux distributions) you must
67 rebuild PHP with the "-with-pdflib=no" configure option.
68 (*HINT* for maintainers of Linux distributions:
69 include PDFlib support for PHP as DSO, this allows easier updates)
70
71 - Several properties of your PHP version must match the loadable module
72 of PDFlib. The supplied binary modules for PDFlib have been built as
73 follows:
74 - nondebug version
75 - for supported PHP version numbers see "bind/php/<phpversion>
76 - thread-safe (only relevant for Windows)
77
78 If you get an error message similar to the following your PHP version
79 number does not match that of the PDFlib module:
80 Warning: pdf: Unable to initialize module
81 Module compiled with debug=0, thread-safety=1 module API=20001214
82 PHP compiled with debug=0, thread-safety=1 module API=20001222
83 Unfortunately new PHP version simply deny loading a wrong module
84 whithout any specific error message.
85
86 All of these options must match.
87
88
89If you can't meet the above conditions you must choose to "Rebuild PHP" as
90described below (or ask us whether your combination will be available soon).
91
92
93Installing the module on Windows:
94
95 - Our DLLs have been tested with the binary PHP distribution which is
96 available from http://www.php.net.
97
98 - The PDFlib binary distribution for Windows contains several DLLs
99 for different versions of PHP. Currently we offer the following
100 flavors:
101
102 - "php-4.1.0\libpdf_php.dll" was built for PHP 4.1.0/4.1.1/4.2.0
103 - "php-4.2.1\libpdf_php.dll" was built for PHP 4.2.1-4.3.5
104
105 - For the PHP installation please follow the documentation of your
106 PHP distribution and copy "bind/php/<your phpversion>/libpdf_php.dll"
107 to the directory which is specified in the "extension_dir" line in
108 php.ini.
109
110Installing the module on Unix:
111
112 - The PDFlib binary distribution for Unix contains several shared libraries
113 for different versions of PHP. Currently we offer the following
114 flavors:
115
116 - "php-4.1.0\libpdf_php.*" was built for PHP 4.1.0, 4.1.1, 4.2.0
117 - "php-4.2.1\libpdf_php.*" was built for PHP 4.2.1-4.3.5
118
119 - Copy the file libpdf_php.* from the directory "bind/php/<phpversion>"
120 of the PDFlib binary distribution to the directory which is specified in
121 the "extension_dir" line in php.ini.
122
123
124Using the module:
125
126 - If you decide to load PDFlib each time PHP starts insert one line in
127 php.ini:
128 extension=libpdf_php.dll (on Windows)
129 or
130 extension = libpdf_php.so (on Unix)
131
132 and restart apache, so that the changes are recognized.
133 You may check <?phpinfo()?> whether the installation did work. If you
134 don't find a PDF section please check your logfiles for the reason.
135
136 - Without the "extension = ..." line in php.ini you must include the
137 following line in your PHP scripts:
138 dl("libpdf_php.dll"); (on Windows)
139 or
140 dl("libpdf_php.so"); (on Unix)
141
142 In this case your php.ini needs these settings:
143 - php.ini must include the line "safe_mode=Off".
144 - php.ini must include the line "enable_dl=On".
145
146
147
148Rebuild PHP
149===========
150
151If the loadable module does not fit your needs, or if DSO modules are not
152supported on your platform, you can rebuild PHP with PDFlib support.
153
154WARNING: this option requires substantial experience with building PHP.
155It is not a matter of simply calling "make" and waiting for the result.
156If you never built PHP from source code it is strongly recommended to
157avoid this option.
158
159When recompiling PHP using the library from the binary PDFlib distribution
160you have to use the library located in the "bind/c" directory of the PDFlib
161distribution.
162
163Note: Building PDFlib for PHP from the source code of PDFlib is not supported
164by PDFlib GmbH since we supply precompiled binaries (although it should work,
165and therefore you will find hints how to do it below).
166
167Unix
168 - Unpack the PDFlib binary distribution to <pdflib-dir>,
169 or unpack the PDFlib source distribution to <pdflib-dir>, and
170 issue the command
171
172 $ ./configure; make; make install
173
174 - Copy some PDFlib support files for PHP to your PHP source tree (check
175 the section "Support Files" below to see which files apply to your
176 PHP version.
177
178 $ cp <pdflib-dir>/bind/php/ext/pdf/<somefiles> <php-dir>/ext/pdf
179
180 and rebuild the PHP configure script in the PHP directory (only
181 neccesary if you decided to use our config.m4 script):
182
183 $ ./buildconf
184
185 - For rebuilding PHP add the following to your PHP configure options:
186 --with-pdflib=<pdflib-dir>/bind/c
187
188 or if building PDFlib from source:
189 --with-pdflib[=<pdflib-install-directory>]
190
191 where <pdflib-install-directory> will typically be something like
192 /usr/local or similar (the directory where "lib" and "include" for PDFlib
193 reside).
194
195 - Now rebuild PHP as usual, and install it.
196
197Windows
198 - Create PDFlib.lib from the PDFlib sources. Change the project settings
199 to create a "Multithreaded DLL" library named pdflib.lib.
200
201 - Copy the required PDFlib support files (see below) for PHP to your
202 PHP source tree.
203
204 C:\> copy <pdflib-dir>\bind\php\ext\pdf\<somefiles> <php-dir>\ext\pdf
205
206 - Now rebuild libpdf_php.dll.
207
208
209Support files
210 The following files have to be copied from bind/php/ext/pdf to the ext/pdf
211 directory of your PHP source tree. Replacing config.m4 is optional, but
212 the config.m4 supplied by us is much simpler and therefor makes less
213 troubles if you manage to go through the buildconf process.
214
215 Which files are needed depends on the PHP version you use:
216
217 PHP 4.1.0-4.1.1
218 config.php-406+.m4 -> config.m4
219 pdf.c -> pdf.c
220 php_pdf.h -> php_pdf.h
221
222 PHP 4.2.1-4.2.3
223 config.php-406+.m4 -> config.m4
224 pdf.c -> pdf.c
225 php_pdf.h -> php_pdf.h
226
227 PHP 4.3.0-4.3.5
228 pdf.c -> pdf.c
229 php_pdf.h -> php_pdf.h
230
231
232Samples
233=======
234
235To use the samples:
236
237 - Copy some files:
238 $ cp bind/php/*.php .../htdocs # (to your htdocs directory)
239 $ cp bind/data/* .../htdocs/data # (to your htdocs)
240
241 - point your browser to the sample files
242
243 - enjoy the generated PDFs
244