Créer un plugin WordPress : guide pour débutants

Un plugin WordPress, pourquoi et comment

Les plugins étendent WordPress. Pour une PME, plutôt que d’accumuler du code custom dans le thème ou des fichiers épars, créer un plugin dédié structure les développements, facilite la maintenance, et peut être réutilisé sur plusieurs sites. Ce tutoriel guide la création d’un plugin basique pour comprendre les concepts, avec une approche pragmatique accessible aux développeurs qui débutent.

Les concepts fondamentaux

Un plugin est un dossier contenant au moins un fichier PHP avec un en-tête spécial. WordPress détecte automatiquement les plugins dans wp-content/plugins/. Une fois activé, le code du plugin s’exécute aux points appropriés du cycle WordPress.

L’interaction avec WordPress se fait via hooks : actions (faire quelque chose à un moment précis) et filters (modifier une valeur). Ces hooks sont la clé de l’extension WordPress.

Créer la structure

Dans wp-content/plugins/, créez un dossier mon-plugin/. À l’intérieur, un fichier mon-plugin.php avec l’en-tête :

<?php
/*
Plugin Name: Mon Plugin
Description: Description de mon plugin
Version: 1.0.0
Author: Votre Nom
License: GPL v2 or later
*/

Cet en-tête suffit pour que WordPress reconnaisse le plugin. Dans l’administration WordPress, Extensions > Extensions installées : votre plugin apparaît, prêt à être activé.

Votre premier hook

Ajoutons une fonctionnalité. Modifier le footer pour ajouter une mention. Dans mon-plugin.php :

function mon_plugin_ajouter_footer() {
    echo '<div class="mon-footer-custom">Propulsé par mon plugin</div>';
}
add_action('wp_footer', 'mon_plugin_ajouter_footer');

Le hook wp_footer s’exécute dans le footer des pages publiques. Notre fonction y affiche du texte. Active le plugin et visite le site : le texte apparaît.

Les hooks action et filter

Actions : faire quelque chose. « Envoyer un email quand un nouveau post est publié ». add_action(‘publish_post’, ‘ma_fonction’);.

Filters : modifier une valeur. « Ajouter du texte à la fin de chaque article ». add_filter(‘the_content’, ‘ma_fonction’);. Dans ma_fonction, recevoir le contenu, le modifier, le retourner.

La documentation WordPress liste des centaines de hooks. Chercher un hook adapté à votre besoin avant de réinventer.

Ajouter un shortcode

Les shortcodes insèrent du contenu dynamique dans les articles et pages. [mon-shortcode] peut afficher une date, un formulaire, du contenu dynamique.

function mon_shortcode_date($atts) {
    return 'Nous sommes le ' . date('d/m/Y');
}
add_shortcode('date-jour', 'mon_shortcode_date');

Dans une page, [date-jour] affichera la date actuelle. Les attributs passés (shortcode [date-jour format= »Y »]) se récupèrent via $atts.

Ajouter un widget

Les widgets s’ajoutent dans les zones de widgets du thème. Création plus verbose, via une classe qui étend WP_Widget. Documentation officielle détaille la structure.

Pour un besoin simple, un shortcode peut suffire et être plus flexible.

Un widget WordPress hérite de la classe WP_Widget dont les méthodes obligatoires sont widget(), form() et update(). Enregistrez-le via le hook widgets_init avec register_widget('MaClasse'). Depuis la version 5.8 (juillet 2021), WordPress recommande de migrer les widgets vers des blocs Gutenberg via la fonction register_block_type. Pour un blog tech francophone à Sicap Liberté, créer un widget moderne signifie déclarer un bloc dynamique en PHP qui rend une liste de derniers articles ou une zone de promotion. Les widgets classiques restent supportés mais ne bénéficient plus des améliorations d’éditeur.

Ajouter une page d’administration

Pour configurer le plugin depuis l’admin. add_menu_page ou add_options_page créent des pages dans le menu.

function mon_plugin_menu() {
    add_menu_page(
        'Mon Plugin',       // titre de la page
        'Mon Plugin',       // libellé menu
        'manage_options',   // capacité requise
        'mon-plugin',       // slug
        'mon_plugin_page'   // fonction qui affiche
    );
}
add_action('admin_menu', 'mon_plugin_menu');

function mon_plugin_page() {
    echo '<h1>Ma page d\'administration</h1>';
}

Stocker des options

Pour persister des configurations. Les fonctions WordPress add_option, get_option, update_option, delete_option gèrent.

