Aller au contenu

Conversion des documents en PDF

Objectif de cette page

Expliquer comment et pourquoi Maarch Courrier convertit les documents en PDF.

L’objectif est de comprendre :

  • Pourquoi plusieurs outils de conversion sont utilisés.
  • Comment Maarch Courrier choisit l’outil adapté.
  • Ce qui se passe selon le type de document d’origine.
  • Quelles sont les conséquences pour les utilisateurs et les intégrateurs.

Contexte : pourquoi convertir en PDF ?

Dans Maarch Courrier, le PDF est le format de référence pour :

  • La consultation homogène des documents.
  • Les échanges avec des services externes (signature, archivage, etc.).
  • La pérennité et l’impression.

Les documents sources peuvent être de formats très variés, selon le paramétrage des extensions autorisé dans config/extensions.xml : HTML, Word, LibreOffice, Excel, etc. La conversion en PDF est donc une étape clé pour garantir une expérience cohérente côté utilisateur et faciliter les traitements.

Principe général de la conversion

La logique de conversion repose sur une idée simple :

Le type de fichier d’origine (son extension) détermine la stratégie de conversion utilisée.

Trois grandes situations se présentent :

  1. Le document est une page HTML (extensions html ou htm).
  2. Le document est d’un autre format bureautique (Word, LibreOffice, Excel, etc.).
  3. Le document est déjà au format PDF.

En fonction de ce cas, Maarch Courrier va :

  • soit appeler un outil spécialisé (wkhtmltopdf),
  • soit tenter une conversion via OnlyOffice,
  • soit utiliser LibreOffice en « solution de repli »,
  • soit ne rien faire si ce n’est pas nécessaire.

Cas n°1 : documents HTML (html / htm)

Pourquoi un traitement spécifique ?

Les documents HTML représentent des contenus destinés à être affichés dans un navigateur. Pour les convertir en PDF, il faut un rendu « comme dans un navigateur », en tenant compte :

  • du HTML,
  • du CSS,
  • éventuellement de ressources externes (images, polices, etc.).

Outil utilisé : wkhtmltopdf

Maarch Courrier s’appuie sur wkhtmltopdf, un outil spécialisé dans la conversion de pages HTML en PDF.

Quelques points importants :

  • wkhtmltopdf gère le rendu des pages web avec des marges standardisées.
  • L’encodage est forcé en UTF-8 pour limiter les problèmes de caractères.
  • Certaines erreurs de chargement de ressources (images, CSS externes) sont ignorées pour éviter l’échec complet de la conversion à cause d’un élément secondaire manquant.

Environnements « headless »

Sur les serveurs Linux sans interface graphique (cas très fréquent en production), wkhtmltopdf a besoin d’un environnement d’affichage simulé.

Pour cela :

  • Si l’outil xvfb-run est disponible, il est utilisé pour simuler un affichage graphique.
  • Sinon, Maarch Courrier suppose qu’un display est disponible et configure l’environnement en conséquence.

L’idée est de rendre la conversion HTML → PDF robuste, même sur des serveurs dépourvus d’interface graphique.

Cas n°2 : autres documents non PDF (Word, LibreOffice, etc.)

Pourquoi utiliser plusieurs outils ?

Les formats bureautiques (Word, ODT, Excel, etc.) sont variés et évolutifs. Aucun outil unique ne garantit une conversion parfaite dans tous les cas. Maarch Courrier adopte donc une stratégie en deux étapes :

  1. Utiliser un service dédié (OnlyOffice) si possible.
  2. Basculer sur LibreOffice en cas d’échec ou d’indisponibilité.

Cela permet de profiter du service OnlyOffice lorsqu’il est disponible, et de basculer automatiquement sur LibreOffice, l’outil fourni avec Maarch Courrier.

Étape 1 : tentative de conversion avec OnlyOffice

Quand le document n’est ni HTML ni PDF, la première tentative passe par OnlyOffice :

  • Maarch Courrier vérifie si OnlyOffice est en mesure de gérer le fichier.
  • Si oui, il lui confie la conversion en PDF.

Deux scénarios possibles :

  • Conversion réussie. Maarch Courrier enregistre le succès dans les logs et indique un retour sans erreurs.
  • Conversion impossible ou échouée. Maarch Courrier enregistre un message d’erreur dans les logs, mais ne s’arrête pas là : il bascule automatiquement sur un autre outil.

Étape 2 : solution de repli avec LibreOffice

Si OnlyOffice ne peut pas être utilisé, Maarch Courrier passe à LibreOffice :

  • Le document est éventuellement pré-traité pour limiter les problèmes d’encodage.
  • LibreOffice est exécuté en mode « headless » (sans interface graphique) pour convertir le fichier en PDF.

Un délai maximum est imposé à cette conversion pour éviter que LibreOffice ne reste bloqué sur un document problématique : au-delà d’un certain temps, la commande est interrompue.

Cette approche garantit une résilience : même si le service OnlyOffice est indisponible, la conversion PDF reste possible.

Cas n°3 : documents déjà au format PDF

Si le document fourni est déjà un PDF :

  • Maarch Courrier ne lance aucune conversion.
  • Le fichier est considéré comme déjà dans le format cible.

C’est un comportement volontaire :

Il est inutile de retraiter un PDF qui est déjà dans le format attendu.

Résultats et interprétation

À l’issue du processus, la logique de conversion peut aboutir à plusieurs situations :

  • Conversion réussie via wkhtmltopdf (HTML → PDF).
  • Conversion réussie via OnlyOffice (formats bureautiques) — cas privilégié.
  • Conversion réussie via LibreOffice (fallback si OnlyOffice est indisponible ou en échec).
  • Aucune conversion effectuée pour les documents déjà en PDF.
  • Échec de conversion si tous les outils sollicités échouent (erreur sur le fichier, format non supporté, problème d’outil, etc.).

Implications pour les utilisateurs et intégrateurs

  • Les utilisateurs n’ont pas à choisir l’outil de conversion : Maarch Courrier sélectionne automatiquement la méthode la plus adaptée selon le type de document.

  • Les intégrateurs doivent s’assurer que :

    • wkhtmltopdf est disponible pour les conversions HTML. Normalement livré dans l'image Docker.
    • OnlyOffice est correctement configuré s’ils souhaitent bénéficier de conversions pour les formats bureautiques.
    • LibreOffice est installé pour servir de solution de repli. Normalement livré dans l'image Docker.

En cas de problème de conversion, les logs constituent la source principale d’information pour comprendre l’outil utilisé et la cause probable de l’échec.