Comment créer un mu-plugin WordPress

Un mu-plugin WordPress (must-use plugin) est un fichier PHP placé dans wp-content/mu-plugins/ que WordPress charge automatiquement à chaque requête. Il ne peut pas être désactivé depuis l’administration et s’exécute avant tout plugin classique. Utilisez-le pour du code qui doit toujours être présent : hooks personnalisés, règles de sécurité, optimisations de performances ou constantes chargées tôt.

Un autre cas d’usage d’un mu-plugin consiste à ajouter des fonctions supplémentaires à un plugin ou au cœur de WP. Par exemple, WP STAGING propose de nombreux filtres et hooks qui peuvent enrichir la fonctionnalité de staging ou de sauvegarde de WP STAGING. Tous ces filtres documentés peuvent être ajoutés à un mu-plugin personnalisé.

Réponse rapide : déposez un fichier .php contenant un en-tête de plugin dans wp-content/mu-plugins/. WordPress le détecte au prochain chargement de page, sans aucune activation. Vérifiez dans Extensions → Extensions à utilisation obligatoire qu’il a bien été chargé.

Introduction aux must-use plugins

Les mu-plugins se trouvent dans wp-content/mu-plugins/ (le chemin est contrôlé par la constante WPMU_PLUGIN_DIR) et sont chargés par WordPress avant tout plugin de wp-content/plugins/. Ils n’apparaissent pas dans la liste standard des extensions et ne peuvent pas être désactivés depuis l’interface d’administration.

Le scénario le plus courant qui pousse les développeurs vers un mu-plugin : ils ont une fonction ou un filtre qui casse sans cesse parce qu’un autre administrateur désactive le plugin qui le contenait, ou parce qu’une mise à jour de plugin écrase une personnalisation. Un mu-plugin supprime ces deux risques d’un seul coup.

La documentation officielle de WordPress traite des must-use plugins sur wordpress.org/documentation/article/must-use-plugins/.

Comment un mu-plugin se compare-t-il aux autres emplacements où vous pourriez placer le même code ?

Avantages des mu-plugins

Le principal avantage par rapport à un plugin classique est la résistance aux manipulations. Un plugin classique peut être désactivé par n’importe quel utilisateur de niveau administrateur, ou supprimé si un identifiant est compromis. Un mu-plugin, non.

Utilisez un mu-plugin lorsque :

• Le code doit s’exécuter même si tous les plugins classiques sont désactivés (une redirection de maintenance, un en-tête de sécurité, une règle HTTPS forcée)
• Vous enregistrez des actions et des filtres WP STAGING qui doivent être chargés avant l’initialisation du plugin lui-même
• Vous gérez plusieurs sites WordPress et souhaitez un comportement propre à chaque site en dehors des plugins versionnés
• Vous voulez appliquer des réglages PHP à l’exécution (comme memory_limit) tôt dans le cycle de vie de la requête

Utilisez un plugin classique lorsque :

• La fonctionnalité doit pouvoir être activée ou désactivée par le propriétaire du site ou un développeur
• La fonctionnalité est livrée sous forme de produit installable avec mises à jour automatiques
• Vous construisez quelque chose que d’autres plugins détectent via is_plugin_active()

Comment créer un mu-plugin WordPress

Étape 1 : accédez aux fichiers de votre site

Connectez-vous à votre site via FTP, SFTP ou le gestionnaire de fichiers de votre hébergeur.

Étape 2 : localisez ou créez le répertoire mu-plugins

Rendez-vous dans wp-content/. Cherchez le dossier mu-plugins/. S’il n’existe pas, créez-le. WordPress se met immédiatement à charger les fichiers PHP de ce répertoire, sans configuration supplémentaire.

Étape 3 : créez le fichier de votre plugin

Créez un nouveau fichier PHP, par exemple my-mu-plugin.php. Utilisez des lettres minuscules et des traits d’union (pas d’espaces) dans le nom du fichier. Le nom du fichier apparaît dans Extensions → Extensions à utilisation obligatoire de l’administration WordPress, choisissez donc un nom parlant.

