CXIX. Fonctions PDF

Introduction

Les fonctions PDF permettent de créer des fichiers PDF en utilisant la bibliothèque PDFlib créée initialement par Thomas Merz et qui est actuellement maintenue par PDFlib GmbH.

La documentation de cette section est uniquement destinée à être une introduction aux fonctions disponibles, et ne doit pas être considérée comme une référence exaustive. Reportez-vous à la documentation incluse dans la distribution de PDFlib pour plus de détails et d'explications. Elle fournit une excellente référence des capacités de PDFlib, et contient la documentation la plus à jour.

Pour commencer, nous vous conseillons de regarder du côté des exemples fournis avec le paquet PDFlib. Ces exemples montrent la création d'un texte simple, de vecteurs ou encore de graphiques, en passant par l'utilisation de fonctions hauts niveaux comme PDI.

Toutes les fonctions de la PDFlib et du module PHP ont des noms et des arguments identiques. Vous aurez à comprendre quelques concepts basiques de PDF et PostScript pour l'utiliser efficacement. Toutes les longueurs et coordonnées sont mesurées en points PostScript. Il y a généralement 72 points PostScript pour faire un pouche (2.54 cm), mais cela dépend de la résolution de sortie. Reportez-vous au manuel de référence PDFlib inclus dans la distribution de PDFlib pour plus de détails sur le système de coordonnées.

Avec la version 6, PDFlib offre une API orientée objet pour PHP 5 en plus de l'API orientée fonctions pour PHP 4. Voici les plus grandes différences :

En PHP 4, tout d'abord, une ressource PDF doit être récupérée avec l'appel à une fonction comme

$p = PDF_new();

Cette ressource PDF est utilisée en tant que premier paramètre dans tous les prochains appels de fonctions, comme dans

PDF_begin_document($p, "", "").

En PHP 5, un objet PDFlib est créé plutôt avec

$p = new PDFlib().

Cet objet offre toutes les fonctions de l'API PDFlib en tant que méthodes, par exemple avec

$p->begin_document("", "").

En plus, les exceptions ont été introduites en PHP 5 qui sont supportées dans la version 6 ou supérieure de la PDFlib.

Lisez les exemples ci-dessous pour plus d'informations.

Note : Si vous êtes intéressé par des alternatives gratuites pour générer des PDF, sans passer par des bibliothèques PDF, reportez-vous à cette entrée de la FAQ.

Pré-requis

PDFlib Lite est disponible en tant qu'open source. Cependant, la license de PDFlib Lite permet l'utilisation libre sous certaines conditions. PDFlib Lite supporte une partie des fonctionnalités de PDFlib ; reportez-vous au site web de PDFlib pour plus de détails. La version complète de PDFlib est disponible en téléchargement sur http://www.pdflib.com/products/pdflib-family/, mais impose l'achat d'une license pour l'utiliser commercialement.

Problèmes avec les anciennes versions de PDFlib

Toutes les versions de PHP 4 éditées après le 9 Mars 2000 ne suportent pas les versions de PDFlib plus anciennes que PDFlib 3.0.

PDFlib 4.0 et plus récent est supporté par PHP 4.3 et plus récent.

Installation

Cette extension PECL n'est pas intégrée à PHP. Des informations sur l'installation de ces extensions PECL peuvent être trouvées dans le chapitre du manuel intitulé Installation des extensions PECL. D'autres informations comme les notes sur les nouvelles versions, les téléchargements, les sources des fichiers, les informations concernant les mainteneurs ainsi qu'un CHANGELOG, peuvent être trouvées ici : http://pecl.php.net/package/pdflib.

Pour inclure le support de la PDFlib dans votre PHP < 4.3.9, il faut compiler PHP avec l'option --with-pdflib[=DIR]. DIR est le dossier d'installation de PDFlib et, par défaut, il vaut /usr/local.

Types de ressources

Cette extension ne définit aucune ressource.

Remarque sur les fonctions obsolètes de la PDFlib

