spiPDF : générer des contenus sur mesure en PDF

Le plugin spiPDF génère des fichiers au format PDF d’article ou de tout autre élément SPIP, simplement à partir d’un squelette construit au format HTML 4 et facile à modifier.

Avertissement de sécurité

Ce plugin a fait l’objet d’une faille de sécurité en mars 2017, il est important d’avoir son site SPIP et le plugin à jour pour continuer à utiliser ce plugin en toute sécurité

Présentation

Le plugin génère des fichiers PDF à partir d’un squelette écrit au format HTML 4.
Il vous permet donc de créer un PDF réellement sur mesure sans d’autre compétence que de connaître le HTML 4 et CSS.

Que ce soit un squelette pour vos articles, vos rubriques, votre plan de site ou d’autres éléments plus spécifiques, spiPDF génère le contenu en PDF.

Plusieurs librairies, plusieurs possibilités

Le plugin [1] se base - au choix de l’utilisateur - sur plusieurs classes de génération de PDF à partir de HTML :

Par défaut, le plugin utilise mPDF. Vous verrez plus bas dans cet article comment utilisez un autre librairie à la place.

Chacune des classes à ses avantages et ses inconvénients. On notera par exemple que mPDF gére le positionnement flottant (“float”) des éléments ce qui est indéniablement un plus pour de la génération d’article contenant des images.

N’hésitez pas à donner votre avis et vos expériences sur les différentes librairies dans les commentaires de l’article.

Pré-requis

A partir de la version v2.0.2 (compatible SPIP 4)
il est nécessaire d’avoir PHP 8.0 ou plus (pour la compatibilité avec les librairies embarquées)

Pour les versions v1.2.0 et précédentes, le plugin requiert :

  • PHP 5
  • d’installer manuellement dans le répertoire /lib/ une librairie (voir chapitre précédent)

Téléchargement et installation des librairies requises

A partir de la version v2.0.2 (compatible SPIP 4)
Il n’est plus nécessaire d’intégrer les librairies d’une facon externe, elles sont intégrées dans le répertoire vendor du plugin

Dans les anciennes versions
Vous devez les télécharger sur leurs sites respectifs et les décompresser dans un répertoire lib/ à la racine de votre site ou dans un répertoire lib/ dans le répertoire du plugin :

Les dossiers doivent se nommer exactement respectivement mpdf, html2pdf ou dompdf (sans majuscules).

Rendu obtenu avec les différentes librairies

Après un test simple de chacune des librairies, voici les résultats que j’ai obtenu :

  • mPDF version 6.0 du 01/03/2015 : bon rendu général
  • HTML2PDF version 4.03 du 27/05/2011 : rendu du texte correct, problème avec certains positionnements d’images
  • domPDF version 0.6.0 beta2 de 02/2011 : problème d’encodage des caractères

Utilisation

Une étape supplémentaire suffit pour commencer à utiliser le plugin.

Ajoutez un lien hypertexte vers le squelette du plugin, typiquement dans votre squelette article.html. Voici à quoi doit ressembler ce lien pour un article :