Étape 4 : ajoutez l’en-tête du plugin et votre code

Chaque mu-plugin a besoin d’un commentaire d’en-tête de plugin en haut, exactement comme un plugin classique. Voici la structure minimale :

<?php
/*
Plugin Name: My Custom Mu-Plugin
Description: A custom must-use plugin to enhance my WordPress site.
Version: 1.0
Author: Mickey Mouse
*/

// Your custom code goes here

Étape 5 : envoyez votre mu-plugin

Téléversez le fichier .php dans wp-content/mu-plugins/ sur votre serveur.

Étape 6 : vérifiez l’activation

Il n’y a aucune étape d’activation. Rendez-vous dans Extensions → Extensions à utilisation obligatoire de l’administration WordPress pour confirmer que le fichier a été chargé. S’il n’apparaît pas, vérifiez que le fichier se trouve directement dans mu-plugins/ (et non dans un sous-répertoire).

Exemple de mu-plugin : texte de pied de page d’administration personnalisé

Voici un exemple complet et fonctionnel qui modifie le texte du pied de page affiché en bas de chaque écran d’administration WordPress :

<?php
/*
Plugin Name: Custom Admin Footer
Description: Changes the footer text in the WordPress admin area.
Version: 1.0
Author: Your Name
*/

add_filter('admin_footer_text', function () {
    echo 'Customized by Tony Stark - Powered by WordPress';
});

Cas d’usage courants des mu-plugins

Voici les schémas qui reviennent le plus souvent dans les tickets de support WP STAGING et sur les forums de développeurs :

1. Forcer la journalisation de débogage sans modifier wp-config.php

<?php
/*
Plugin Name: Enable Debug Log
*/
if ( ! defined( 'WP_DEBUG' ) ) {
    define( 'WP_DEBUG', true );
}
if ( ! defined( 'WP_DEBUG_LOG' ) ) {
    define( 'WP_DEBUG_LOG', true );
}
if ( ! defined( 'WP_DEBUG_DISPLAY' ) ) {
    define( 'WP_DEBUG_DISPLAY', false );
}

C’est pratique sur des environnements de staging ou de développement où vous voulez activer la journalisation sans toucher au wp-config.php de production. Consultez Enable WordPress Debug Log Mode pour le flux de débogage complet.

2. Augmenter la limite de mémoire PHP

La directive ini memory_limit peut être modifiée à l’exécution via ini_set(), ce qui fait d’un mu-plugin un endroit propre pour l’appliquer avant le chargement des plugins classiques :

<?php
/*
Plugin Name: Increase Memory Limit
*/
@ini_set( 'memory_limit', '256M' );

Remarque : certains réglages PHP sont fixés au niveau du serveur et ne peuvent pas être modifiés via ini_set() à l’exécution. Une référence complète des directives qui acceptent des changements à l’exécution est disponible sur php.net/manual/en/ini.list.php.

3. Code de filtres WP STAGING

WP STAGING expose des actions et des filtres documentés pour contrôler le comportement de sauvegarde et de staging. Comme ils doivent être chargés avant l’initialisation de WP STAGING lui-même, un mu-plugin est le bon endroit pour les enregistrer. Placez n’importe quel appel add_filter() ou add_action() dans un fichier mu-plugin et il sera toujours présent, quel que soit l’ordre d’activation des plugins. Parcourez tous les hooks disponibles dans la documentation des actions et filtres WP STAGING, liée plus bas dans Articles connexes.

4. Redirection HTTPS forcée

<?php
/*
Plugin Name: Force HTTPS
*/
add_action( 'template_redirect', function () {
    if ( ! is_ssl() ) {
        wp_redirect( 'https://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'], 301 );
        exit;
    }
} );

5. Désactiver XML-RPC