Depuis PHP 4.0.5, l'extension PHP pour la PDFlib est officiellement supportée par PDFlib GmbH. Cela signifie que toutes les fonctions décrites dans le manuel de référence de la PDFlib (PDFlib V3.0 ou supérieur) sont supportées par PHP 4 avec exactement la même signification et les mêmes paramètres. Cepdentant, avec la PDFlib V5.0.4 ou supérieure, tous les paramètres doivent être spécifiés. Pour des raisons de compatibilité, l'implémentation de la PDFlib supporte la plupart des fonctions obsolètes, mais elles doivent être remplacées par leur nouvelle version. PDFlib GmbH ne fournira aucun support pour les problèmes survenant lors de l'utilisation de ces fonctions obsolètes. La documentation de cette section indique les anciennes fonctions comme "obsolètes" et donne la fonction qui doit être utilisée à la place.

Exemples

La plupart des fonctions sont simples d'emploi. Le plus difficile est probablement de créer un fichier PDF simple. L'exemple suivant devrait vous mettre sur les rails. Il est développé en PHP 4 et crée un fichier hello.pdf d'une page. Il définit quelques champs de contenu et charge la police Helvetica-Bold et affiche le texte "Bonjour le monde (dit PHP) !".

Exemple 1. Exemple "Bonjour le monde !" avec PDFlib en PHP 4

<?php
$p
= PDF_new();

/*  Ouvre un nouveau fichier PDF ; insère un nom de fichier pour créer le PDF sur le disque */
if (PDF_begin_document($p, "", "") == 0) {
   die(
"Erreur : " . PDF_get_errmsg($p));
}

PDF_set_info($p, "Creator", "hello.php");
PDF_set_info($p, "Author", "Rainer Schaaf");
PDF_set_info($p, "Title", "Bonjour le monde (PHP) !");

PDF_begin_page_ext($p, 595, 842, "");

$font = PDF_load_font($p, "Helvetica-Bold", "winansi", "");

PDF_setfont($p, $font, 24.0);
PDF_set_text_pos($p, 50, 700);
PDF_show($p, "Bonjour le monde ");
PDF_continue_text($p, "(dit PHP) !");
PDF_end_page_ext($p, "");

PDF_end_document($p, "");

$buf = PDF_get_buffer($p);
$len = strlen($buf);

header("Content-type: application/pdf");
header("Content-Length: $len");
header("Content-Disposition: inline; filename=hello.pdf");
print
$buf;

PDF_delete($p);
?>

L'exemple suivant vient avec la distribution de la PDFlib pour PHP 5. Il utilise le nouveau gestionnaire d'exceptions ainsi que les nouvelles fonctionnalités objets disponible en PHP 5. Il crée le fichier hello.pdf d'une seule page. Il définit quelques champs de contenu et charge la police Helvetica-Bold et affiche le texte "Bonjour le monde (dit PHP) !".

Exemple 2. Exemple "Bonjour le monde !" avec PDFlib en PHP 5

<?php

try
{
    
$p = new PDFlib();

    
/*  Ouvre un nouveau fichier PDF ; insère un nom de fichier pour créer le PDF sur le disque */
    
if ($p->begin_document("", "") == 0) {
       die(
"Erreur : " . $p->get_errmsg());
    }

    
$p->set_info("Creator", "hello.php");
    
$p->set_info("Author", "Rainer Schaaf");
    
$p->set_info("Title", "Bonjour le monde (PHP) !");

    
$p->begin_page_ext(595, 842, "");

    
$font = $p->load_font("Helvetica-Bold", "winansi", "");

    
$p->setfont($font, 24.0);
    
$p->set_text_pos(50, 700);
    
$p->show("Bonjour le monde ");
    
$p->continue_text("(dit PHP) !");
    
$p->end_page_ext("");

    
$p->end_document("");

    
$buf = $p->get_buffer();
    
$len = strlen($buf);

    
header("Content-type: application/pdf");
    
header("Content-Length: $len");
    
header("Content-Disposition: inline; filename=hello.pdf");
    print
$buf;
}
catch (PDFlibException $e) {
   die(
"Une exception PDFlib est survenu dans l'exemple hello :\n" .
   
"[" . $e->get_errnum() . "] " . $e->get_apiname() . ": " .
   
$e->get_errmsg() . "\n");
}
catch (Exception $e) {
   die(
$e);
}
$p = 0;
?>