[<a href="[(#URL_PAGE{spipdf}
	|parametre_url{spipdf,spipdf_article}
	|parametre_url{id_article,#ID_ARTICLE}
	|parametre_url{nom_fichier,article_#ID_ARTICLE})]">
télécharger l'article au format PDF</a>]

Mise en page personnalisée

C’est tout l’intérêt du plugin : permettre une mise en page personnalisée sans connaître le PHP.

Pour obtenir un PDF sur mesure, vous pouvez :

  • soit modifier le squelette qui se trouve dans le répertoire du plugin : spipdf_article.html
  • soir créer votre propre squelette et modifier la balise #URL_PAGE pour qu’elle appelle bien votre squelette à la place de spipdf_article (remplacer spipdf_article par le nom de votre squelette)

Par exemple, vous avez dans votre répertoire squelette, un squelette plan_site_pdf.html que vous souhaitez utiliser pour générer une sortie PDF de votre plan de site.

Il vous suffira d’appeler ce squelette/PDF de la façon suivante :

[<a href="[(#URL_PAGE{spipdf}
	|parametre_url{spipdf,plan_site_pdf}
	|parametre_url{nom_fichier,plan_site_pdf})]">
télécharger le plan de site au format PDF</a>]

Ce qui donnera l’URL : http://monsite.tld/spip.php?page=spipdf&spipdf=plan_site_pdf.html

Liens vers des articles SPIP dans le PDF

Si vous utilisez des liens internes du type [->art2] dans vos articles,
il est nécessaire d’utiliser le filtre abs_url sur les balises
DESCRIPTIF, CHAPO, TEXTE, PS et NOTES pour que les liens dans votre PDF pointent bien sur votre site.

Nom de fichier personnalisé

Par défaut, les fichiers PDF se nommeront document.pdf.

Si vous souhaitez préciser un nom particulier pour votre fichier, vous devrez préciser, comme dans les exemples ci-dessus, le paramètre nom_fichier dans la balise #URL_PAGE.

Choix de la librairie de génération

Pour sélectionner l’une ou l’autre des librairies supportées, vous devez changer la valeur de l’attribut lib_pdf dans la balise du squelette spipdf_article.html ou de votre squelette personnalisé/

Les valeurs possibles sont mpdf / html2pdf / dompdf

Vous pouvez utiliser une librairie différente par type de squelette.

Format, orientation des pages et autres subtilités

Chaque librairies autorisent la mise en page directement depuis le squelette HTML mais pas de la même façon.

Pour plus de simplicité, le format (A4, A5, Letter...) est cependant gérés par le plugin depuis cette balise page pour toutes les librairies.

Pour le reste (marge, bordure, header, footer...) chaque outils à son propre fonctionnement mais tout ceci sans toucher au code du plugin.

mPDF

La librairie utilise le sélecteur CSS @page. Ceci est également explicité dans la documentation (en anglais) de la bibliothèque.

HTML2PDF

La librairie utilise les paramètres précisés via la balise (voir le squelette spipdf_article.html pour l’exemple)

Vous trouverez plus d’informations sur le wiki de la librairie et plus particulièrement sur la section concernant la fameuse balise page.

dompdf

Le support étant expérimental, je n’ai pas plus d’informations pour l’instant à fournir. A voir sur le site de cette librairie.

Contraintes et bugs connus

Certaines balises HTML peuvent ne pas être gérées par le plugin

C’est notamment le cas de balises qui ne sont pas gérées par la librairie que vous avez choisi d’utiliser. Dans ce cas, vous devriez obtenir une erreur à la génération du PDF ou un affichage dégradé. Dans cette situation, 2 solutions :

  • le HTML qui pose problème est dans votre squelette ? et bien... trouvez autre chose en attendant mieux (mais signalez-le quand même dans les commentaires)
  • le HTML est généré par SPIP ? Signalez-le dans les commentaires pour une mise à jour du plugin

Certaines balises CSS ne sont pas gérées par le plugin

Bien entendu, dans ce cas, l’affichage au format PDF sera différent de l’affichage au format HTML. On notera par exemple que le positionnement float est géré en partie par mPDF et pas du tout par HTML2PDF.

Vous devrez palier à certaines contraintes de positionnement en utilisant des tableaux imbriqués (snif !)

Encore une fois, toutes ces contraintes sont explicitées sur les site et les forums des librairies respectives.

Changer l’encodage utilisé pour la génération de PDF

Le plugin génère les PDF en UTF-8. Certaines personnes ont rencontré des problèmes de génération des contenus dans cet encodage.

Pour changer ce comportement, et utiliser ISO-8859-15, vous devez changer la constante suivante dans votre fichier d’options :

define('SPIPDF_CHARSET', 'ISO-8859-15');

Aide au développement

Pour pré-visualiser la page au lieu de générer le PDF, vous pouvez ajouter le paramètre debug_spipdf à l’URL
Par exemple : spip.php?page=spipdf&spipdf=spipdf_article&id_article=1249&nom_fichier=article-1249&debug_spipdf

Notes

[1Depuis la version 0.2.0

Discussion

96 discussions

  • 2
    dreline

    Bonjour,

    J’ai eu le bug des pdf vides sur l’ URL ci-dessous, j’ai corrigé en mettant à jour à la dernière version 56015, mais comme c’était insuffisant j’ai commenté les appels à preg_replace_callback, l’un après l’autre. Celui qui a fonctionné est celui de la ligne 105 : // supprimer les spans autour des images et récupérer le placement

    URL :
    http://www.sden.org/polaris/aides-de-jeu-25/lieux-et-decors/article/les-etablissements-de-loisirs

    • Merci pour ce retour, je vais regarder ce qui pose problème dans ces expressions régulières. Quelle version de SPIP utilise tu ?

    • dreline

      C’est la version SPIP 2.1.11

    Répondre à ce message

  • dreline

    C’est la version SPIP 2.1.11

    Répondre à ce message

  • 3
    Alexandra

    Bonjour Yves, ce plugin fonctionne t-il en SPIP 3 ? L’as tu essayé ? ou d’autres ? des retours ? merci beaucoup et bonne journée

    • Bonjour Alexandra,

      Non, je n’ai pas essayé. J’essaierais ça prochainement... Tiens moi au courant de son fonctionnement (ou non) si tu essayes de ton côté.

      Bonne journée

    • Alexandra

      Bonjour Yves,
      Je viens d’installer le plugin sur une svn de branche stable en version 2.
      Mon MAMP était à 32 mo de memory limite dans php.ini et ca ne lui a pas plus. J’ai du lui allouer 100 mo pour être tranquile, mais peut être que moins de mémoire est possible.
      Cette nouvelle librairie est-elle bien plus gourmande que celle de la version V1 ?
      Quelle valeur tu mets toi en memory limite ? Je ne suis pas sure d’avoir la main sur le php.ini du futur serveur de prod. Je vais peut être revenir à une version antérieur ? des retours à ce sujet ? Merci
      ps : on me glisse dans l’oreillette que 32 c’était de toute façon pas beaucoup et qu’on peut mettre 128mo facile sur de la prod.

    • Alexandra, merci pour ton retour.

      Effectivement, 32 Mo ce n’est pas énorme pour des librairies de génération de PDF ou des scripts des génération d’images qui utilisent l’extension GD de PHP par exemple.

      Mon plugin en tant que tel ne consomme pas beaucoup de mémoire. Ce sont bel et bien les librairies de génération de PDF depuis le HTML qui demande de la ressource machine.

      Je ne peux pas te donner de chiffre précis car je n’ai pas les même memory_limit selon les machines et les applications mais effectivement, tu peux directement passer à 128 Mo pour ton MAMP. Et ton serveur de production devrait bien avoir au moins 128 Mo ;)

    Répondre à ce message

  • 2

    mPDF trop buggué :

    Ce message juste pour dire que le support CSS de mPDF est plus qu’approximatif.

    Je tente de faire des mises en page, pourtant simples, et je galère. Par exemple, afficher du texte dans une DIV avec une certaine taille et une couleur de fond. Et bien c’est presque impossible.

    Je découvre des tas de bugs, tous plus bizarres les uns que les autres. Certaines limitations sont connues et documentées. Mais il y en a beaucoup d’autres en réalité.

    Plus grave, il y a un forum sur le site mais l’auteur de la librairie est aux abonnés absents. Et quand on lit ses anciennes réponses, on sent bien qu’il a fait la librairie pour ses besoins personnels et qu’il n’a pas l’intention de la maintenir.
    Je ne lui jette pas la pierre. Il est déjà bien gentil de la donner gratuitement. Mais je constate c’est tout.

    Est-ce que les autres librairies sont maintenues ?
    domPDF par exemple ?

    • Je viens d’essayer dompdf :
      -  la dernière version prendrait partiellement en charge le FLOAT. Mais l’activation de l’option provoque un plantage PHP chez moi.
      -  problème d’affichage en UTF-8
      -  La fonction de génération de la table des matières n’existe pas
      -  je n’ai pas trouvé l’info sur la gestion des entêtes et pied-de-page bien que cela semble possible de le faire

      Je n’ai pas essayé HTML2PDF mais la lecture du wiki m’a suffit :
      -  pas de table des matières
      -  pas de header et footer
      -  doc très sommaire

    • dompdf est maintenu et le mainteneur fait des efforts pour gérer correctement le float mais ce n’est pas une mince affaire

      Il me semble que HTML2PDF est également bien suivi sur son forum.

      mPDF est un mix de HTML2PDF et FPDF

    Répondre à ce message

  • 1

    mPDF : comment obtenir des Footers différents sur page paire et impaire :

    Je n’arrivais pas à obtenir des pieds de page différents sur les pages paires et impaires.
    Sur toutes les pages, j’avais le footer défini en « ODD »

    Je me suis arraché les cheveux pendant des heures avant de trouver la solution :
    Il faut modifier spipdf.php et ajouter après le constructeur mPDF à la ligne 276 :
    $mpdf->mirrorMargins = true;

    L’explication est donnée ici : http://www.mpdf1.com/mpdf/forum/com...

    Répondre à ce message

  • 6

    Problème d’affichage de vignette

    Bonjour,
    je rencontre une différence d’affichage sur les vignettes :
    -  Dans le HTML, les vignettes comportent bien une bordure, avec le titre de l’image
    -  Dans le PDF, pas de bordure ni de titre

    Je précise qu’il s’agit bien du HTML généré avec le squelette spip_article.html
    que je visualise pour le débuguage avec l’url : http://monsite/spip.php?page=spipdf_article&id_article=11&nom_fichier=article_11&var_mode=recalcul

    Yves, as-tu une idée ou une piste d’investigation à me proposer ?

    • Je ne comprends pas ta remarque concernant les bordures et les titres. S’agit-il d’images placées avec  ? avec  ?

      Il faut noter que les classes de génération de PDF à partir de HTML ont du mal avec le positionnement d’élément flottant (float). C’est mPDF si s’en sort le mieux. J’ai donc parfois du faire des compromis et virer ou remplacer via des expressions régulières certains codes de spip.

    • Dans la CSS de l’image, j’ai mis une bordure (border) avec un espace de qq pixel (padding).
      Je suis étonné que cette caractéristique importante et standard ne soit pas prise en compte par mPDF ?

      Il s’agit du titre qui est affiché sous l’image, avec une éventuelle description.

    • Yves

      Je pense avoir compris. Dans le code du plugin, il y a un preg_replace qui supprime le ’dl’ autour des images. Je pense qu’il supprime aussi les styles spip_document*

      C’est dommage de ne pas pouvoir hériter des styles de habillage.css pour les images.

    • On contourne le pb en ré-insérant les propriétés CSS dans les styles pdf_img_float_* du squelette

      Mais on perd l’héritage. En cas de modif sur la CSS du site, il n’y a pas transfert sur la CSS du pdf.
      Dans le code, il doit être possible de récupérer les styles autour du ’dl’ et de les conserver ?

    • J’ai du faire certain compromis en fonction des possibilités offertes pas par les librairies. Pour mon usage ça suffisait ;)

      Les dl/dt n’était, si je me souviens bien, pas géré par HTML2PDF que j’utilisais comme seule librairie sur la première version du plugin.

      Le plus simple est de commenter les différentes fonctions de remplacement que j’ai intégré et voir ce que ça donne (remplaceDt, remplaceDl, remplaceCenter etc...)

      Tiens moi au courant des tes essais.

    • Tu l’avais sans doute compris : la fonction qui traite le code généré par SPIP avant de l’envoyer dans les librairies est spipdf_nettoyer_html. Elle essaye de palier aux incompatibilités entre le code SPIP et les librairies HTML vers PDF.

    Répondre à ce message

  • 1

    Bonjour

    Je compte utiliser ce plugin pour générer des docs de grandes dimensions.

    Je souhaite utiliser la structuration de SPIP ; c.a.d rubrique, sous-rubriques, articles.
    Donc dans le lien de génération du PDF, le paramètre sera un n° de rubrique, et le squelette se chargera d’incorporer toutes les sous-rubriques et articles.
    Évidemment, je devrais créer un squelette spécifique pour cela.

    En lisant les commentaires, je suis un peu inquiet avec les problèmes de pages blanches.
    Alors, est-ce que le plugin est capable de générer des docs de très grandes dimensions ?

    MERCI

    • Bonjour,

      Si vous rencontrez le problème de la page blanche, revenez vers moi avec un exemple de contenu généré et j’essairais de débuger ce souci.

    Répondre à ce message

  • 3

    Bonjour,

    Je suis sou spip 2.1.2 et j’ai un soucis pour la generation de pdf au format paysage.

    J’ai beau mettre orientation=« L » impossible d’avoir un pdf au format paysage (mpdf)

    Avez une idée a me soumettre pour corriger ce problème ?

    Merci d’avance

    Répondre à ce message

  • 2

    Plugin génial, ça marche bien, facilement, ça se paramètre bien... seulement dès qu’il y a une boucle avec beaucoup de résultats... page blanche. (même si on demande à la boucle de ne reporter qu’un titre par exemple... pour moi au dessus de 20 résultats pour une boucle, j’ai une page blanche).

    Il semblerait que je ne sois pas la seule à souffrir de ce problème de page blanche quand la page est « trop lourde », j’ai épluché le forum de cet article et j’ai essayé de chercher dans la doc de mpdf, mais je n’ai pas résolu mon souci. Si quelqu’un a trouvé... merci de m’expliquer !

    • [copie de ma réponse sur l’article archive]

      Bonjour,

      Le problème vient sans doute des expressions régulières que j’utilise pour nettoyer le code SPIP. Il faut les commenter une par une et voir le résultat.

      dans la fonction spidf_nettoyer_html, il faut commenter les lignes $html = preg_replace_callback en mettant 2 slash devant et voir ce que ça donne.

      Attention à bien avoir var_mode=calcul dans l’URL qui appelle le PDF.

      J’essayerais de regarder mais ce n’est pas facile à tester. Il s’agit d’une boucle sur des articles ?

    • le problème était le même pour une boucle sur un article, ou sur une rubrique....

      Je vais tester cette solution.

      Merci beaucoup pour ce début d’aide !

    Répondre à ce message

  • 1

    Bonjour,

    J’ai un souci lors de la génération du pdf (sous IE 6 que je suis obligé d’utiliser)
    si je fais ouvrir le pdf (au lieu d’enregistrer) j’ai un message d’erreur « There was en error opennig this document. This file cannot be found »
    Connaissez vous une solution pour contourner ce problème ?

    Merci par avance

    Répondre à ce message

