WordPress.org

Ready to get started?Download WordPress

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

User:Guigui/fr:Plugin API

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.

This article is marked as in need of editing. You can help Codex by editing it.

Introduction

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.

Hooks, Actions et Filtres

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" :

  1. Actions: les actions sont exécutées par WordPress à des moments précis durant l'exécution où lorsqu'un évènement particulier arrive. Votre plugin peut spécifier qu'une ou plusieurs de ses fonctions PHP seront exécutées a ces moments là en utilisant l'API action.
  2. Filtres: les filtres sont exécutés par WordPress pour modifier du texte ou des types avant leur ajout dans la base de données ou dans le navigateur. Votre plugin peut spécifier qu'une ou plusieurs de ses fonctions PHP seront exécutées pour modifier les types où le texte à ces moment là en utilisant l'API filtre.

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).

Fonctions de base

Filtres
Actions

Actions

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 :

  • Modifier la base de données
  • Envoyez un email
  • Modifier ce qui est affiché dans les navigateur

Les étapes de base pour faire ceci (décrites plus en détail ci-dessous) sont les suivantes :

  1. Créer la fonction PHP qui doit être exécutée lorsque l'évènement arrive dans votre plugin.
  2. Enregistrer l'action dans WordPress en appelant add_action()
  3. Mettre votre fonction PHP dans un fichier de plugin et l'activer.

Créer une fonction d'action

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.

S'enregistrer à WordPress

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ù :

hook_name 
le nom de l'action WordPress, ceci indique avec quel évènement votre fonction doit être associée.
your_function_name 
le nom de la fonction que vous voulez exécutée lors de l'évènement spécifié par hook_name. Ceci peut-être une fonction standard de PHP, une fonction WordPress ou une fonction de votre plugin (comme 'email_friends' dans l'exemple précédent).
priority 
un paramètre entier optionnel qui peut être utilisé pour spécifier l'ordre dans lequel les fonctions associées à une action données sont exécutées (par défaut : 10). Plus le chiffre est faible, plus l'exécution sera prioritaire. Les fonctions avec une priorité identique seront exécutées dans l'ordre dans lequel elles ont été ajoutées à l'action.
accepted_args 
un paramètre entier optionnel définissant combien d'argument votre fonction peut accepter (par défaut : 1). Utile car certains "hook" peuvent passer plus d'un paramètre à votre fonction. Ce paramètre est présent depuis la release 1.5.1.

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.

Installation et activation

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.

Hooks pour les actions

Voyez Plugin API/Action Reference (en anglais) pour la liste des actions actuellement disponibles dans WordPress.

Filtres

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 :

  1. Créer la fonction PHP qui va filtrer les données.
  2. Enregistrer le filtre dans WordPress en appelant add_filter()
  3. Mettre votre fonction PHP dans un fichier de plugin et l'activer.

Créer une fonction de filtrage

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.

S'enregistrer à WordPress

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ù :

hook_name 
Le nom du filtre WordPress qui détermine quand votre filtre sera appliqué.
your_filter 
Le nom de la fonction que vous voulez utiliser pour le filtrage. Ceci peut-être une fonction PHP standard, une fonction WordPress ou une fonction de votre propre fichier de plugin.
priority 
un paramètre entier optionnel qui peut être utilisé pour spécifier l'ordre dans lequel les fonctions associées à un filtre donnés sont exécutées (par défaut : 10). Plus le chiffre est faible, plus l'exécution sera prioritaire. Les fonctions avec une priorité identique seront exécutées dans l'ordre dans lequel elles ont été ajoutées au filtre.
accepted_args 
un paramètre entier optionnel définissant combien d'argument votre fonction peut accepter (par défaut : 1). Utile car certains hook peuvent passer plus d'un paramètre à votre fonction.

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.

Installation et activation

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.

Hooks pour les filtres

Voyez Plugin API/Filter Reference (en anglais) pour la liste des filtres actuellement disponibles dans WordPress.

Exemple

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;
}

Supprimer les actions et les filtres

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.

Pluggable fonctions

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

Activation/Désactivation

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.