Table des matières
PDF_activate_item -- Active un élément de structure ou un autre élément de contenu
PDF_add_annotation -- [Obsolète] Ajoute une annotation
PDF_add_bookmark -- [Obsolète] Ajoute un signet dans la page courante
PDF_add_launchlink -- [Obsolète] Ajoute une annotation de lancement dans la page PDF courante
PDF_add_locallink -- [Obsolète] Ajoute une annotation de lien dans la page PDF courante
PDF_add_nameddest -- Crée une destination nommée
PDF_add_note -- [Obsolète] Ajoute une annotation dans la page PDF courante
PDF_add_outline -- [Obsolète] Ajoute un signet dans la page courante
PDF_add_pdflink --  [Obsolète] Ajoute une annotation sur un lien vers un fichier dans la page PDF courante
PDF_add_thumbnail -- [Obsolète] Ajoute une miniature sur la page PDF courante
PDF_add_weblink -- [Obsolète] Ajoute un lien web sur la page PDF courante
PDF_arc -- Dessine un arc de cercle PDF dans le sens anti-horaire
PDF_arcn -- Dessine un arc de cercle dans le sens horaire
PDF_attach_file -- [Obsolète] Ajoute un fichier attaché à la page PDF
PDF_begin_document -- Crée un nouveau fichier PDF
PDF_begin_font -- Commence une définition de police de type 3
PDF_begin_glyph -- Commence une définition de glyphe pour les polices de tye 3
PDF_begin_item -- Ouvre un élément de structure ou un autre élément de contenu
PDF_begin_layer -- Commence une interface
PDF_begin_page_ext -- Commence une nouvelle page
PDF_begin_page -- [Obsolète] Initialise une nouvelle page de document PDF
PDF_begin_pattern -- Initialise un nouveau pattern PDF
PDF_begin_template -- Initialise un nouveau template PDF
PDF_circle -- Dessine un cercle dans un document PDF
PDF_clip -- Modifie le chemin de clipping PDF
PDF_close_image -- Ferme une image dans un document PDF
PDF_close_pdi_page -- Ferme la page PDF
PDF_close_pdi -- Ferme le fichier PDF d'entrée
PDF_close -- [Obsolète] Ferme le fichier PDF
PDF_closepath_fill_stroke -- Termine le chemin, dessine les bords et remplit la forme
PDF_closepath_stroke -- Termine le chemin et dessine les bords
PDF_closepath -- Termine le chemin PDF courant
PDF_concat -- Concatène une matrice avec le CTM
PDF_continue_text -- Affiche du texte à la prochaine ligne PDF
PDF_create_action -- Crée une action pour des objets ou des événements
PDF_create_annotation -- Crée une annotation rectangulaire
PDF_create_bookmark -- Crée un signet
PDF_create_field -- Crée un champ de formulaire
PDF_create_fieldgroup -- Crée un groupe de champs dans un formulaire
PDF_create_gstate -- Crée un objet graphique
PDF_create_pvf -- Crée un fichier PDFlib virtuel
PDF_create_textflow -- Crée un objet de flux de texte
PDF_curveto -- Dessine une courbe de Bezier
PDF_define_layer -- Crée une définition d'interface
PDF_delete_pvf -- Efface un fichier virtuel PDFlib
PDF_delete_textflow -- Efface un objet de flux de texte
PDF_delete -- Efface un objet PDF
PDF_encoding_set_char -- Ajoute un nom de glyphe et/ou une valeur Unicode
PDF_end_document -- Ferme un fichier PDF
PDF_end_font -- Termine une définition de police de type 3
PDF_end_glyph -- Termine la définition d'un glyphe pour les polices de type 3
PDF_end_item -- Ferme la structure d'un élément ou un autre élément de contenu
PDF_end_layer -- Désactive toutes les interfaces actives
PDF_end_page_ext -- Termine une page
PDF_end_page -- Termine la page PDF courante
PDF_end_pattern -- Termine le pattern PDF
PDF_end_template -- Termine le template PDF
PDF_endpath -- Termine le chemin courant
PDF_fill_imageblock -- Remplit un bloc d'image avec des données variables
PDF_fill_pdfblock -- Remplit un bloc de contenu avec des données variables
PDF_fill_stroke -- Remplit et passe le pinceau sur le chemin PDF courant
PDF_fill_textblock -- Remplit un bloc de texte avec des données variables
PDF_fill -- Remplit le chemin PDF courant avec la couleur courante
PDF_findfont -- [Obsolète] Prépare une police pour utilisation ultérieure
PDF_fit_image -- Place une image ou un template
PDF_fit_pdi_page -- Place une page PDF importée
PDF_fit_textflow -- Formate un flux de texte dans un espace rectangulaire
PDF_fit_textline -- Place un simple ligne de texte
PDF_get_apiname -- Récupère le nom d'une fonction de l'API qui a échouée
PDF_get_buffer -- Lit le tampon contenant le fichier PDF généré
PDF_get_errmsg -- Récupère le texte d'une erreur
PDF_get_errnum -- Récupère un numéro d'erreur
PDF_get_font -- [Obsolète] Charge une police
PDF_get_fontname -- [Obsolète] Lit le nom de la police
PDF_get_fontsize -- [Obsolète] Gère les polices
PDF_get_image_height -- [Obsolète] Retourne la hauteur d'une image
PDF_get_image_width -- [Obsolète] Retourne la largeur d'une image
PDF_get_majorversion --  [Obsolète] Retourne le numéro de version majeur de PDFlib
PDF_get_minorversion --  [Obsolète] Retourne le numéro de version mineure de PDFlib
PDF_get_parameter -- Lit certains paramètres
PDF_get_pdi_parameter -- Lit des paramètres textuels dans le document PDI
PDF_get_pdi_value -- Lit des paramètres numériques dans le document PDF d'entrée
PDF_get_value -- Lit certains paramètres numériques
PDF_info_textflow -- Récupère le statut d'un flux de texte
PDF_initgraphics -- Remet à zéro l'environnement graphique PDF
PDF_lineto -- Dessine une ligne PDF
PDF_load_font -- Cherche et prépare une police
PDF_load_iccprofile -- Cherche et prépare un profile ICC
PDF_load_image -- Ouvre un fichier image
PDF_makespotcolor -- Place un point de couleur PDF
PDF_moveto -- Place le point courant PDF
PDF_new -- Crée un nouvel objet PDF
PDF_open_ccitt -- [Obsolète] Ouvre une image contenant des données brutes CCITT
PDF_open_file -- [Obsolète] Ouvre un nouveau fichier PDF
PDF_open_gif -- [Obsolète] Ouvre une image GIF
PDF_open_image_file -- [Obsolète] Lit une image depuis un fichier
PDF_open_image -- [Obsolète] Ouvre une image
PDF_open_jpeg -- [Obsolète] Ouvre une image JPEG
PDF_open_memory_image -- [Non supporté] Ouvre une image créée en mémoire par PHP
PDF_open_pdi_page -- Prépare une page
PDF_open_pdi -- Ouvre un fichier PDF
PDF_open_tiff -- [Obsolète] Ouvre une image TIFF
PDF_place_image -- [Obsolète] Place une image dans la page
PDF_place_pdi_page -- [Obsolète] Place une page dans le document
PDF_process_pdi -- Traite un document PDF importé
PDF_rect -- Dessine un rectangle
PDF_restore -- Rétablit l'ancien environnement graphique PDF
PDF_resume_page -- Réouvre une page
PDF_rotate -- Configure la rotation
PDF_save -- Sauve l'environnement graphique courant
PDF_scale -- Configure l'échelle du document
PDF_set_border_color -- [Obsolète] Configure la couleur des bords autour des liens et annotations
PDF_set_border_dash -- [Obsolète] Configure le style des lignes autour des liens des annotations
PDF_set_border_style -- [Obsolète] Choisit le style de bord autour des liens et annotations
PDF_set_char_spacing -- [Obsolète] Configure l'espacement des caractères
PDF_set_duration -- [Obsolète] Configure la durée entre deux pages
PDF_set_gstate -- Active un objet graphique
PDF_set_horiz_scaling -- [Obsolète] Configure l'échelle horizontale du texte
PDF_set_info_author --  [Obsolète] Remplit le champ d'auteur du document
PDF_set_info_creator --  [Obsolète] Remplit le champ de créateur du document
PDF_set_info_keywords --  [Obsolète] Remplit le champ de mots-clés du document
PDF_set_info_subject --  [Obsolète] Remplit le champ de sujet du document
PDF_set_info_title --  [Obsolète] Remplit le champ de titre du document
PDF_set_info -- Remplit un champ de l'en-tête de document PDF
PDF_set_layer_dependency -- Définit les liens entre les interfaces
PDF_set_leading -- [Obsolète] Configure la distance entre deux lignes de texte
PDF_set_parameter -- Modifie certains paramètres
PDF_set_text_matrix -- [Obsolète] Configure la matrice de texte
PDF_set_text_pos -- Modifie la position du texte
PDF_set_text_rendering -- [Obsolète] Détermine le rendu du texte
PDF_set_text_rise -- [Obsolète] Configure l'élévation de texte
PDF_set_value -- Modifie certains paramètres numériques
PDF_set_word_spacing -- [Obsolète] Configure l'espace entre deux mots
PDF_setcolor -- Configure la couleur de dessin et de remplissage
PDF_setdash -- Configure le mode de pointillé
PDF_setdashpattern -- Définit un modèle de masque
PDF_setflat -- Configure la position à plat (flatness)
PDF_setfont -- Configure la police courante
PDF_setgray_fill -- [Obsolète] Configure la couleur de remplissage à un niveau de gris
PDF_setgray_stroke -- [Obsolète] Configure la couleur de dessin à un niveau de gris
PDF_setgray -- [Obsolète] Configure la couleur de dessin et de remplissage à un niveau de gris
PDF_setlinecap -- Configure le paramètre de linecap
PDF_setlinejoin -- Configure le paramètre de linejoin
PDF_setlinewidth -- Configure la largeur de ligne
PDF_setmatrix -- Configure la matrice de transformation
PDF_setmiterlimit -- Configure la "miter limit"
PDF_setpolydash -- [Obsolète] Configure des pointillés complexes
PDF_setrgbcolor_fill -- [Obsolète] Choisit la couleur utilisée pour le remplissage
PDF_setrgbcolor_stroke -- [Obsolète] Choisit la couleur utilisée pour le dessin
PDF_setrgbcolor -- [Obsolète] Choisit la couleur rgb de remplissage et de dessin
PDF_shading_pattern -- Définit un masque d'ombrage
PDF_shading -- Définit un dégradé
PDF_shfill -- Remplit un espace avec un degradé
PDF_show_boxed -- [Obsolète] Affiche le texte dans un cadre
PDF_show_xy -- Affiche un texte à une position donnée
PDF_show -- Affiche le texte à la position courante
PDF_skew -- Incline le système de coordonnées
PDF_stringwidth -- Retourne la largeur d'un texte avec la police courante
PDF_stroke -- Dessine la ligne le long du chemin
PDF_suspend_page -- Suspend une page
PDF_translate -- Effectue une translation de l'origine du système de coordonnées
PDF_utf16_to_utf8 -- Convertit une chaîne UTF-16 en UTF-8
PDF_utf8_to_utf16 -- Convertit une chaîne UTF-8 en UTF-16