X. ClibPDF

ClibPDF vous permet de créer des documents PDF avec PHP. Cette librairie est disponible à FastIO mais n'est pas gratuite. Vous devez lire la licence avant de l'utiliser. Si vous ne pouvez pas accepter la licence, essayez plutôt pdflib de Thomas Merz, qui est aussi très puissante. Les fonctionnalités de ClibPDF et ses API sont très similaires à celles de Thomas Merz's pdflib mais, selon FastIO, ClibPDF est plus rapide, et crée des documents plus compacts. Cela peut avoir changé depuis la version 2.0 de pdflib. Un test de vitesse (avec pdfclock.c issue des exemples de pdflib 2.0 transformé en script PHP) ne montre aucune différence de vitesse. La taille des fichiers est similaire si la compression n'est pas utilisée. Il vaut mieux alors essayer les deux, et choisir celui qui vous convient le mieux.

Cette documentation devrait être lue avec le manuel ClibPDF sous la main, car il est beaucoup plus détaillé.

Beaucoup de fonctions sont natives de ClibPDF et se retrouvent dans le module PHP, et tout comme pdflib, elles ont le même nom. Toutes les fonctions, hormis cpdf_open() utilisent un pointeur sur un document comme premier paramètre. Actuellement, ce pointeur n'est pas utilisé en interne, car ClibPDF ne supporte pas la création de plusieurs documents PDF simultanément. En fait, il ne vaut mieux pas l'envisager, car les résultats sont aléatoires. Je ne veux même pas imaginer les problèmes qui pourrait se poser avec les environnements multi-tâches. Selon l'auteur de ClibPDF, cette situation va changer dans les prochaînes versions (lorsque cette documentation a été traduite, c'était la version 1.10). Si vous avez besoin de cette fonctionnalité, utilisez pdflib.

Note : La fonction cpdf_set_font() a changé depuis le PHP 3.0 pour supporter les polices asiatiques. Le paramètre d'encodage n'est plus un entier, mais une chaîne.

Un des gros avantage de ClibPDF sur pdflib est la possibilité de créer complétement un document sans passer par des fichiers temporaires. Il est aussi possible d'utiliser des coordonnées avec une unité de longeur prédéfinie. C'est une fonctionnalité bien pratique mais qui peut être simulée avec pdf_translate().

Un autre atout de ClibPDF est que chaque page peut être modifiée à tout moment même si une nouvelle page a été ouverte. La fonction cpdf_set_current_page() vous permet de quitter temporairement une page, et d'en modifier une autre.

La plus part des fonctions sont très simples d'emploi. Le plus difficile est probablement de créer un document PDF simple. L'exemple suivant devrait vous aider à démarrer. La page contient du texte qui utilise la police "Times-Roman" en taille 30, outlined. Le texte est souligné.

Exemple 1. Exemple simple ClibPDF


<?php
$cpdf = cpdf_open(0);
cpdf_page_init($cpdf, 1, 0, 595, 842);
cpdf_add_outline($cpdf, 0, 0, 0, 1, "Page 1");
cpdf_set_font($cpdf, "Times-Roman", 30, "WinAnsiEncoding");
cpdf_set_text_rendering($cpdf, 1);
cpdf_text($cpdf, "Times Roman outlined", 50, 750);
cpdf_moveto($cpdf, 50, 740);
cpdf_lineto($cpdf, 330, 740);
cpdf_stroke($cpdf);
cpdf_finalize($cpdf);
Header("Content-type: application/pdf");
cpdf_output_buffer($cpdf);
cpdf_close($cpdf);
?>
    

La distribution pdflib contient un exemple plus complet, qui crée des séries de pages avec une horloge. Voici cet exemple convertit en script PHP qui utilise l'extension ClibPDF :

Exemple 2. Exemple pdfclock de la distribution pdflib 2.0