update_option('mon_plugin_param', 'valeur');
$valeur = get_option('mon_plugin_param', 'defaut');

Stocker de manière organisée : un seul option array plutôt que plusieurs options individuelles. Facilite la gestion et économise les requêtes base de données.

WordPress fournit l’API Options pour persister des paramètres de configuration en base. Les fonctions clés sont add_option(), get_option(), update_option() et delete_option(). Préfixez systématiquement vos clés avec un identifiant unique (ex. monplugin_seuil_alerte) pour éviter les collisions avec d’autres extensions. Pour des structures complexes, sérialisez un tableau associatif et utilisez une seule option racine plutôt que dix options dispersées. WordPress autocharge par défaut les options dans wp_options, ce qui pèse sur les performances : passez le paramètre autoload à no pour les options rarement lues.

Créer un formulaire de configuration

Une page d’administration avec formulaire pour configurer le plugin. L’API Settings de WordPress standardise cette création. register_setting, add_settings_section, add_settings_field définissent la structure. Le formulaire s’affiche et se traite automatiquement.

L’API Settings de WordPress génère automatiquement les pages d’options propres et sécurisées. Le pattern type combine quatre fonctions : add_settings_section() définit une section, add_settings_field() ajoute un champ, register_setting() déclare l’option et son sanitize callback, enfin settings_fields() et do_settings_sections() rendent le formulaire dans la page admin. La fonction sanitize est non négociable : elle doit nettoyer chaque entrée utilisateur avec sanitize_text_field(), esc_url_raw() ou absint() selon le type. Sans elle, vous ouvrez la porte aux injections XSS.

Les types de publication personnalisés

Pour ajouter un type de contenu (produits, événements, témoignages), les Custom Post Types. register_post_type crée le type.

function mon_plugin_cpt() {
    register_post_type('evenement', array(
        'labels' => array(
            'name' => 'Événements',
            'singular_name' => 'Événement'
        ),
        'public' => true,
        'supports' => array('title', 'editor', 'thumbnail')
    ));
}
add_action('init', 'mon_plugin_cpt');

Un nouveau type apparaît dans l’admin, avec son propre éditeur.

Les taxonomies personnalisées

Pour organiser les contenus custom. Catégories et tags dédiés via register_taxonomy. Permet de structurer sans se mélanger aux catégories du blog.

Une taxonomie personnalisée classe un type de contenu selon une logique propre à votre plugin (genres pour des livres, régions pour des restaurants, niveaux pour des cours). La fonction register_taxonomy() appelée sur le hook init déclare la taxonomie et ses libellés. Choisissez entre hiérarchique (comme les catégories, avec parents et enfants) ou non-hiérarchique (comme les étiquettes). Liez la taxonomie à un ou plusieurs CPT via le second argument. Les taxonomies enrichissent le SEO en créant des archives dédiées et améliorent la navigation utilisateur via des filtres et des nuages de tags.

La base de données

Pour les données complexes qui ne rentrent pas dans les CPT, créer des tables custom est possible. La classe wpdb interagit avec la base. Usage limité aux cas où les CPT ne suffisent vraiment pas ; souvent, un CPT avec meta fields couvre les besoins.

Pour des données qui ne s’inscrivent pas dans le modèle posts/meta de WordPress (logs, transactions, stocks), créez vos propres tables via $wpdb->query() ou dbDelta() au moment de l’activation du plugin. Préfixez le nom de table avec $wpdb->prefix pour respecter le préfixe configuré. Toutes les requêtes doivent passer par $wpdb->prepare() qui échappe les paramètres et bloque les injections SQL. À la désactivation propre, prévoyez l’option de supprimer les tables via une commande utilisateur explicite, jamais automatiquement, pour éviter la perte de données accidentelle.

Les meta fields

Associer des données supplémentaires à un post. add_post_meta, get_post_meta, update_post_meta. Advanced Custom Fields (plugin) facilite grandement la gestion avec interface graphique.

Les meta fields stockent des informations attachées à un post, un utilisateur ou un terme. Les fonctions add_post_meta(), get_post_meta() et update_post_meta() couvrent 90% des cas. Depuis WordPress 4.6, l’API REST expose nativement les meta enregistrés via register_post_meta() avec show_in_rest = true. Cela permet à un frontend headless React ou Vue de lire et modifier les meta sans plugin tiers. Pour les interfaces d’administration sophistiquées, le plugin gratuit Advanced Custom Fields reste l’outil de référence depuis plus de 10 ans.

