PHP SmartyPants

Téléchargement

Librarie : pour développeurs

PHP SmartyPants Lib 1.8.1 (17 Ko): Librarie PHP SmartyPants pour développement. Requiert PHP 5.3. Aussi disponible sur Packagist et sur Github. Le 12 décembre 2016.

Version classique : plugin pour WordPress, Smarty, etc.

Classic version → PHP SmartyPants & PHP SmartyPants Typographer: Important: la version classique de PHP SmartyPants et PHP SmartyPants Typographer n’est plus supportée. Si vous êtes un développeur utilisant PHP 5.3 ou plus, utilisez plutôt la version Lib ci-haut.

Introduction

Ceci est une librarie qui inclus le parseur PHP SmartyPants et son frère PHP SmartyPants Typographer.

PHP SmartyPants permet de facilement transformer une ponctuation faite de simple caractères ASCII en entités HTML de ponctuation « typographiquement intelligente. »

PHP SmartyPants est un portage vers le PHP de SmartyPants écrit en Perl par John Gruber.

SmartyPants effectue les transformations suivantes :

Guillemets droits (" et ') en entités HTML de guillemets “courbes” ;
Citations à guillemets approximatifs (``comme ça'') en entités HTML de guillemets “courbes” ;
Tirets (« -- » et « --- ») en entités HTML de de tiret court et long ;
Trois points consécutifs (« ... ») en une entité HTML de points de suspension.

SmartyPants Typographer peut effectuer les transformations supplémentaires suivantes :

Guillemets français approximatifs (<< et >>) en véritable « guillemets ».
Guillemets virgule (,,comme ça`` et ''comme ça,,) en leur équivalents typographiques.
Remplacement des espaces existants en espace insécable lorsqu’approprié autour des signes de ponctuation, avec possibilité de les ajouter ou supprimer selon la configuration.
Remplacement des espaces existants en espace insécable pour les séparateurs de millier ou entre un nombre et un symbole d’unité reconnu qui le suit.

Ceci veux dire qu vous pouvez écrire, éditer, et sauvegarder en utilisant la ponctuation ASCII de base tout en permettant au contenu publié d’appraraître avec de la ponctuation typographiquement soignée.

SmartyPants ne modifie pas les caractères à l’intérieur des balises <pre>, <code>, <kbd>, or <script>. Normalement, ces balises sont utilisées pour afficher du texte où les guillemets courbes et le reste de la ponctuation intelligente ne serait pas appropriée, comme du code.

Échappement

Si vous avec littéralement besoin d’un guillemet droit (ou d’un tiret ou de points), SmartyPants accepte les séquences d’échappement suivantes commençant par une barre oblique inversée pour forcer une ponctuation non-améliorée. les caractères seront alors changés en entité HTML décimales équivalente :

Échappement	Valeur	Charactère
`\\`	`\`	`\`
`\"`	`"`	`"`
`\'`	`'`	`'`
`\.`	`.`	`.`
`\-`	`-`	`-`
\`	```	`

C’est utile, par exmple, si vous voulez utiliser des guillemets droits comme marqueur poru des pieds et des pouces :

6\'2\" de haut

ce qui devient :

6&#39;2&#34; de haut

dans le HTML généré par SmartyPants. Un navigateur affiche alors :

6'2" de haut

Configuration requise

Cette librarie requiert PHP 5.3 ou plus.affiche

Note : l’anciene librarie hybride plugin pour PHP SmartyPants et PHP SmartyPants Typographer fonctionne toujours avec PHP 4.0.5.

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\SmartyPants;
$html_output = SmartyPants::defaultTransform($html_input);

SmartyPants Typographer est disponible de la même façon :

use Michelf\SmartyPantsTypographer;
$html_output = SmartyPantsTypographer::defaultTransform($html_input);

Si vous désirez utiliser PHP SmartyPants avec un autre filtre qui génère du HTML tel que Markdown, vous devez filtrer le texte après la fonction génératrice de HTML. Voici un exemple utilisant PHP Markdown :

use Michelf\Markdown, Michelf\SmartyPants;
$my_html = Markdown::defaultTransform($my_text);
$my_html = SmartyPants::defaultTransform($my_html);

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\SmartyPants, faites comme ceci :

require_once 'Michelf/SmartyPants.inc.php';

Ou si vous avez besoin du parseur Michelf\SmartyPantsTypographer :

require_once 'Michelf/SmartyPantsTypographer.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.

Limites algorithmiques

Une situation où les guillemets sont courbés dans le mauvais sens apparaît quand une apostrophe est utilisée au début d’une contraction. Par exemple :

'Twas the night before Christmas.

Dans un cas comme celui-ci, SmartyPants transformera l’apostrophe en un guillemet simple ouvrant, alors que ça devrait être un fermant. Il n’y a probablement pas de façon de régler ce problème de façon générale.

Dans un tel cas, il faut utiliser l’entité HTML appropriée pour un guillement simple fermant (’ ou ’), à la main.

Bogues

Pour signaler un problème (autre que les sujets discutés dans la section « Algorithmic Shortcomings » sur la page de SmartyPants de John Gruber, contactez moi par courriel à cette adresse :

michel.fortin@michelf.ca

Si le bogue comprend des guillemets courbés sur le mauvais sens, prière de fournir un exemple pour illustrer.

Contributions

Conversion en PHP par Michel Fortin.

Version originale en Perl par John Gruber.

Une partie de ce programme est basé sur le plugin MTRegex de Brad Choate.