doc-fr/reference/pdf/reference.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.27 $ -->
<!-- EN-Revision: 1.24 Maintainer: yannick Status: ready -->
<!-- Purpose: utilspec.nontext -->
<!-- Membership: pecl, external -->
<!-- Reviewed: no -->

<reference id="ref.pdf">
 <title>&Functions; PDF </title>
 <titleabbrev>PDF</titleabbrev>

 <partintro>
  <section id="pdf.intro">
   &reftitle.intro;
   <para>
    Les fonctions PDF permettent de créer des fichiers PDF en utilisant
    la bibliothèque PDFlib créée initialement par
    <ulink url="&url.pdflib.merz;">Thomas Merz</ulink> et qui est
    actuellement maintenue par <ulink url="&url.pdf;">PDFlib GmbH</ulink>.
   </para>
   <para>
    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.
   </para>
   <para>
    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.
   </para>
   <para>
    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.
   </para>
   <para>
    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 :
   </para>
   <para>
    En &php; 4, tout d'abord, une ressource PDF doit être récupérée
    avec l'appel à une fonction comme
   </para>
   <para>
    $p = PDF_new();
   </para>
   <para>
    Cette ressource PDF est utilisée en tant que premier paramètre dans tous
    les prochains appels de fonctions, comme dans
   </para>
   <para>
    PDF_begin_document($p, "", "").
   </para>
   <para>
    En &php; 5, un objet PDFlib est créé plutôt avec
   </para>
   <para>
    $p = new PDFlib().
   </para>
   <para>
    Cet objet offre toutes les fonctions de l'API PDFlib en tant que méthodes,
    par exemple avec
   </para>
   <para>
    $p->begin_document("", "").
   </para>
   <para>
    En plus, les exceptions ont été introduites en &php; 5 qui sont supportées
    dans la version 6 ou supérieure de la PDFlib.
   </para>
   <para>
    Lisez les <link linkend="pdf.examples">exemples</link> ci-dessous
    pour plus d'informations.
   </para>
   <note>
    <para>
     Si vous êtes intéressé par des alternatives gratuites pour
     générer des PDF, sans passer par des bibliothèques PDF, reportez-vous à
     <link linkend="faq.using.freepdf"> cette entrée de la FAQ</link>.
    </para>
   </note>
  </section>

  <section id="pdf.requirements">
   &reftitle.required;
   <para>
    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
    <ulink url="&url.pdf;">&url.pdf;</ulink>, mais impose l'achat
    d'une license pour l'utiliser commercialement.
   </para>
  </section>

  <section id="pdf.oldlibs.hints">
   <title>Problèmes avec les anciennes versions de PDFlib</title>
   <para>
    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.
   </para>
   <para>
    PDFlib 4.0 et plus récent est supporté par &php; 4.3.0 et
    plus récent.
   </para>
  </section>

  &reference.pdf.configure;

  <section id="pdf.resources">
   &reftitle.resources;
   &no.resource;
  </section>

  <section id="pdf.oldlibs">
   <title>Remarque sur les fonctions obsolètes de la PDFlib</title>
   <para>
    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.
   </para>
  </section>

  <section id="pdf.examples">
   &reftitle.examples;
   <para>
    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 <filename>hello.pdf</filename> d'une page.
    Il définit quelques champs de contenu et charge la police
    <literal>Helvetica-Bold</literal> et affiche le texte "Bonjour le monde (dit PHP) !".
   </para>
   <para>
    <example>
     <title>Exemple "Bonjour le monde !" avec PDFlib en &php; 4</title>
     <programlisting role="php">
<![CDATA[
<?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);
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    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 <filename>hello.pdf</filename>
    d'une seule page. Il définit quelques champs de contenu et charge la police
    <literal>Helvetica-Bold</literal> et affiche le texte "Bonjour le monde (dit PHP) !".
   </para>
   <para>
    <example>
     <title>Exemple "Bonjour le monde !" avec PDFlib en &php; 5</title>
     <programlisting role="php">
<![CDATA[
<?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;
?>
]]>
     </programlisting>
    </example>
   </para>
  </section>

 </partintro>

 &reference.pdf.functions;

</reference>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->