Les scripts et styles

Charger du CSS et JavaScript. wp_enqueue_script et wp_enqueue_style sont les fonctions recommandées. Chargement conditionnel : enqueue uniquement sur les pages qui en ont besoin pour éviter d’alourdir inutilement.

function mon_plugin_scripts() {
    wp_enqueue_style('mon-plugin-css', plugin_dir_url(__FILE__) . 'style.css');
    wp_enqueue_script('mon-plugin-js', plugin_dir_url(__FILE__) . 'script.js');
}
add_action('wp_enqueue_scripts', 'mon_plugin_scripts');

Toujours enregistrer les assets JavaScript et CSS via wp_enqueue_script() et wp_enqueue_style(), jamais en hardcodant des balises script ou link dans le head. WordPress gère ainsi la déduplication, l’ordre de chargement et les dépendances automatiquement. Préfixez les handles avec votre slug de plugin pour éviter les conflits. Utilisez le quatrième argument de wp_enqueue_script (true) pour charger le script en pied de page et améliorer le LCP. Pour les performances mobiles sur connexion 4G ouest-africaine, inscrivez aussi le hook wp_enqueue_scripts conditionnellement (uniquement sur les pages où le script sert).

La sécurité

Préoccupations essentielles. Validation et sanitation des entrées utilisateur (sanitize_text_field, esc_html, etc.). Nonces pour les formulaires et actions sensibles (wp_create_nonce, wp_verify_nonce). Vérification des capacités utilisateur (current_user_can). Requêtes paramétrées pour la base ($wpdb->prepare).

Un plugin mal sécurisé peut être une porte d’entrée pour les attaquants. La sécurité dès la conception.

Trois piliers protègent un plugin WordPress en production. Premièrement, valider et nettoyer toutes les entrées utilisateur avec les fonctions sanitize_*() de WordPress. Deuxièmement, vérifier les permissions via current_user_can('manage_options') avant toute action sensible. Troisièmement, protéger les formulaires avec des nonces générés par wp_create_nonce() et vérifiés par wp_verify_nonce() pour bloquer les attaques CSRF. Pour les requêtes AJAX, utilisez les hooks wp_ajax_* avec vérification de nonce systématique. Une faille dans un plugin populaire compromet des milliers de sites en quelques heures.

Les traductions

Pour un plugin utilisé dans plusieurs langues. Chaînes traduisibles avec __() et _e(). Fichier .pot généré avec wp i18n make-pot (WP-CLI). Traductions dans .po/.mo dans un dossier languages/.

Internationaliser un plugin commence par envelopper toutes les chaînes affichées dans __() ou esc_html__() avec un text-domain unique (ex. monplugin). Chargez les traductions au hook plugins_loaded avec load_plugin_textdomain('monplugin', false, dirname(plugin_basename(__FILE__)) . '/languages'). Générez le fichier .pot via WP-CLI commande wp i18n make-pot. Pour la traduction française au Sénégal, fournissez fr_SN ou fr_FR selon votre cible. WordPress.org traduit gratuitement les plugins publiés via la communauté GlotPress, ce qui peut couvrir 30+ langues sans effort supplémentaire.

Tester le plugin

Environnements. Développement local (Local by Flywheel, XAMPP, DevKinsta). Staging en ligne pour tester dans des conditions proches de la production. Tests unitaires avec PHPUnit pour les plugins matures.

Activer et désactiver le plugin régulièrement pour vérifier que rien ne casse l’administration ou le frontend.

Le test minimum d’un plugin couvre trois plans. Test fonctionnel manuel sur une installation WordPress propre via Local WP ou Lando. Test de compatibilité avec les versions PHP supportées (8.1, 8.2, 8.3 minimum en 2026) via Docker images officielles. Test automatisé unitaire avec PHPUnit et le framework de tests WordPress (wp-cli scaffold plugin-tests). Pour un plugin distribué publiquement, prévoyez aussi un test sur le multisite (wpmu) qui révèle souvent des bugs de stockage d’options globales versus blog-spécifiques. Sans cette discipline, votre plugin casse à la première mise à jour majeure de WordPress.

La structure du plugin avancée

Un plugin qui grandit doit être structuré. Fichier principal court qui déclare et initialise. Classes dans des fichiers séparés. Namespaces PHP pour éviter les conflits. Autoload avec Composer. Séparation clair des responsabilités (admin, public, API, etc.).