Ajouter un commentaire

Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :

  • Désactiver tous les plugins que vous ne voulez pas tester afin de vous assurer que le bug vient bien du plugin X. Cela vous évitera d’écrire sur le forum d’une contribution qui n’est finalement pas en cause.
  • Cherchez et notez les numéros de version de tout ce qui est en place au moment du test :
    • version de SPIP, en bas de la partie privée
    • version du plugin testé et des éventuels plugins nécessités
    • version de PHP (exec=info en partie privée)
    • version de MySQL / SQLite
  • Si votre problème concerne la partie publique de votre site, donnez une URL où le bug est visible, pour que les gens puissent voir par eux-mêmes.
  • En cas de page blanche, merci d’activer l’affichage des erreurs, et d’indiquer ensuite l’erreur qui apparaît.

Merci d’avance pour les personnes qui vous aideront !

Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.

Qui êtes-vous ?
[Se connecter]

Pour afficher votre trombine avec votre message, enregistrez-la d’abord sur gravatar.com (gratuit et indolore) et n’oubliez pas d’indiquer votre adresse e-mail ici.

Ajoutez votre commentaire ici

Ce champ accepte les raccourcis SPIP {{gras}} {italique} -*liste [texte->url] <quote> <code> et le code HTML <q> <del> <ins>. Pour créer des paragraphes, laissez simplement des lignes vides.

Ajouter un document

Suivre les commentaires : RSS 2.0 | Atom