PD4ML for PHP
pd4ml-php brings PD4ML to PHP: it converts HTML and CSS into PDF,
PDF/A, PDF/UA, ZUGFeRD/Factur-X invoices, DOCX, RTF and page images, and
gives PHP applications the complete public PD4ML API.
PD4ML is a Java library. pd4ml-php runs it in a small Java bridge process that PHP talks to
over a pipe (or a local TCP port): every PD4ML class and method can be called from PHP as if it
were a PHP object, and the module adds PHP-style I/O on top — file paths, strings and streams
instead of Java streams.
The PD4ML manual, which this guide refers to throughout, is at https://pd4ml.com/docs/. The generated reference of every class and method is api.md.
Contents
1. Prerequisites
| Requirement | Notes |
|---|---|
| PHP 8.1 or later | CLI, FPM or any SAPI that may start processes (proc_open) or open local sockets. Extensions: json, mbstring, simplexml; openssl for downloading PD4ML. |
| Composer | To install the module from Packagist (https://getcomposer.org); optional, see 2.1. |
| Java 8 or later | A JDK or JRE; an LTS release (17, 21) is recommended. Found through PD4ML_JAVA, JAVA_HOME, or java on the PATH. |
| PD4ML | Downloaded by vendor/bin/pd4ml install (see below), or any PD4ML build you point the module at. |
| Network access | Only for the download; conversions themselves need none, unless the HTML references remote resources. |
| A PD4ML license | Optional for evaluation: without one, PD4ML runs in evaluation mode and watermarks its output. See Licensing and 5.18. |
Check with php -v, php -m and java -version. On a server without Java, install a JRE
package (for example apt install openjdk-21-jre-headless) and, if it is not on the PATH,
set JAVA_HOME or PD4ML_JAVA.
2. Installation
2.1 Add the module
The module is published on Packagist,
the main Composer repository, as pd4ml/pd4ml-php. In your project's directory:
composer require pd4ml/pd4ml-php
Composer downloads the module into vendor/, adds it to composer.json (as ^1.0, so later
1.x releases are accepted) and installs its command-line tool as vendor/bin/pd4ml
(vendor\bin\pd4ml on Windows). Load the module with Composer's autoloader:
require __DIR__ . '/vendor/autoload.php';
composer update pd4ml/pd4ml-php updates it later. The source, issues and release tags are at
https://github.com/zxfr/pd4ml-php.
Without Composer, clone or download the source anywhere, include its own autoloader
(require '/path/to/pd4ml-php/src/autoload.php';) and run the tool as php bin/pd4ml instead
of vendor/bin/pd4ml in the commands below.
2.2 Install PD4ML
vendor/bin/pd4ml install
This downloads the most recent PD4ML 4.x release from the PD4ML Maven repository
(https://pd4ml.com/maven2), together with the Bouncy Castle jars PD4ML needs for encryption
and signing (from Maven Central), checks every file against its published SHA-1 checksum and
stores them in a per-user cache directory (%LOCALAPPDATA%\pd4ml-php on Windows,
~/.cache/pd4ml-php elsewhere). The module then uses that build by itself; run the command
again to update.
| Option | |
|---|---|
| (none) | the most recent 4.x release |
--snapshots |
the most recent 4.x build, development snapshots included |
--version=4.0.23fx2 |
an exact version |
--jakarta |
the -jakarta variant (for Jakarta EE / Servlet 6 environments) |
--home=DIR |
install into DIR (default: PD4ML_HOME, else the cache directory) |
--force |
download again |
--no-bouncycastle |
skip the Bouncy Castle jars (encryption and signing will not work) |
vendor/bin/pd4ml list |
list the available versions |
The same from PHP, for a script's initialisation:
use Pd4ml\Installer;
Installer::install(); // downloads only when that build is not there yet
echo Installer::installedVersion(), PHP_EOL;
Check the installation: vendor/bin/pd4ml version.
Web servers: the user the web server runs as must see the installed build — install it as that user, or install into a shared directory with
--home=and setPD4ML_HOMEfor the web server too.
2.3 Other ways to provide PD4ML
The module looks for PD4ML in this order:
Bridge::configure(['classpath' => [...]]), before the first conversion;- the
PD4ML_CLASSPATHenvironment variable — jars and class directories separated by;(Windows) or:(elsewhere),dir/*for all jars of a directory; - the
PD4ML_CLASSPATH_FILEenvironment variable — a file with one entry per line; - the build
vendor/bin/pd4ml installdownloaded.
Typical reasons to use them:
- Offline / air-gapped servers:
vendor/bin/pd4ml install --home=./pd4ml-libson a machine with network access, copy the directory, setPD4ML_HOMEon the target. - A licensed or specific jar:
PD4ML_CLASSPATH=/opt/pd4ml/pd4ml.jar:/opt/pd4ml/lib/*. - A PD4ML development build (the v42 layout engine, see 4.3): a classpath file listing the build's classes and its Maven dependencies, in
PD4ML_CLASSPATH_FILE.
3. Quick start
use Pd4ml\PD4ML;
use Pd4ml\Java;
$pd = new PD4ML();
$pd->setPageSize(Java::PageSize()->A4);
$pd->readHtmlString('<h1>Hello, PDF</h1><p>Generated with <b>PD4ML</b>.</p>');
$pd->writePDF('hello.pdf');
Or in one call:
use Pd4ml\Pdf;
use Pd4ml\Bytes;
$pdf = Pdf::htmlToPdf(new Bytes('<h1>Invoice 42</h1>'));
assert(str_starts_with($pdf, '%PDF'));
4. How it works
4.1 The two-phase model
Every conversion is read once, written any number of times: readHTML parses and lays out
the document; each writePDF, writeDOCX, writeRTF or renderAsImages then produces one
output from that same layout. Settings (page size, headers, fonts...) go before readHTML.
See the two-phase model.
use Pd4ml\PD4ML;
$pd = new PD4ML();
$pd->readHtmlString('<h1>Quarterly report</h1>');
$pd->writePDF('report.pdf');
$pd->writeDOCX('report.docx');
$thumbnails = $pd->renderPng(); // PNG images, one string per page
4.2 The bridge
Per process (default). The first use of PD4ML starts a Java bridge process for the PHP process; it serves every conversion of that PHP process and ends with it. A CLI script, a queue worker or a long-running PHP server starts Java once (roughly a second); afterwards a conversion of an ordinary document takes milliseconds.
Shared server (web servers). Under PHP-FPM, mod_php or CGI, each request is a fresh start — run one bridge server for all of them instead:
vendor/bin/pd4ml serve --port=8723 # keep it running (systemd, supervisor, a Windows service)and set
PD4ML_BRIDGE=tcp://127.0.0.1:8723for the web server (or callBridge::configure(['server' => 'tcp://127.0.0.1:8723'])). The server listens on the loopback interface only; each connection has its own objects.JVM options (memory, system properties):
PD4ML_JVM_OPTIONS="-Xmx2g", orBridge::configure(['jvmOptions' => ['-Xmx2g']])before the first use. Java runs headless.The bridge's own console output is discarded;
PD4ML_BRIDGE_LOG=/path/to/filekeeps it.
4.3 Layout engines
PD4ML 4.2 introduces a second HTML layout engine, v42, written for close agreement with
current browsers (flexbox, grid, modern CSS). new PD4ML() uses it by default:
use Pd4ml\PD4ML;
use Pd4ml\Runtime;
if (Runtime::hasLayoutEngines()) {
$pd = new PD4ML(); // v42
$legacy = new PD4ML(null, null, 'v40'); // the previous engine
echo $pd->engine, ' ', $legacy->engine, PHP_EOL;
}
Builds before 4.2 — including the current public release, 4.1.x — have one engine only. With
such a build the module uses it and raises a notice (E_USER_NOTICE) once;
Runtime::hasLayoutEngines() returns false, and asking for an engine explicitly throws.
4.4 PHP and Java values
- Java methods keep their Java names (
setPageSize,readHTML...) and take PHP values:string,int,float,bool,null, arrays (lists for Java arrays/lists, associative arrays forMaps). - A Java object comes back as a
JavaObject: call its methods, read its public fields ($size->width), cast it to string (toString()). Javanullisnull. - Java classes:
Java::PageSize(),Java::Constants(),Java::PdfSpec()... (seePd4ml\Java), any other one withJava::cls('java.util.Locale'). Static fields and methods are read on them with->(Java::PageSize()->A4), constructors called with->new(...). - Binary data: PHP strings go to Java as text. Wrap binary content — a PDF, an HTML file's raw bytes — in
new Bytes($data)(strings that are not valid UTF-8 are sent as bytes anyway). A Javabyte[]comes back as a PHP string. - Floats: write
10.0rather than10where a Java method has bothintandfloatoverloads and you want the latter.
4.5 Exceptions
Java exceptions are thrown as Pd4ml\JavaException, which knows the Java class and its
superclasses:
use Pd4ml\JavaException;
use Pd4ml\PD4ML;
try {
$pd = new PD4ML();
$pd->readHTML('file:///no/such/document.html');
$pd->writePDF();
} catch (JavaException $e) {
if ($e->isInstanceOf('java.io.IOException')) {
echo 'cannot read the document: ', $e->getJavaMessage(), PHP_EOL;
}
}
$e->javaClass, $e->causes and $e->javaTrace hold the details. Problems with the bridge
itself (no Java, no PD4ML build) are Pd4ml\BridgeException.
5. Use cases
The snippets below are complete and runnable; files they read (report.html...) are assumed to
exist in the working directory, and Composer's autoloader (vendor/autoload.php) to be loaded.
5.1 HTML string to PDF
The common case for web applications: render HTML with your template engine (Twig, Blade, plain PHP), convert it in memory.
use Pd4ml\PD4ML;
$html = '<html><body><h1>Order 1001</h1><p>Thank you for your order.</p></body></html>';
$pd = new PD4ML();
$pd->readHtmlString($html);
$pdf = $pd->writePDF(); // the PDF as a string
writePDF, writeDOCX and writeRTF return the document without a target, write to a file
path, or write into an open stream (fopen(...), php://output, php://memory).
5.2 Files and URLs
use Pd4ml\PD4ML;
$pd = new PD4ML();
$pd->readHTML('report.html'); // also: 'https://example.com/report'
$pd->writePDF('report.pdf');
Relative links (<img src="logo.png">, <link href="style.css">) resolve against the
document's own location when it is read from a path or URL. When the HTML comes from a string,
Bytes or a stream, pass the base location — otherwise images and stylesheets silently go
missing (see reading the source):
use Pd4ml\PD4ML;
$html = '<link rel="stylesheet" href="style.css"><p class="note">Styled</p>';
$pd = new PD4ML();
$pd->readHtmlString($html, '.'); // a directory, file path or URL
$pd->writePDF('styled.pdf');
For a document in a known non-UTF-8 encoding: $pd->readHTML(new Bytes($data), $base, 'windows-1251').
5.3 Page size, orientation, margins and scaling
use Pd4ml\Java;
use Pd4ml\PD4ML;
$pd = new PD4ML();
$pd->setPageSize(Java::PageSize()->LETTER->rotate()); // landscape
$pd->setPageMargins(Java::PageMargins()->new(15, 20, 15, 20, Java::Units()->MM)); // left, top, right, bottom
$pd->setHtmlWidth(1000); // the virtual browser width the page is laid out in
$pd->readHtmlString("<table width='100%'><tr><td>wide content</td></tr></table>");
$pd->writePDF('landscape.pdf');
The layout is scaled to the page: scale = printable width / html width. A smaller HTML width
makes everything larger. adjustHtmlWidth(true) uses the document's own natural width;
fitPageVertically(Java::Constants()->CENTER_ALIGN) shrinks the whole document onto a single
page. Page size and margins accept a page scope ('1', '2+', 'odd'...) as a second
argument. More in page layout.
Custom sizes: Java::PageSize()->new(100.0, 150.0, Java::Units()->MM); named sizes:
Java::PageSize()->getInstance('A5').
5.4 Headers, footers and page numbers
Headers and footers are HTML fragments; $[page], $[total] and $[title] are filled in per
page, and setDynamicData adds placeholders of your own (note the single quotes, so PHP does
not interpolate $[...]):
use Pd4ml\PD4ML;
$pd = new PD4ML();
$pd->setDynamicData(['customer' => 'Acme Corp.', 'invoice' => 'INV-2026-0031']);
$pd->setPageHeader('<div style="font-size:9pt"><b>$[title]</b></div>', 30, '1+');
$pd->setPageFooter(
'<div style="font-size:8pt; text-align:right">'
. 'Invoice $[invoice] — $[customer] — page $[page] of $[total]</div>',
24, '1+');
$pd->readHtmlString('<title>Invoice</title><h1>Invoice</h1>' . str_repeat('<p>Line item</p>', 80));
$pd->writePDF('invoice.pdf');
The second argument is the area height in pixels, the third the page scope: '1' (first page),
'2+' (all but the first), 'odd', 'even', '3-7'... Headers and footers can also be
written inline in the HTML with PD4ML's extension tags. See
headers, footers, watermarks and backgrounds
and the usage examples.
5.5 Watermarks and page backgrounds
use Pd4ml\PD4ML;
$pd = new PD4ML();
$pd->setWatermark('<span style="font-size:72pt; color:#c00">DRAFT</span>',
120.0, 350.0, // left, top (px)
0.15, // opacity
45.0, // rotation, degrees
1.0, // scale
true, true, // visible on screen, in print
'1+'); // pages
$pd->setPageBackground('<div style="background:#f7f7f2; height:100%"></div>', '1+');
$pd->readHtmlString('<h1>Proposal</h1>');
$pd->writePDF('draft.pdf');
5.6 Fonts
PD4ML covers Unicode broadly with its built-in fonts. For a specific typeface (a corporate font, CJK coverage), give it a font directory:
use Pd4ml\PD4ML;
$pd = new PD4ML();
$pd->useTTF('/opt/fonts', true); // a directory of TTF/OTF fonts (indexed: see below)
$pd->embedTTFs(true, false); // embed only the glyphs used
$pd->applyKerning(true);
$pd->enableLigatures(true);
Index a font directory once ahead of time — PD4ML then reads the index
(pd4fonts.properties) instead of scanning all fonts on every conversion
(font indexing):
java -jar <pd4ml jar> -configure.fonts /opt/fonts
(php -r "require 'vendor/autoload.php'; echo Pd4ml\Installer::installedJar();" prints the jar's
path.) CSS @font-face web fonts in the document work as well.
5.7 Bookmarks, links and tables of contents
use Pd4ml\PD4ML;
$pd = new PD4ML();
$pd->generateBookmarksFromHeadings(true); // one PDF bookmark per <h1>..<h6>
$pd->enableHyperlinks(true); // <a href> become clickable links (the default)
$pd->readHtmlString('<h1>Introduction</h1><p>...</p><h1 style="page-break-before:always">Details</h1>');
$pd->writePDF('bookmarked.pdf');
A table of contents with page numbers can be generated from the headings with PD4ML's
<pd4ml:toc> tag: see the usage examples.
Explicit page breaks: CSS page-break-before / break-before, or <pd4ml:page.break>.
5.8 PDF/A and PDF/UA
use Pd4ml\Java;
use Pd4ml\PD4ML;
$spec = Java::PdfSpec();
$pd = new PD4ML();
$pd->readHtmlString("<html lang='en'><title>Annual report</title><h1>Annual report</h1>");
$pd->writePDF('archive.pdf', $spec->PDFA_3B); // archival
$pd->writePDF('accessible.pdf', $spec->PDFUA_1); // accessible
$pd->writePDF('both.pdf', $spec->PDF_1_7->combine($spec->PDFA_2A));
$status = $pd->getLastRenderInfo(Java::Constants()->PD4ML_PDFA_STATUS); // after writing
The spec can also be given as a keyword string ('pdf/a-3b'; Java::PdfSpec()->listKeywords()
lists them); unknown keywords throw InvalidArgumentException. PDF/A embeds all fonts; PDF/UA
needs well-structured HTML (real headings, alt texts, lang, table headers) — combine with
$pd->setErrorPolicy(Java::ErrorPolicy()->PEDANTIC) to be told when the source does not satisfy
the standard. Details: PDF/A, PDF/UA and e-invoicing.
5.9 ZUGFeRD / Factur-X e-invoices
PdfSpec->ZUGFeRD / PdfSpec->FacturX select the PDF/A-3 container the standards require; the
invoice XML is attached from the HTML with PD4ML's attachment tag. The complete recipe, with
the required attachment names, is on the
ZUGFeRD and Factur-X page.
use Pd4ml\Java;
use Pd4ml\PD4ML;
$pd = new PD4ML();
$pd->readHTML('invoice.html'); // contains the <pd4ml:attachment> of factur-x.xml
$pd->writePDF('invoice.pdf', Java::PdfSpec()->FacturX);
5.10 Passwords and permissions
use Pd4ml\Java;
use Pd4ml\PD4ML;
$C = Java::Constants();
$pd = new PD4ML();
$pd->setPermissions('owner-secret', $C->AllowPrint | $C->AllowCopy, $C->AES_256BIT);
$pd->readHtmlString('<p>Confidential</p>');
$pd->writePDF('protected.pdf');
Combine the Allow* flags with |, or start from DefaultPermissions and remove flags with
^. Needs the Bouncy Castle jars (installed by vendor/bin/pd4ml install). See
permissions and encryption.
5.11 Word (DOCX, RTF) and images
use Pd4ml\Java;
use Pd4ml\PD4ML;
$pd = new PD4ML();
$pd->readHtmlString('<h1>Letter</h1><p>Dear customer, ...</p>');
$pd->writeDOCX('letter.docx');
$pd->writeRTF('letter.rtf');
$pages = $pd->renderPng(); // PNG per page
$tiffs = $pd->renderAsImages(Java::Constants()->TIFF); // one TIFF per page
$pd->renderAsImages('.', 'page', Java::Constants()->PNG24); // page files in a directory
Image formats: PNG8, PNG24, TIFF, TIFF_COMPRESSED (Constants); the multi-page TIFF
formats are not supported by the v42 engine yet — use the v40 engine for them. With the v42
engine, DOCX/RTF output can be made editable — text boxes and form fields instead of
pictures for positioned content: $pd->setParam(Java::Constants()->PD4ML_WORD_EDITABLE, 'true').
5.12 Interactive forms and multi-column layout
use Pd4ml\PD4ML;
$pd = new PD4ML();
$pd->generateForms(true, null); // <input>/<select>/<textarea> become PDF form fields
$pd->readHtmlString("<form>Name: <input name='name' size='30'></form>");
$pd->writePDF('form.pdf');
$news = new PD4ML();
$news->generateMulticolumn(2, 20, true); // two columns, 20 mm apart
$news->readHtmlString('<h1>Newsletter</h1>' . str_repeat('<p>Lorem ipsum dolor sit amet.</p>', 200));
$news->writePDF('newsletter.pdf');
See forms and multi-column pages (PD4ML 4.0.24 / 4.1.2 and later).
5.13 Adding CSS and HTML programmatically
use Pd4ml\PD4ML;
$pd = new PD4ML();
$pd->addStyle('body { font-family: sans-serif } h1 { color: #036 }', true); // true: after the document's styles
$pd->injectHtml('<div style="font-size:8pt">Generated by the reporting service</div>', false); // before </body>
$pd->readHtmlString('<h1>Report</h1>');
$pd->writePDF('report-styled.pdf');
addStyle also takes the URL of a stylesheet ($pd->addStyle(Runtime::toUrl('print.css'), true)).
See injecting HTML
and adding styles.
5.14 Progress, diagnostics and metadata
use Pd4ml\Java;
use Pd4ml\PD4ML;
$pd = new PD4ML();
$pd->monitorProgressWith(function (int $messageId, int $percent, ?string $note, int $msec) {
printf("%3d%% %s (%d ms)\n", $percent, $note ?? '', $msec);
});
$pd->setErrorPolicy(Java::ErrorPolicy()->NORMAL); // NONE, RELAXED, NORMAL, PEDANTIC, STRICT
$pd->setLogLevel(1); // 0 (silent) .. 5
$pd->setAuthorName('Reporting service');
$pd->setDocumentTitle('Monthly statement');
$pd->addMetadata('StatementId', '2026-10', false);
$pd->readHtmlString('<h1>Statement</h1>');
$pd->writePDF('statement.pdf');
$pages = (int) $pd->getLastRenderInfo(Java::Constants()->PD4ML_TOTAL_PAGES);
The callback runs in PHP while the conversion runs in Java; an exception it throws comes out of the call that caused it. The v42 engine currently reports fewer progress stages than v40. More in extensibility and diagnostics.
5.15 Working with existing PDFs
use Pd4ml\Bytes;
use Pd4ml\Pdf;
$cover = Pdf::htmlToPdf(new Bytes('<h1 style="margin-top:300px; text-align:center">Annual Report</h1>'));
$body = Pdf::htmlToPdf(new Bytes('<h2>Chapter 1</h2><p>...</p>'));
$doc = Pdf::open($cover); // a path, URL, PDF string, Bytes or stream (+ password)
$doc->append(Pdf::open($body)); // pages of another document after these
$doc->setTitle('Annual Report');
Pdf::write($doc, 'annual-report.pdf');
$stamp = Pdf::htmlToPdf(new Bytes('<p style="color:#c00; font-size:40pt">COPY</p>'));
$original = Pdf::open('annual-report.pdf');
$original->overlay(Pdf::open($stamp), 128); // draw over every page, half opaque (0..255)
Pdf::write($original, 'annual-report-copy.pdf', 'secret');
echo Pdf::open('annual-report.pdf')->getNumberOfPages(), PHP_EOL;
underlay draws another document under the pages (a letterhead), Pdf::merge($a, $b)
appends two documents in one call, deletePage, getPageSize, getMetadata, dumpOutlines
inspect and edit a document. PD4ML's PDF toolkit (signing, optimisation, XFDF) is described in
the PDF post-processing toolkit
and reachable through Java::cls(...).
5.16 Web applications
With the bridge server running (vendor/bin/pd4ml serve, 4.2) and
PD4ML_BRIDGE set for the web server:
// plain PHP
use Pd4ml\PD4ML;
$pd = new PD4ML();
$pd->readHtmlString(render_invoice_html($number), __DIR__ . '/assets');
header('Content-Type: application/pdf');
header("Content-Disposition: inline; filename=invoice-$number.pdf");
$pd->writePDF(fopen('php://output', 'wb'));
// Laravel
use Pd4ml\PD4ML;
Route::get('/invoice/{number}.pdf', function (int $number) {
$pd = new PD4ML();
$pd->readHtmlString(view('invoice', ['number' => $number])->render(), public_path());
return response($pd->writePDF(), 200, ['Content-Type' => 'application/pdf']);
});
// Symfony controller
use Pd4ml\PD4ML;
use Symfony\Component\HttpFoundation\Response;
public function invoice(int $number): Response
{
$pd = new PD4ML();
$pd->readHtmlString($this->renderView('invoice.html.twig', ['number' => $number]),
$this->getParameter('kernel.project_dir') . '/public');
return new Response($pd->writePDF(), 200, ['Content-Type' => 'application/pdf']);
}
5.17 Batch conversion
use Pd4ml\PD4ML;
foreach (glob('*.html') as $source) {
$pd = new PD4ML(); // one converter per document
$pd->readHTML($source);
$pd->writePDF(preg_replace('/\.html$/', '.pdf', $source));
echo "written $source", PHP_EOL;
}
One bridge serves the whole loop. To convert in parallel, run several worker processes (each with its own bridge), or point them all at one bridge server.
5.18 Licensing
use Pd4ml\PD4ML;
use Pd4ml\Runtime;
$pd = new PD4ML('YOUR-SERIAL-NUMBER'); // or a license file URL; or pd4ml.lic in the working dir / classpath
if ($pd->isDemoMode()) {
echo 'unlicensed: output is watermarked', PHP_EOL;
}
echo 'PD4ML ', Runtime::version(), $pd->isPro() ? ' pro' : '', PHP_EOL;
Without a license PD4ML is fully functional but marks its output. See licensing.
6. Tips and hints
- Keep the bridge warm. Under PHP-FPM/mod_php use the bridge server; a per-request Java start costs about a second. CLI scripts and workers pay it once.
- One converter per document.
new PD4ML()is cheap; reuse the process, not the object. - Set the base location for HTML from strings. Missing images and unstyled output are almost always unresolved relative links (details).
- Settings before
readHTML. Page size, headers, fonts and styles apply to the layoutreadHTMLmakes; writes afterwards only choose the output format. - Write several formats from one read. PDF, DOCX and page images from a single
readHTMLcost one layout. - Single quotes for placeholders.
'$[page]'— in double quotes PHP tries to interpolate. - Print CSS works.
@page { size: A4 landscape; margin: 15mm },@media printandpage-break-*/break-*are honoured — often simpler than API calls. - Control the scale with the HTML width. If text is too small or a layout wraps differently than in the browser, set
setHtmlWidthto the width the page was designed for. - Index fonts once with
-configure.fontsinstead of pointinguseTTFat a large unindexed directory on every conversion. - Restrict what documents can load when converting untrusted HTML: see
Constants->PD4ML_ALLOWED_RESOURCE_LOCATIONandPD4ML_DISABLE_EXTERNAL_ATTACHMENTS(viasetParam). - IDE support:
Pd4ml\PD4MLApideclares every Java method ofPD4ML(@method), so completion works on the converter; api.md lists the API of every class. - Choose the build for production: pin it with
vendor/bin/pd4ml install --version=X(or aPD4ML_CLASSPATHto a jar you keep) rather than following the latest release.
7. Troubleshooting
| Symptom | Cause and remedy |
|---|---|
BridgeException: PD4ML not found |
No build configured: run vendor/bin/pd4ml install (as the user PHP runs as), or set PD4ML_CLASSPATH. |
BridgeException: cannot start java / "closed the connection" |
Java is missing or failed: check java -version, set JAVA_HOME or PD4ML_JAVA; PD4ML_BRIDGE_LOG shows Java's output. proc_open must not be in disable_functions. |
BridgeException: cannot connect |
The bridge server is not running, or PD4ML_BRIDGE names another port. |
| Slow first conversion per request | No bridge server under a web server: see 4.2. |
InstallException: the openssl PHP extension is needed |
Enable extension=openssl in php.ini. |
| Images or styles missing | Relative links without a base location, or resources the server cannot reach (proxies, authentication): see setCookie, setHttpOptions. |
| Output is watermarked | No license installed (licensing). |
| Squares instead of characters | The fonts lack those glyphs: provide fonts with useTTF (fonts). |
NoClassDefFoundError: org/bouncycastle/... with setPermissions |
The Bouncy Castle jars are missing: install without --no-bouncycastle, or add them to the classpath. |
| Notice "has no v42 layout engine" | The PD4ML build predates 4.2: the conversion uses its own engine. Use a 4.2 build for v42. |
JavaException: ... NoSuchMethodException |
No Java method of that name takes those argument types — check api.md; pass floats as 10.0, binary data as Bytes. |
8. API reference
PHP classes
| Class | |
|---|---|
PD4ML |
the converter: new PD4ML(?string $license, ?int $htmlWidth, $engine); every Java method of com.pd4ml.PD4ML |
Java |
the PD4ML Java classes: PageSize(), PageMargins(), Units(), Constants(), LayoutEngine(), ErrorPolicy(), PdfSpec(), PdfDocument(), Dimensions(), ProgressListener(), StatusMessage(), ResourceProvider(), CustomTag(), PD4ML(); cls($name); proxy($interface, $callable) |
Pdf |
htmlToPdf($source, $target, $options), open($source, $password), write($doc, $target, $password, $permissions), merge($a, $b, $target) |
Runtime |
version(), install(), configure(), hasLayoutEngines(), toUrl(), pdfSpec() |
Installer |
install($version, $options), installedJar(), installedClasspath(), installedVersion(), availableVersions() |
Bridge |
configure($config), get(), shutdown(), classpath() |
JavaObject, JavaClass |
a Java object / class: methods, fields, ->new() |
Bytes, Output |
binary input / captured output stream |
JavaException, BridgeException, InstallException |
errors |
PD4ML methods with PHP additions
| Method | |
|---|---|
readHTML($source, ?string $baseUrl, ?string $encoding) |
source: path, URL string, Bytes, stream, Java URL/stream |
readHtmlString(string $html, ?string $baseUrl) |
the document as a string |
writePDF($target = null, $spec = null) |
to a path / stream, or returned; spec: PdfSpec or keyword |
writeDOCX($target = null), writeRTF($target = null, bool $rtfWmf = false) |
as writePDF |
renderAsImages($format) / renderPng() |
pages as encoded images (strings) |
monitorProgressWith($listener) |
a PHP callable or a Java ProgressListener |
useHtmlRenderer($engine, ?int $htmlWidth, ?array $params) |
the layout engine by name |
All other methods are those of the Java class com.pd4ml.PD4ML (api.md,
Java API); static ones are called on the class
(PD4ML::getVersion()).
ResourceProvider and CustomTag are extended in Java; register yours with
addCustomResourceProvider / addCustomTagHandler and put its classes on the classpath.
Java interfaces (such as ProgressListener) can be implemented in PHP with Java::proxy().
Examples: resource loaders,
custom tags.
9. Further reading
- PD4ML documentation and the full programmer's manual
