CPDF_BEGIN_TEXT

Syntaxe

Paramètres

Description

Cette fonction permet de débuter une zone de texte dans un document de format PDF. Cette fonction est obsolète.

Remarques

• L'extension CLIBPDF initialement proposé à partir du PHP 3 a été progressivement retiré jusqu'à la version 5 du PHP où elle fut remplacé par l'extension PDFLIB, laquelle est utilisé par de nombreux langages de programmations autre que le PHP. Si vous ne pouvez pas installer un extension supplémentaire, vous pouvez utiliser la bibliothèque gratuite et open source entièrement écrit en PHP pure FPDF Library développé par Olivier PLATHEY.
• Le rôle principal de cette fonction est de marquer le début d'une section de texte dans un flux de génération de PDF. Autrement dit, elle indique à l'API que le contenu qui va suivre doit être interprété comme du texte, et non comme des dessins, des images ou des formes vectorielles.
• Le paramètre $pdf_document est essentiel puisqu'il identifie le document PDF dans lequel la zone de texte va être définie. Sans ce paramètre, la fonction ne saurait pas dans quel contexte travailler. En pratique, il s'agit d'un identifiant ou d'un pointeur retourné par une fonction d'initialisation du document.
• L'appel de cpdf_begin_text doit obligatoirement être complété par un appel à cpdf_end_text afin de délimiter correctement la zone de texte. Si cette fermeture est omise, cela peut engendrer des erreurs ou des incohérences dans le rendu du PDF.
• Le mécanisme ressemble à celui d'un flux de balises en XML ou HTML : on ouvre une balise (ici begin_text), on insère du contenu, puis on ferme avec une balise correspondante (end_text). Ce mode de fonctionnement en "paire" permet une meilleure organisation du contenu textuel.
• Comme la fonction est déclarée obsolète, son utilisation peut poser des problèmes de compatibilité avec les versions récentes de PHP. Elle risque même de ne pas être disponible du tout dans les distributions actuelles, ce qui impose une réécriture du code existant si l'on souhaite migrer.
• L'usage de cette fonction est typique des librairies bas-niveau pour la gestion de PDF. Elle ne gère pas la mise en forme complexe du texte directement, mais seulement la création d'un bloc textuel. Pour positionner, changer de police ou gérer des styles, il fallait appeler d'autres fonctions complémentaires (par ex. cpdf_set_font, cpdf_set_text_pos).
• D'un point de vue pédagogique, cpdf_begin_text illustre bien la philosophie des bibliothèques de génération de PDF anciennes : elles étaient souvent proches de la logique interne du format PDF lui-même, nécessitant plusieurs appels successifs pour écrire un simple texte. Aujourd'hui, les bibliothèques modernes simplifient considérablement ce processus avec des appels plus haut-niveau.