Page d'accueil du Codex en français - Télécharger WordPress en français
Les utilisateurs francophones se retrouvent sur le site WordPress-Francophone, notamment sur son forum d'entraide.
Cette page a pour objectif de documenter l'API (Application Programming Interface) des "hooks" et son utilisation pour le développement de plugin WordPress.
Cet article suppose que vous ayez déjà lu Writing a Plugin (en anglais), qui donne une vue d'ensemble (avec beaucoup de détails) sur la manière de développer un plugin. Le présent article est focalisé sur l'API des "Hooks", également connue comme "Filtres" et "Actions", que WordPress utilise pour mettre votre plugin en action. Ces "hooks" peuvent également être utilisés dans les thèmes, comme décrit ici (en anglais).
Note: Les informations données ici s'appliquent aux Versions 1.2 et supérieures de WordPress. Avant la version 1.2, il fallait utiliser des "hacks" qui impliquaient la modification du code source de WordPress.
Les "hooks" sont fournis dans WordPress afin de permettre à votre plugin de "crocheter" le fonctionnement de WordPress. C'est à dire d'appeler des fonctions de votre plugin à des moments précis afin de réaliser des actions. Il existe deux types de "hook" :
Il est parfois possible d'accomplir une tâche en utilisant aussi bien une action qu'un filtre. Par exemple, si vous voulez que votre plugin modifie le texte d'un article, vous devrez ajouter une fonction à l'action publish_post (l'article sera alors modifié lors de sa sauvegarde dans la base de données), ou bien une fonction de filtrage pour the_content (l'article sera alors modifié lors de son affichage dans le navigateur).
Pour la liste complète de toutes les actions et filtres disponibles dans WordPress voir Adam Brown's WP Hooks Database (en anglais).
|
|
Les actions sont générés par des évènements spécifiques qui arrivent dans WordPress comme la publication d'un article, le changement de thème ou l'affichage d'une page du panneau d'administration. Votre plugin peut répondre à l'évènement en exécutant une fonction PHP qui peut par exemple :
Les étapes de base pour faire ceci (décrites plus en détail ci-dessous) sont les suivantes :
La première étape pour créer une action dans votre plugin consiste à écrire une fonction PHP et à la placer dans votre plugin (votre fichier de plugin doit se trouver dans le répertoire wp-content/plugins). Par exemple, si vous voulez que vos amis reçoivent un email chaque fois que vous créez un nouvel article, vous devrez créer la fonction suivante :
function email_friends($post_ID) {
$friends = 'bob@example.org,susie@example.org';
mail($friends, "sally's blog updated",
'I just put something on my blog: http://blog.example.com');
return $post_ID;
}
Pour la plus part des actions, votre fonction devra accepter un paramètre (généralement l'ID de l'article ou du commentaire). Certaines actions peuvent cependant avoir plusieurs paramètres -- consultez la documentation des actions (si elle est disponible) ou le code source de WordPress pour plus d'informations. Dans votre fonction, outre les paramètres, vous pouvez également accéder aux variables globales de WordPress et appeler d'autres fonctions WordPress (ou de votre plugin).
Toute sortie de texte dans une fonction (par exemple avec print) apparaitra dans le code source de la page à l'endroit où l'action a été invoquée.
NOTE : gardez à l'esprit que les autres plugins ou même WordPress utilisent peut-être déjà le nom de fonction que vous voulez utiliser. Voyez Avoiding Function Name Collisions (en anglais) pour plus d'informations.
Après la création de votre fonction, l'étape suivant consiste à s'enregistrer à WordPress. Pour faire ceci, appelez la fonction add_action() dans l'espace global d'exécution de votre plugin :
add_action ( 'hook_name', 'your_function_name', [priority], [accepted_args] );
où :
Avec l'exemple précédent, il faudrait rajouter la ligne suivant dans le plugin :
add_action ( 'publish_post', 'email_friends' );
Vous pouvez également supprimer les actions. Voir cette section pour plus de détails.
La dernière étape pour que votre action fonctionne consiste à installer le fichier et à activer le plugin. La fonction PHP que vous avez écrite et l'appel à add_action doivent être placé ensemble dans un fichier PHP de votre plugin qui doit lui même être installé dans le répertoire wp-content/plugins. Quand ceci est fait vous devez vous rendre dans l'administration de WordPress afin d'activer votre plugin ; voir Managing Plugins (en anglais) pour plus de détails.
Voyez Plugin API/Action Reference (en anglais) pour la liste des actions actuellement disponibles dans WordPress.
Les filtres sont des fonctions au travers des quelles WordPress va faire passer des données à certains moment de l'exécution. Juste avant de faire certaines actions avec les données (comme l'ajout dans une base de données ou l'envoi vers le navigateur). Les filtres se trouvent donc entre la base de données et le navigateur (quand WordPress génère des pages) et entre le navigateur et la base de données (quand WordPress ajoute de nouveaux articles ou commentaires dans la base de données) ; la plus part des entrées/sorties de WordPress passent par au moins un filtre. WordPress effectue quelque filtrage par défaut et votre plugin peut en ajouter de nouveau.
Les étapes de bases pour ajouter vos propre filtres à WordPress (décrites en détails ci-dessous) sont :
Une fonction de filtrage prend en entré les données non modifiées et retourne les données modifiées (ou dans certains cas, la valeur null pour indiquer que la donnée doit être supprimer ou qu'elle n'est pas valide). Si la donnée n'est pas modifiée par votre filtre, alors elle doit être retournée afin que les plugins suivants puissent la modifier si nécessaire.
La première étape pour la création d'un filtre dans votre plugin consiste à créer une fonction PHP pour faire le filtrage (votre fichier de plugin devra aller dans le répertoire wp-content/plugins). Par exemple, si vous voulez vous assurez que vos articles et commentaires ne contiennent pas de mots vulgaires, vous devrez définir une variable globale avec une liste de mots interdits et créer la fonction suivante :
function filter_profanity($content) {
global $profanities;
$content=str_ireplace($profanities,'{censored}',$content);
return $content;
}
Pourquoi ceci fonctionne sans boucle ? $profanities doit être un tableau et str_replace boucle sur le tableau pour vous.
NOTE : gardez à l'esprit que les autres plugins ou même WordPress utilisent peut-être déjà le nom de fonction que vous voulez utiliser. Voyez Avoiding Function Name Collisions (en anglais) pour plus d'informations.
Après la définition de votre fonction, l'étape suivante consiste à l'enregistrer dans WordPress. Pour faire ceci appelez add_filter() dans l'espace global d'exécution de votre plugin :
add_filter ( 'hook_name', 'your_filter', [priority], [accepted_args] );
Où :
Avec l'exemple précédent il faudrait placer le code suivant dans la section principale d'exécution du plugin pour indiquer à WordPress de filtrer les commentaires :
add_filter('comment_text','filter_profanity');
Vous pouvez également supprimer des filtres en utilisant la fonction remove_filter(). Voyez Supprimer les actions et les filtres.
La dernière étape consiste à installer et activer le plugin. La fonction PHP que vous avez écrite et l'appel à add_filter() doivent être placés ensemble dans un fichier PHP lui même installé dans le répertoire wp-content/plugins. Une fois installé, vous devez vous rendre dans la section d'administration de WordPress et activer votre plugin ; voyez Managing Plugins (en anglais) pour plus de détails.
Voyez Plugin API/Filter Reference (en anglais) pour la liste des filtres actuellement disponibles dans WordPress.
Il s'agit d'un exemple, décrit par Ozh sur la mailing-list wp-hackers pour un plugin qui modifie (ou surcharge) la fonction bloginfo(). On va donc modifier le comportement de base de WordPress.
add_filter('bloginfo', 'mybloginfo', 1, 2);
add_filter('bloginfo_url', 'mybloginfo', 1, 2);
function mybloginfo($result='', $show='') {
switch ($show) {
case 'wpurl':
$result = SITE_URL;
break;
case 'template_directory':
$result = TEMPL_DIR;
break;
default:
}
return $result;
}
Dans certains cas, vous trouverez nécessaire que votre plugin désactive une des actions ou l'un des filtres intégrés à WordPress, ou ajouté par un autre plugin. Vous pouvez faire ceci en appelant remove_filter('filter_hook','filter_function') ou remove_action('action_hook','action_function').
Par exemple, remove_action('publish_post','generic_ping'); permettra d'éviter l'envoi d'un ping à chaque fois qu'un nouvel article est créé.
Notez que si un "hook" a été enregistré en utilisant une priorité autre que le 10 par défaut, vous devrez également spécifier la priorité dans l'appel à remove_action(). Notez également qu'en général vous ne devez pas supprimer quelque chose sans savoir ce qu'il fait et pourquoi il le fait -- vérifiez le code source de WordPress ou des autres plugins pour être sûr.
En plus des "hooks" (actions et filtres) décrite ici, un autre moyen pour un plugin de modifier le comportement des fonctionnalité de WordPress consiste à surcharger les fonctions. En fait, il existe un petit jeu de fonctions que WordPress autorisent à redéfinir. Ces fonctions sont appelées Pluggable Functions (en anglais) et sont définies dans wp-includes/pluggable.php. WordPress charge ses fonctions seulement si elles ne sont toujours pas définies après le chargement de tout les plugins. Pour plus de détails, examinez le fichier wp-settings.php
Si votre plugin possède des tâches qui doivent être réalisées uniquement lors de l'activation ou de la désactivation, il peut utiliser register_activation_hook et register_deactivation_hook. La plus part des plugins n'ont pas besoins d'utiliser ces fonctions. Cependant, si votre plugin a besoin de modifier une des options par défaut à l'activation ou s'il a besoin de restaurer des changements fait précédemment, il peut utiliser ces fonction.
Creating Tables with Plugins (en anglais) est un exemple d'utilisation de register_activation_hook pour rendre la base de données compatible avec la version courante du plugin.