<?php
$radius = 200;
$margin = 20;
$pagecount = 40;
$pdf = cpdf_open(0);
cpdf_set_creator($pdf, "pdf_clock.php3");
cpdf_set_title($pdf, "Analog Clock");
while($pagecount-- > 0) {
  cpdf_page_init($pdf, $pagecount+1, 0, 2 * ($radius + $margin), 2 * ($radius + $margin), 1.0);
  cpdf_set_page_animation($pdf, 4, 0.5, 0, 0, 0);  /* wipe */
  cpdf_translate($pdf, $radius + $margin, $radius + $margin);
  cpdf_save($pdf);
  cpdf_setrgbcolor($pdf, 0.0, 0.0, 1.0);
  /* indications des minutes */
  cpdf_setlinewidth($pdf, 2.0);
  for ($alpha = 0; $alpha < 360; $alpha += 6)
    {
    cpdf_rotate($pdf, 6.0);
    cpdf_moveto($pdf, $radius, 0.0);
    cpdf_lineto($pdf, $radius-$margin/3, 0.0);
    cpdf_stroke($pdf);
    }
  cpdf_restore($pdf);
  cpdf_save($pdf);
  /* Indications des 5 minutes */
  cpdf_setlinewidth($pdf, 3.0);
  for ($alpha = 0; $alpha < 360; $alpha += 30)
  {
    cpdf_rotate($pdf, 30.0);
    cpdf_moveto($pdf, $radius, 0.0);
    cpdf_lineto($pdf, $radius-$margin, 0.0);
    cpdf_stroke($pdf);
  }
  $ltime = getdate();
  /* aiguille des heures */
  cpdf_save($pdf);
  cpdf_rotate($pdf, -(($ltime['minutes']/60.0) + $ltime['hours'] - 3.0) * 30.0);
  cpdf_moveto($pdf, -$radius/10, -$radius/20);
  cpdf_lineto($pdf, $radius/2, 0.0);
  cpdf_lineto($pdf, -$radius/10, $radius/20);
  cpdf_closepath($pdf);
  cpdf_fill($pdf);
  cpdf_restore($pdf);
  /* aiguille des minutes */
  cpdf_save($pdf);
  cpdf_rotate($pdf, -(($ltime['seconds']/60.0) + $ltime['minutes'] - 15.0) * 6.0);
  cpdf_moveto($pdf, -$radius/10, -$radius/20);
  cpdf_lineto($pdf, $radius * 0.8, 0.0);
  cpdf_lineto($pdf, -$radius/10, $radius/20);
  cpdf_closepath($pdf);
  cpdf_fill($pdf);
  cpdf_restore($pdf);
  /* aiguille des secondes */
  cpdf_setrgbcolor($pdf, 1.0, 0.0, 0.0);
  cpdf_setlinewidth($pdf, 2);
  cpdf_save($pdf);
  cpdf_rotate($pdf, -(($ltime['seconds'] - 15.0) * 6.0));
  cpdf_moveto($pdf, -$radius/5, 0.0);
  cpdf_lineto($pdf, $radius, 0.0);
  cpdf_stroke($pdf);
  cpdf_restore($pdf);
  /* Un petit cercle au centre */
  cpdf_circle($pdf, 0, 0, $radius/30);
  cpdf_fill($pdf);
  cpdf_restore($pdf);
  cpdf_finalize_page($pdf, $pagecount+1);
}
cpdf_finalize($pdf);
header("Content-type: application/pdf");
cpdf_output_buffer($pdf);
cpdf_close($pdf);
?>
   
