PHP Markdown

Téléchargement

PHP Markdown Lib 2.0.0 (131 Ko)

Librarie PHP Markdown pour développement. Nécéssite PHP 7.4 ou plus récent. Aussi disponible sur Packagist et sur Github. Le 26 septembre 2022.

L’ancienne version classique capable d’agir comme plugin pour WordPress et Smarty n’est plus supportée.

Introduction

Ceci est une librarie qui inclus le parseur PHP Markdown et son frère PHP Markdown Extra incluant de nouvelles fonctionalités. À l’origine il s’agissait d’un portage vers le PHP de l’outil Markdown écrit par John Gruber.

Markdown, c’est deux choses : c’est une syntaxe qui vous permet d’écrire de façon naturelle en format texte ; c’est aussi un logiciel qui permet de convertir du texte écrit selon la syntaxe Markdown en code HTML pour la publication sur un site web.

La syntaxe Markdown vous permet d’écrire naturellement du texte et de lui donner un certain format sans avoir à utiliser de balise HTML. Plus important encore : en format Markdown, votre texte reste agréable à lire pour un être humain, et c’est suffisamment vrai pour qu’un document écrit avec Markdown puisse être publié textuellement, sans modification. Si vous utilisez le courrier électronique en mode texte, vous connaissez déjà certaines parties de la syntaxe.

Visitez la page Concepts pour une courte introduction remplie d’exemples qui vous apprendra à écrire avec Markdown. Si vous connaissez bien le HTML, vous pouvez aussi consulter la syntaxe complète qui explique en détail l’opération de conversion du texte vers le HTML.

Configuration requise

PHP Markdown Lib nécessite la version 5.3 ou plus récente de PHP.

Pour les version antérieures de PHP, vous pouvez utilisez la version classique.

Avant PHP 5.3.7, pcre.backtrack_limit était réglé par défaut à 100 000, ce qui est trop petit dans certaines circonstances. Vous deverez peut-être le changer pour une valeur plus élevé. Les dernières versions de PHP utilisent 1 000 000, ce qui est généralement suffisant.

Utilisation

Cette librarie est conçu pour être utilisé avec l’auto-chargement des classes. Pour que l’auto-charchement fonctionne, votre projet doit avoir installé un un auto-chargeur compatible avec PSR-0. Voir le fichier Readme.php pour une installation minimale. (Si vous ne pouvez utiliser l’auto-chargement, voyez plus bas.)

Avec l’auto-chargement des classes en place, placer le dossier « Michelf » dans votre chemin d’inclusion devrait être suffisant pour faire fonctionner ceci:

use Michelf\Markdown;
$mon_html = Markdown::defaultTransform($mon_texte);

La syntaxe Markdown Extra est aussi disponible de la même façon:

use Michelf\MarkdownExtra;
$mon_html = MarkdownExtra::defaultTransform($mon_texte);

Si vous désirez utiliser PHP Markdown avec un autre filtre conçu pour travailler avec du HTML, vous devez filtrer le texte après l’appel à la fonction transform. Voici un exemple utilisant PHP SmartyPants:

use Michelf\Markdown, Michelf\SmartyPants;
$mon_html = Markdown::defaultTransform($mon_texte);
$mon_html = SmartyPants::defaultTransform($mon_html);

Tous ces exemples utilisent la fonction statique defaultTransform qui se trouve à l’intérieur de la classe du parseur. Si vous voulez personaliser la configuration du parseur, vous pouvez aussi l’instancier directement et changer certaines variables de configuration:

use Michelf\MarkdownExtra;
$parser = new MarkdownExtra;
$parser->fn_id_prefix = "post22-";
$mon_html = $parser->transform($mon_texte);

Pour en savoir plus, consultez la liste complète des variables de configuration.

Utilisation sans auto-chargement

Si vous ne pouvez utiliser l’auto-chargement des classes, vous pouvez toujours faire un include ou un require pour accéder au parseur. Pour charger le parseur Michelf\Markdown, faites comme ceci:

require_once 'Michelf/Markdown.inc.php';

Ou si vous avez besoin du parseur Michelf\MarkdownExtra:

require_once 'Michelf/MarkdownExtra.inc.php';

Alors que les fichiers purs .php dépendent de l’autochargement pour fonctionner, l’utilisation des fichiers .inc.php chargera à l’avance toutes les dépendances nécessaires qui seraient autrement chargés à la demande avec l’auto-chargement.

API public et politique de versionnement

Les numéros de version sont de la forme majeur.mineur.patch.

L’API public de PHP Markdown consiste en deux classes parseur Markdown et MarkdownExtra, leur constructeurs, les fonctions transform et defaultTransform ainsi que leurs variables de configuration. L’API public est stable pour une version majeure donnée. Elle pourrait recevoir des additions d’une version mineure à l’autre.

Les membres protégés ne sont pas considérés faire partie de l’API public. Ceci n’est pas conventionnel et mérite une explication. Incrémenter le numéro de version majeur à chaque changement donnerait des numéros de version insensés pour la vaste majorité de ceux qui ne font qu’utiliser le parseur. Les membres protégés sont là pour créer des sous-classes d’un parseur qui se comporte de façons différentes. Très peu de gens créent des sous-classes. Je ne veux pas décourager ceux qui veulent en faire en mettant tout privé, mais en même temps je ne peux garentir la stabilité de l’API entre les version pour les membres protégés.

Les changements à la syntaxe incrémenteront le numéro mineur pour les nouvelles fonctionalités, et le numéro patch pour les petites corrections. Une nouvelle fonctionalité est quelque chose qui nécéssite un chanemeng à la documentation de la syntaxe. Notez que puisque PHP Markdown Lib inclus deux parseurs, un changement à la syntaxe pour un seul d’entre eux incrémentera le à numéro mineur. Notez aussi qu’il n’y a rien de parfaitement rétrocompatible avec la syntaxe Markdown: toutes les entrés sont toujours valides, donc une nouvelle fonctionalité remplace toujours quelque chose qui était aupravant permis, même si cette chose ne faisait probablement pas trop de sens.

Bogues

Pour signaler un problème, contactez moi par courriel à cette adresse : michel.fortin@michelf.ca

Merci d’inclure : (1) un exemple du texte d’entrée ; (2) la sortie à laquelle vous vous attendiez ; (3) la sortie que PHP Markdown a produite.

Développement et tests

Voir le dépôt PHP Markdown sur Github et MDTest pour la suite de tests.

Licence et droit d’auteur

PHP Markdown Lib
Copyright © 2004-2022 Michel Fortin Tous droits réservés.

Markdown Original
Copyright © 2004-2006 John Gruber
Tous droits réservés.