wkhtmltopdf migration

Migrate Symfony KnpSnappyBundle off wkhtmltopdf

Keep your Symfony PDF service. Point its Snappy setting at Marqius.

Marqius

Four printed variations of a shared document layout

A Symfony app generates statements through its Snappy service. A new container starts fine, but building a statement fails because the service still points at the old program.

Marqius is a drop-in replacement for wkhtmltopdf. Your app can keep using Symfony KnpSnappyBundle to ask for a PDF.

Why this helps

Change the path in the bundle’s settings. The controllers and commands can keep using the same Symfony service, so you can try the switch in one environment first.

Make your first PDF

Start with Invoice 1001 for 120.00 EUR. Open the example PDF to see what this library’s test should produce. The kit includes all 14 sample projects and a more detailed print demo for checking tables and page breaks. Open START-HERE.html after unzipping. Download the library starter kit (ZIP) · Open the library example PDF

With Docker running, unzip the demo to a fresh folder and open a terminal in the folder containing examples/. You can also start in an empty folder. The command in step 3 will fetch the files for you inside the container.

1. Open a fresh test container

Terminal
docker run --rm -it --mount "type=bind,source=$PWD,target=/proof" debian:trixie-slim bash

Run the rest of the steps in the shell that just opened. The container is a fresh Linux test environment. Your host folder is mounted as /proof, so you can open the saved PDF after the test.

2. Install the tools and Marqius

Terminal
apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends ca-certificates curl unzip fonts-dejavu-core poppler-utils php-cli composer php-mbstring php-xml php-curl php-zip php-sqlite3
mkdir -p /work
cd /work
curl -fsSLo install-marqius.sh https://marqius.com/marqius-wkhtmltopdf.sh
bash install-marqius.sh --version 0.12.8 --prefix /work/bin
export PATH="/work/bin:$PATH"
export WKHTMLTOPDF_BINARY=/work/bin/marqius-wkhtmltopdf
export COMPOSER_ALLOW_SUPERUSER=1
"$WKHTMLTOPDF_BINARY" --version
wkhtmltopdf --version

The version output should include marqius-wkhtmltopdf 0.12.8. Marqius supplies the wkhtmltopdf command inside this test container.

3. Bring the demo project into the test container

Terminal
cd /work
if [ -d /proof/examples/knp-snappy-bundle ]; then
  cp -R /proof/examples .
else
  curl -fsSLo wrapper-demos.zip https://marqius.com/download/wkhtmltopdf-demo/0.12.8/marqius-wrapper-demos.zip &&
    unzip -oq wrapper-demos.zip
fi

4. Start a small Symfony app and add the PDF bundle

Terminal
composer create-project 'symfony/skeleton:^7.4' symfony-demo --no-interaction --prefer-dist
cd symfony-demo
composer require symfony/framework-bundle symfony/console symfony/yaml knplabs/knp-snappy-bundle --no-interaction --prefer-dist

5. Add the bundle and the sample command

Terminal
php -r '$file = "config/bundles.php"; $bundles = require $file; $bundles["Knp\\Bundle\\SnappyBundle\\KnpSnappyBundle"] = ["all" => true]; file_put_contents($file, "<?php\nreturn " . var_export($bundles, true) . ";\n");'
mkdir -p config/packages src/Command
cp ../examples/knp-snappy-bundle/config/packages/knp_snappy.yaml config/packages/
cp ../examples/knp-snappy-bundle/src/Command/RenderInvoiceCommand.php src/Command/

6. Run the Symfony invoice command

Terminal
php bin/console marqius:invoice /proof/invoice.pdf

7. Check that the PDF contains the right invoice

Terminal
pdfinfo /proof/invoice.pdf | grep '^Pages:'
pdftotext /proof/invoice.pdf - | grep -F 'Invoice 1001'
pdftotext /proof/invoice.pdf - | grep -F '120.00'
chmod a+r /proof/invoice.pdf

Look for one page, the invoice number and the amount. Type exit to close the test container. Open invoice.pdf in the folder you created on your computer.

How to switch your own app to Marqius

Change knp_snappy.pdf.binary in Symfony's configuration and inject the path through the application environment.

Install Marqius alongside the original. Set WKHTMLTOPDF_BINARY in the application process to the new executable's full path unless the example specifies a framework-specific variable. The Debian APT package installs /usr/bin/marqius-wkhtmltopdf. Debian installation guide · Downloads for other environments

Apply the change in config/packages/knp_snappy.yaml in your Symfony project. Put the binary value under the existing PDF configuration.. Retain the existing rendering options unless your comparison identifies a reason to change them.

yaml
knp_snappy:
    pdf:
        enabled: true
        binary: '%env(WKHTMLTOPDF_BINARY)%'

Try it with a document you know

Run the same Symfony command or controller that produces the production PDF. If this is a fresh project, verify KnpSnappyBundle is enabled in config/bundles.php. A missing Flex recipe can leave the service unregistered.

If Symfony cannot resolve the variable, define it for the process running bin/console or PHP-FPM. Rebuild your production container cache through the normal deployment process and run a proof in that environment.

Check the old and new PDFs

Save a PDF from the old setup. Make it again with the same data and fonts. Check the words, amounts and page breaks. Keep the old program path handy so you can switch back if you need to. The runnable Symfony KnpSnappyBundle example exercises a sample PDF through the wrapper. The developer manual chapter records the test conditions and constraints. The public comparison scoreboard reports differences for the wkhtmltopdf and Marqius renderers.

All 14 library guides · KnpLabs Snappy · Laravel Snappy · Try Marqius for 30 days

Reader questions

Do I need to change the knp_snappy.pdf service call?

The service remains the same. Point its PDF binary configuration at the new executable and keep the consumer code.