Ecriture d’un plugin WordPress, 1e partie : les bases

Dans cet article, je vais vous indiquer les règles de base pour créer un plugin WordPress. Cet article est le premier d’une suite d’articles qui vous permettront de plonger de plus en plus profondément dans l’écriture de plugins.

1- Préalable

La première étape est d’abord d’ouvrir le répertoire de WordPress dans lequel les plugins doivent être placés afin qu’ils soient automatiquement reconnus. Ouvrez donc votre client FTP préféré, et allez dans le dossier WordPress-content/plugins.

Nous allons placer notre plugin dans un répertoire particulier afin d’avoir une meilleure organisation. Créez un dossier avec le nom du plugin (tout simplement myplugin dans notre cas) dans le dossier plugins. A ce stade, vérifiez que le dossier nouvellement créé soit accessible en lecture, écriture (afin de pouvoir éditer le plugin directement sous WordPress) et exécution. Ces permissions dépendent de vos configurations (mod_php ou cgi, etc…). Une bonne façon de procéder est de regarder et comparer avec les permissions des plugins déjà présents. Cette question de permissions est également à vérifier à chaque fois que vous créez un nouveau fichier.

Créez maintenant une page myplugin.php dans le nouveau dossier. Notre première étape est maintenant de l’identifier :

<?php
/*
Plugin Name: MyPlugin
Description: Exemple de création de plugin
Version: 0.0
*/
?>

A ce stade, vous pouvez voir que votre plugin est déjà disponible dans la page « Gérer les extensions » de WordPress.

L’objectif d’un plugin est de modifier des comportements existants, ou d’apporter un ou des nouveaux comportements dans WordPress. Pour cela, le plugin doit se greffer à l’architecture existante. Pour rester dans l’analogie médicale, une greffe ne prend que si l’organisme ne la rejette pas. Pour éviter ce rejet, WordPress offre les hooks. Un hook (litt. un crochet) est un dispositif qui permet à un plugin de s’insérer dans le fonctionnement général de WordPress. Ce sont littéralement des portes par lesquelles on peut entrer dans la maison WordPress, modifier l’emplacement des meubles ou la couleur des pièces, voire changer de meubles, sans pour autant toucher aux murs de la maison.
Les plugins peuvent donc modifier le comportement de WordPress, ou ajouter un nouveau comportement, et deux types de hooks sont disponibles pour cela : les filters et les actions.

2 - Les filters

Si vous voulez modifier un comportement existant dans WordPress, vous utiliserez un filter (filtre). Un filtre donne un élément à votre code et s’attend à ce que votre code lui retourne un élément. Le rôle de votre code est donc de transformer/convertir/modifier l’élément initial avant de le retourner.
Supposons par exemple que vous désirez modifier tous les titres qui apparaissent dans votre blog. Le code pour cela est le suivant :

<?php
// Cette fonction ajoute un petit texte à un autre texte
function myplugin_change_post_title ($text) {
	$text .= "<br /> <span style=\"color:blue\">my plugin est passé par là</span>";
	return $text;
}

//insertion de la fonction dans le filter the_title
add_filter('the_title', 'myplugin_change_post_title');
?>

D’ores et déjà, deux observations :

- ne jamais sous-estimer l’importance des commentaires dans le code. Cela vous permettra plus tard de comprendre tout de suite ce que fait votre code sans avoir à l’analyser ligne par ligne.

- le nom de la fonction n’est pas aussi long (myplugin_change_post_title) pour rien. Cela permet d’éviter des conflits entre vos fonctions et les fonctions de WordPress ou les fonctions d’autres plugins. Veuillez utiliser un nom de fonction qui soit aussi unique que possible afin d’éviter tout conflit de nommage avec d’autres plug-ins, surtout si vous comptez distribuer le votre. L’autre solution pour éviter un conflit est l’utilisation de classes, en attendant les namespaces de PHP6.

Pour revenir au code, la fonction myplugin_change_post_title() fait exactement ce que le commentaire qui le précède annonce : il prend en paramètre un texte, y ajoute un autre texte, et renvoie le tout.
La fonction add_filter() ordonne ensuite à WordPress d’exécuter la fonction myplugin_change_post_title à chaque fois que le filter the_title est lancé. the_title se lance à chaque fois que WordPress récupère le titre d’un post depuis la base de données et avant l’affichage du titre sur la page. the_title donne donc le titre du post (ici, Lorem Ipsum) à myplugin_change_post_title, qui y ajoute le petit bout de texte (mais il peut s’agir d’opérations plus compliquées), puis retourne le texte ainsi modifié, qui est alors inséré de nouveau dans le processus global de WordPress.

Résultat :

Le code html résultant est le suivant :

Lorem Ipsum  my plugin est passé par là

Vous verrez que le texte est rajouté aussi bien dans le titre même que dans l’attribut title du lien. Cela tient à la nature particulière du filter the_title.

3- Les actions

Maintenant, nous désirons modifier le style du texte que nous venons de rajouter aux titres afin qu’il se distingue du reste du titre. Nous pourrions faire cela en modifiant la fonction myplugin_change_post_title, mais supposons que nous avons besoin de cette fonction telle quelle, qu’elle soit utilisée par d’autres parties du plugin et doit rester intact par exemple. Nous allons donc plutôt utiliser une autre fonction se greffant sur une action à la place. En effet, une action se contente juste dire à votre code : je te laisse la main pendant un moment, fais ce que tu as à faire, et dis-moi quand tu as fini !

<?php
/**
 * Cette fonction modifie le style du texte ajouté au titre en y ajoutant du code CSS
 */

function myplugin_add_style_post_title() {
	echo <<<CSS
	<style type="text/css">
	.myplugin_change_post_title_style {
	  color:#4378fe;
	  font-style: italic;
	  }
	</style>
CSS;
}

add_action('Wordpress_head', 'myplugin_add_style_post_title');
?>

Vous remarquerez que myplugin_add_style_post_title ne prends pas de paramètres, et ne retourne rien. Elle se contente d’afficher des lignes CSS, et c’est tout. C’est donc une candidate idéale pour l’utilisation d’une action.
Vous aurez également remarqué que la syntaxe de echo a une forme différente de celle qu’on voit d’habitude. Ici, nous avons recours à la syntaxe HEREDOC (http://www.php.net/manual/fr/language.types.string.php#language.types.string.syntax.heredoc), qui permet d’utiliser des chaînes de caractère d’une façon plus simple (sans devoir par exemple échapper les guillemets, potentiels sources d’erreurs).
La fonction add_action exécute ensuite la fonction myplugin_add_style_post_title lorsque l’action wp_head est lancée, c’est-à-dire entre l’affichage des balises et .

Sans surprise, le code suivant est inséré dans l’en-tête de la page :

	<style type="text/css">
	.myplugin_change_post_title_style {
	  color:#4378fe;
	  font-style: italic;
	  }
	</style>

Note : ceci est juste un exemple, afin d’illustrer l’utilisation d’une action. Dans un vrai plugin, il est très déconseillé d’écrire directement de cette manière du code CSS dans l’en-tête. Il y a des manières plus élégantes et sécurisées de procéder.

Nous avons vu ici les bases de l’écriture d’un plugin WordPress. Dans les articles suivants, nous verrons comment apporter plus de fonctionnalités concrètes à ce plugin.

Notre plugin WordPress