Table des matières
cpdf_global_set_document_limits -- Fixe les limites d'un document PDF.
cpdf_set_creator -- Fixe le créateur d'un document PDF.
cpdf_set_title -- Fixe le titre d'un document PDF.
cpdf_set_subject -- Fixe le sujet d'un document PDF.
cpdf_set_keywords -- Fixe les mot clés d'un document PDF.
cpdf_open -- Ouvre un nouveau document PDF.
cpdf_close -- Ferme un fichier PDF.
cpdf_page_init -- Commence une nouvelle page.
cpdf_finalize_page -- Termine une page.
cpdf_finalize -- Termine un document.
cpdf_output_buffer -- Envoie le document PDF dans un buffer mémoire.
cpdf_save_to_file -- Ecrit un document PDF dans un fichier.
cpdf_set_current_page -- Fixe la page courante.
cpdf_begin_text -- Démarre une section de texte.
cpdf_end_text -- Termine une section de texte.
cpdf_show -- Imprime un texte à la position courante.
cpdf_show_xy -- Affiche un texte à une position.
cpdf_text -- Imprime un texte avec des options.
cpdf_set_font -- Sélectionne la police courante et sa taille.
cpdf_set_leading -- Fixe la distance entre deux lignes.
cpdf_set_text_rendering -- Détermine le rendu du texte.
cpdf_set_horiz_scaling -- Fixe l'échelle horizontale du texte.
cpdf_set_text_rise -- Fixe l'élévation du texte.
cpdf_set_text_matrix -- Fixe la matrice du texte.
cpdf_set_text_pos -- Fixe la position du texte.
cpdf_set_char_spacing -- Fixe l'espacement des caractères.
cpdf_set_word_spacing -- Fixe l'espacement des mots.
cpdf_continue_text -- Imprime le texte à la ligne suivante.
cpdf_stringwidth -- Retourne la taille de la chaîne.
cpdf_save -- Sauve l'environnement courant.
cpdf_restore -- Restaure un environnement.
cpdf_translate --  Modifie l'origine du système de coordonées.
cpdf_scale -- Modifie l'échelle.
cpdf_rotate -- Effectue une rotation.
cpdf_setflat -- Fixe la platitude (flatness).
cpdf_setlinejoin -- Fixe le paramètre linejoin.
cpdf_setlinecap -- Fixe le paramètre linecap.
cpdf_setmiterlimit -- Fixe le paramètre miter limit.
cpdf_setlinewidth -- Fixe la largeur de ligne.
cpdf_setdash -- Fixe le motif de pointillé.
cpdf_newpath -- Commence un nouveau chemin
cpdf_moveto -- Fixe le point courant.
cpdf_rmoveto -- Fixe le point courant relativement.
cpdf_curveto -- Dessine une courbe.
cpdf_lineto -- Dessine une ligne.
cpdf_rlineto -- Dessine une ligne, relativement.
cpdf_circle -- Dessine un cercle.
cpdf_arc -- Dessine un arc de cercle.
cpdf_rect -- Dessine un rectangle.
cpdf_closepath -- Ferme le chemin.
cpdf_stroke -- Dessine une ligne le long du chemin.
cpdf_closepath_stroke --  Ferme le fichier et dessine une ligne le long du chemin.
cpdf_fill -- Remplit le chemin courant.
cpdf_fill_stroke -- Remplit le chemin, et dessine le bord.
cpdf_closepath_fill_stroke -- Remplit le chemin, dessine le bord et ferme le chemin.
cpdf_clip -- Aligne les dessins sur le chemin courant.
cpdf_setgray_fill --  Modifie le niveau de gris comme couleur de remplissage.
cpdf_setgray_stroke -- Choisit un niveau de gris comme couleur de dessin.
cpdf_setgray --  Modifie un niveau de gris comme couleur de dessin et de remplissage.
cpdf_setrgbcolor_fill -- Choisit une couleur rgb comme couleur de remplissage.
cpdf_setrgbcolor_stroke -- Choisit une couleur rgb comme couleur de dessin.
cpdf_setrgbcolor --  Choisit une couleur rgb comme couleur de dessin et de remplissage.
cpdf_add_outline -- Ajoute un signet à la page courante.
cpdf_set_page_animation -- Fixe l'animation de la transition entre les pages.
cpdf_import_jpeg -- Ouvre une image JPEG.
cpdf_place_inline_image -- Place une image dans la page.
cpdf_add_annotation -- Ajoute une annotation.