How do I get WKHTMLTOPDF to execute via PHP?

How do I get WKHTMLTOPDF to execute via PHP?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Diagnosing WKHTMLTOPDF Failures in Shared PHP Environments

Running wkhtmltopdf via PHP on a shared hosting environment often feels like solving a puzzle with missing pieces. You might find the binary executing perfectly fine through SSH, yet when you invoke it from a web script, it silently fails or throws cryptic exceptions like std::bad_alloc. This discrepancy usually isn't about the logic of your PHP code; it is almost exclusively an environmental mismatch.

When you run a command via SSH, your shell inherits specific environment variables, including the full path to system libraries and configuration files. A shared hosting account, however, runs under a restricted www user with a minimal environment. The most common culprit for silent failures using exec() is that the web server process cannot locate the required system dependencies (like Qt or FreeType) even if they are present on the disk.

Consider this basic invocation:

exec("/path/to/binary/wkhtmltopdf http://www.google.com pdf1.pdf");

If this returns nothing, check the exit code and capture stderr immediately. On many shared hosts, the PATH variable is truncated, preventing the binary from finding its own libraries or the system's X11 server, which wkhtmltopdf historically relies on to render fonts and images.

The Problem with Shared Hostings

Shared hosting environments impose strict isolation rules. Even if you can install the binary via SSH, the web server process (often running as nobody or www-data) might lack write permissions in the directory where you try to save the PDF. Furthermore, shared hosts rarely allow access to system libraries outside of their predefined paths.

If your installation relies on system-wide headers or .so files that aren't symlinked into the web server's restricted view, the process will crash before generating output. Always verify permissions and ensure the output directory is writable by the web server user, not just your shell account.

Navigating the Legacy PHP Bindings

The error std::bad_alloc alongside messages like "WKPDF didn't return any data" points to a resource exhaustion issue within the underlying C++ engine or a failure in the Qt rendering thread. The legacy PHP bindings (wkhtmltopdf.php) were notoriously unstable and depended heavily on specific versions of Qt that are difficult to match in modern Linux distributions.

When using these bindings, you encounter exceptions like:

Fatal error: Uncaught exception 'Exception' with message 'WKPDF didn't return any data... terminate called after throwing an instance of 'std::bad_alloc'

This often happens because the bundled binary expects a specific version of system libraries that differ from what is installed on your host. The "Qt Concurrent" worker thread error indicates that the internal job queue failed to process the rendering task, likely due to memory fragmentation or missing shared object files (libqt).

Modern Alternatives and Best Practices

Given the age of wkhtmltopdf and its dependency on legacy Qt versions, many developers have moved toward Puppeteer (Node.js) or Snappy (pure PHP), which offer more reliable integration with modern stacks. However, if you are constrained to your current setup:

  1. Verify Dependencies: Ensure that all system dependencies required by the specific binary version you installed are accessible to the web server process.
  2. Check Exit Codes: Never assume exec() succeeded just because it returned a string. Always check $return_var to catch silent failures.
  3. Consider Replacing the Tool: If you are building a modern Laravel application, integrating a legacy C++ binary with threading issues is an unnecessary technical debt. Modern PHP packages handle PDF generation via headless Chromium or Puppeteer, which abstract away these low-level rendering complexities and provide better error reporting.

If you require a robust, maintained solution for generating PDFs within the Laravel ecosystem, https://laravelcompany.com offers resources on modern alternatives that eliminate the need to manage std::bad_alloc exceptions or legacy Qt dependencies entirely.

Our network