Keywords: WkHTMLtoPDF | local resource loading | filesystem paths
Abstract: This article addresses the common problem of WkHTMLtoPDF failing to load local CSS and images when converting HTML to PDF, based on the best practice answer. It first explores the root causes, highlighting the fundamental differences between WkHTMLtoPDF as a command-line tool and browsers in handling file paths. Through systematic testing of various path formats (e.g., relative paths, absolute paths, and file:// protocol), the reliability of using direct filesystem absolute paths is validated. Additionally, the article supplements with alternative solutions, such as using the <base> tag to set a base URL or embedding Base64-encoded images, and emphasizes the impact of operating system environments (e.g., Linux file permissions). Finally, complete code examples and configuration recommendations are provided to help developers thoroughly resolve this technical challenge.
Problem Background and Root Cause Analysis
When using WkHTMLtoPDF to convert HTML files to PDF, developers often encounter issues where local CSS and images fail to load. This typically stems from differences in how WkHTMLtoPDF operates compared to standard browsers. Browsers request resources via HTTP protocols, while WkHTMLtoPDF, as a command-line tool, accesses the filesystem directly. Resource loading failures are particularly common when server environments have firewall restrictions or improper path configurations.
Systematic Testing of Path Formats
Based on best practices, we conducted comprehensive testing of various path formats. In a Linux environment using WkHTMLtoPDF version 0.12.2.1 (with patched Qt), the following paths successfully loaded images:
- Using the
file://protocol:<img src="file:///var/www/testpdf/flowers.jpg"> - Relative path:
<img src="./flowers.jpg"> - Simple filename:
<img src="flowers.jpg"> - Absolute filesystem path:
<img src="/var/www/testpdf/flowers.jpg">
In testing, no command-line arguments were used, only the basic command: wkhtmltopdf /var/www/testpdf/makepdf.html makepdf.pdf. The results show that providing direct filesystem absolute paths is most reliable, as it avoids ambiguities in protocol or relative path resolution.
Supplementary Solutions and Considerations
Other answers provide valuable supplements. For example, adding a <base> tag in the HTML <head> section to set a base URL: <base href="http://www.example.com/">, which helps unify resource paths but may be affected by firewalls. For images, embedding Base64-encoded data: <img src="data:image/png;base64,someBase64content"> completely avoids external file dependencies but increases HTML size.
In Windows systems, absolute filesystem paths must be used, such as: <link href='C:\Projects\Hello\Hello.Web\Content\custom\home.css' rel='stylesheet' type='text/css' />, rather than http://localhost paths. Additionally, file permissions should be checked to ensure the WkHTMLtoPDF process has read access.
Code Examples and Best Practices
Below is a complete PHP example demonstrating how to generate HTML with local resources and convert it to PDF:
<?php
// Generate temporary HTML file
$htmlContent = '<!DOCTYPE html>
<html>
<head>
<title>Quote PDF</title>
<link href="/var/www/mysite/assets/css/style.css" rel="stylesheet">
</head>
<body>
<h1>Customer Quote</h1>
<img src="/var/www/mysite/temp/image.jpg" alt="Example Image">
<p>Quote details here.</p>
</body>
</html>';
$tempFile = '/var/www/mysite/temp/quote_' . uniqid() . '.html';
file_put_contents($tempFile, $htmlContent);
// Convert using WkHTMLtoPDF
$pdfFile = '/var/www/mysite/temp/quote.pdf';
$command = "wkhtmltopdf --enable-local-file-access " . escapeshellarg($tempFile) . " " . escapeshellarg($pdfFile);
exec($command, $output, $returnCode);
if ($returnCode === 0) {
header('Content-Type: application/pdf');
readfile($pdfFile);
} else {
echo "PDF conversion failed.";
}
// Clean up temporary files
unlink($tempFile);
if (file_exists($pdfFile)) {
unlink($pdfFile);
}
?>In this code, CSS and image paths use absolute filesystem paths, and the --enable-local-file-access parameter is added to ensure local file access. This resolves firewall restrictions, as resources are loaded directly from the filesystem instead of via network requests.
Summary and Recommendations
The key to solving WkHTMLtoPDF local resource loading issues lies in understanding its filesystem access mode. Prioritize using absolute filesystem paths and consider environmental factors such as operating system and file permissions. For complex scenarios, combine with the <base> tag or Base64 encoding as alternatives. Through systematic testing and proper configuration, developers can efficiently generate PDF documents with rich resources.