<?php
/*
Plugin Name: Disable XML-RPC
*/
add_filter( 'xmlrpc_enabled', '__return_false' );

Limites et points de vigilance

Avant de vous engager sur un mu-plugin, quelques comportements méritent d’être connus :

Aucun hook de désactivation ni de désinstallation. WordPress ne déclenche jamais deactivate_{plugin} ni uninstall_{plugin} pour les mu-plugins. Si votre plugin crée des options, des tables personnalisées ou des tâches cron planifiées, vous devez les nettoyer manuellement : supprimez le fichier, puis retirez à la main les données stockées.

Le chargement depuis un sous-répertoire nécessite un fichier de chargement. WordPress ne charge que les fichiers PHP placés directement dans wp-content/mu-plugins/. Si vous placez du code dans un sous-répertoire (par exemple, mu-plugins/my-plugin/my-plugin.php), WordPress ne le détectera pas. Le schéma habituel consiste à créer un fichier de chargement léger à la racine de mu-plugins/ qui appelle require_once sur le fichier du sous-répertoire.

Comportement en multisite. Sur un réseau multisite WordPress, les mu-plugins se chargent sur chaque site à chaque requête. Il n’y a pas d’interrupteur par site. Utilisez is_main_site() ou get_current_blog_id() à l’intérieur du plugin si vous devez limiter le comportement à un site précis du réseau.

Ordre de chargement. Les mu-plugins se chargent par ordre alphabétique croissant du nom de fichier, avant tout plugin de wp-content/plugins/. Si l’ordre entre vos mu-plugins compte, préfixez les noms de fichiers : 00-runs-first.php, 10-runs-second.php.

Visibilité dans l’administration. Les mu-plugins apparaissent dans Extensions → Extensions à utilisation obligatoire, mais n’affichent aucun détail à moins que l’en-tête du plugin ne comporte Plugin Name, Description et Version. Ajoutez toujours un en-tête ; cela accélère nettement le diagnostic en cas de problème.

Aucun mécanisme de mise à jour. WordPress n’a aucun moyen intégré de vous avertir des mu-plugins ni de les mettre à jour. Si vous adaptez du code tiers pour un mu-plugin, c’est à vous de suivre les mises à jour et de les appliquer manuellement. Pour des mu-plugins développés en interne, ce n’est pas un souci, mais cela mérite d’être noté si vous envisagez de convertir un plugin communautaire en mu-plugin.

Où placer ce code ?

Une règle empirique utile : si votre code appelle une fonction WordPress (add_filter, get_option, wp_redirect, etc.), placez-le dans un mu-plugin. S’il s’agit d’un simple define() PHP ou d’un réglage qui doit s’exécuter avant le démarrage de WordPress, wp-config.php est le bon endroit.

Conclusion

Un mu-plugin est l’outil adapté au code qui doit toujours s’exécuter et ne peut pas risquer d’être désactivé par accident. La mise en place prend quelques minutes : créez wp-content/mu-plugins/, ajoutez un fichier .php avec un en-tête de plugin, et WordPress s’occupe du reste.

Si vous développez ou testez du code de mu-plugin personnalisé, nous vous recommandons de le vérifier dans un environnement de staging avant de le déployer en production. WP STAGING permet de cloner facilement votre site en production et de confirmer que le mu-plugin se comporte comme prévu avant que vos changements ne soient mis en ligne.

Articles connexes

• How to Create and Add an Admin User With MySQL in WordPress
• WP Staging Actions and Filters
• Enable WordPress Debug Log Mode
• Grant Custom User access to the Staging Site
• How to Delete a WordPress Plugin Manually via FTP

Auteur : Rene Hermenau

À propos de l'auteur : René Hermenau est le fondateur de WP STAGING. Il travaille sur les sauvegardes WordPress, les environnements de staging, les migrations, la gestion des bases de données et les workflows de déploiement sécurisés.

Voir le profil complet de l'auteur Rene Hermenau