Guides de migration · PHP

Remplacer `wkhtmltopdf` par pdfkiln dans `knp-snappy`

KnpLabs/snappy, la bibliothèque PHP des bundles Symfony et de laravel-snappy, ne fait que lancer une ligne de commande : donnez-lui celle de pdfkiln, et votre code comme vos modèles restent tels quels.

1. Installer pdfkiln

Sur un serveur Linux, prenez le paquet Debian : il apporte les bibliothèques système de Chromium, et ses correctifs avec apt upgrade.

curl -fsS https://apt.pdfkiln.org/pdfkiln-archive-keyring.asc | sudo tee /usr/share/keyrings/pdfkiln-archive-keyring.asc > /dev/null
printf 'Types: deb\nURIs: https://apt.pdfkiln.org\nSuites: stable\nComponents: main\nSigned-By: /usr/share/keyrings/pdfkiln-archive-keyring.asc\n' \
  | sudo tee /etc/apt/sources.list.d/pdfkiln.sources
sudo apt update && sudo apt install pdfkiln

Sur un poste de développement, ou là où le paquet Debian ne convient pas, le paquet Composer place wkhtmltopdf et wkhtmltoimage dans vendor/bin ; le programme est téléchargé au premier usage, SHA-256 vérifié :

composer require pdfkiln/pdfkiln

2. Brancher `knp-snappy` sur pdfkiln

// With the Debian package
$pdf = new Knp\Snappy\Pdf('/usr/bin/wkhtmltopdf');
$image = new Knp\Snappy\Image('/usr/bin/wkhtmltoimage');

// With the Composer package: the program, downloaded on first use
$pdf = new Knp\Snappy\Pdf(Pdfkiln\binary());
$image = new Knp\Snappy\Image(Pdfkiln\binary('wkhtmltoimage'));

3. Vérifier

wkhtmltopdf --version
# wkhtmltopdf 0.12.6 (with patched qt), pdfkiln 1.0.3, Chromium 156.0.8078.73

La réponse commence comme celle de wkhtmltopdf 0.12.6 : les bibliothèques qui lisent la version continuent de fonctionner.

Ce qu’attend `knp-snappy`, et ce que fait pdfkiln

--lowquality, passé à chaque appel, est accepté sans un mot, comme par wkhtmltopdf, ainsi que les autres options sans effet dans Chromium.
knp-snappy ne signale une erreur que sur un code de sortie non nul avec une sortie d’erreur : pdfkiln n’y écrit rien quand tout va bien, et sinon les codes et les messages de wkhtmltopdf.
Sous Windows, PHP n’exécute que les fichiers .exe et .com : knp-snappy refuse donc le .bat que Composer écrit dans vendor/bin, et Pdfkiln\binary() renvoie le programme lui-même.

Testé

La suite de tests de knp-snappy 1.7.3 passe avec pdfkiln à la place de wkhtmltopdf (Ubuntu, job d’intégration continue libraries). Le paquet Composer a été vérifié avec knp-snappy sous Windows 11 et sous Ubuntu 24.04.

Un rendu diffère ? Ouvrez un ticket avec le HTML et les deux PDF : github.com/Jamalofski/pdfkiln/issues. Les différences connues sont listées dans le README.

Remplacer wkhtmltopdf par pdfkiln dans knp-snappy