Au-delà de 200 lignes, un plugin gagne à être structuré en classes PHP autoloadées via Composer. Le pattern type sépare le bootstrap (fichier principal), le namespace MonPlugin\ pour la logique, et un dossier languages, assets, templates. Évitez d’inclure des libs tierces hors Composer pour ne pas dupliquer leur code à travers les plugins. Le standard WordPress Plugin Boilerplate (WPPB) offre un squelette mature et documenté. Pour des projets industriels, le pattern Singleton ou Service Container facilite les tests unitaires et l’évolution sur plusieurs années.

La distribution

Partager son plugin. Utilisation privée : copier sur d’autres sites. Distribution via le WordPress.org plugin directory : soumission pour review, hébergement gratuit, visibilité. Distribution commerciale : votre propre site, plateformes comme CodeCanyon.

La distribution publique demande qualité du code, documentation, support.

Pour distribuer un plugin gratuit, soumettez-le sur wordpress.org via le formulaire dédié. Le repository officiel exige un readme.txt formaté en SVN markdown, des règles strictes (pas d’appels externes non documentés, pas de tracking utilisateur sans consentement explicite, code GPL compatible). Le processus de revue prend 2 à 6 semaines. Pour un plugin commercial, distribuez via votre site avec un système de licences (Easy Digital Downloads, WooCommerce Software Add-on). Tarifs typiques : licence annuelle 49 à 199 USD pour un plugin SaaS spécialisé. Une page de support claire et un changelog public construisent la confiance des acheteurs.

Les bonnes pratiques

Conformité aux standards de codage WordPress. Préfixer toutes les fonctions et variables globales pour éviter les conflits. Code documenté. Respect de la vie privée (pas de télémétrie sans consentement). Compatibilité avec les versions récentes de WordPress et PHP.

Cinq règles distinguent un plugin professionnel d’un plugin amateur. Suivre les WordPress Coding Standards (espacement, nommage avec snake_case pour les fonctions). Documenter chaque fonction publique avec des PHPDoc complets. Utiliser le Customizer ou les Options API plutôt que d’éditer wp-config.php. Activer WP_DEBUG pendant le développement et vérifier l’absence de notice ou warning. Maintenir un fichier CHANGELOG.md daté avec sémantique versioning (1.2.3) qui distingue clairement bug fixes, features et breaking changes pour vos utilisateurs.

Quand créer un plugin versus un thème

Règle importante : les fonctionnalités (formulaires, shortcodes, CPT) doivent être dans un plugin, pas dans le thème. Si on change de thème, les fonctionnalités doivent persister. Le thème gère la présentation ; le plugin gère la logique métier.

La règle communautaire WordPress depuis 2010 reste valide : un thème gère l’apparence (CSS, templates, blocks), un plugin gère les fonctionnalités (post types, intégrations, logique métier). Si une fonctionnalité doit survivre à un changement de thème (catalogue produits, formulaires de contact, intégration CRM), elle appartient à un plugin. Les agences qui mélangent les deux dans un thème custom créent une dette technique douloureuse : le client ne peut plus changer le design sans tout perdre. Cette discipline pèse 30 minutes au démarrage et évite des semaines de migration plus tard.

Apprendre en pratiquant

Codex WordPress (developer.wordpress.org) : documentation officielle exhaustive. Code source d’autres plugins : regarder comment ils font. Communauté WordPress : forums, groupes Facebook, meetups.

La meilleure façon de progresser est de créer trois petits plugins pour vous-même avant un plugin commercial. Premier projet : un shortcode qui affiche les heures d’ouverture d’un commerce. Deuxième projet : un widget qui synchronise une liste depuis une API REST publique (météo, taux de change FCFA-EUR). Troisième projet : un CPT minimal avec admin sur-mesure. Cette progression couvre 80% des patterns que vous rencontrerez dans des projets clients à Dakar, Abidjan ou Lomé. Inscrivez-vous au Slack WordPress France et au site officiel developer.wordpress.org pour accélérer la montée en compétence.

Conclusion : compétence utile

Savoir créer des plugins ouvre des possibilités pour toute PME qui utilise WordPress. Plutôt que d’accumuler des hacks dans le thème ou d’acheter mille plugins commerciaux, un plugin custom pour vos besoins spécifiques structure le développement. Démarrez avec un plugin simple répondant à un besoin concret : une fonction répétitive, un shortcode utile, une intégration spécifique. La prise en main est rapide ; la maîtrise se construit avec l’expérience.