Un plugin_action_links qui disparaît après un simple renommage de dossier

« Réglages » a disparu de la liste des liens sous le nom de l’extension, sur l’écran des extensions installées. Rien d’autre n’a changé côté fonctionnel : les réglages existent toujours, la page correspondante répond normalement si l’on connaît son URL directe. Seul ce lien d’action rapide, pourtant présent depuis toujours, a silencieusement cessé de s’afficher après le renommage du dossier de l’extension, effectué à l’occasion d’un changement de marque commerciale.

Symptôme : le hook ne se déclenche plus après le renommage

Le lien « Réglages » (et tout autre lien d’action ajouté par l’extension) est enregistré via le hook plugin_action_links_{$plugin_file}, où $plugin_file correspond au résultat de plugin_basename() appliqué au fichier principal de l’extension — typiquement quelque chose comme ancien-nom-dossier/ancien-nom-dossier.php. Si ce nom exact est codé en dur dans l’appel à add_filter(), plutôt que déduit dynamiquement, le renommage du dossier change la valeur réelle du hook déclenché par WordPress, sans que le filtre enregistré ne corresponde plus.

// Code fautif : le nom du dossier est codé en dur
add_filter( 'plugin_action_links_ancien-nom-dossier/ancien-nom-dossier.php', function ( $liens ) {
    $liens[] = 'Réglages';
    return $liens;
} );

Après renommage du dossier en nouveau-nom-marque, WordPress déclenche désormais le hook plugin_action_links_nouveau-nom-marque/nouveau-nom-marque.php. Le filtre enregistré sous l’ancien nom n’est jamais appelé, et rien dans les journaux ne signale cette absence : le lien disparaît sans la moindre erreur.

Diagnostic : vérifier le nom réel attendu par WordPress

Le diagnostic le plus rapide consiste à afficher, temporairement, la valeur exacte retournée par plugin_basename( __FILE__ ) dans le fichier principal de l’extension, et à la comparer avec ce qui est codé en dur dans l’appel au filtre.

add_action( 'admin_notices', function () {
    error_log( 'Basename actuel : ' . plugin_basename( __FILE__ ) );
} );

Si la valeur affichée dans les journaux ne correspond plus à la chaîne codée en dur dans add_filter( 'plugin_action_links_...' ), la cause est confirmée : le hook cherché par WordPress et le hook réellement enregistré par le code ne coïncident plus.

Correctif : ne jamais coder le nom du dossier en dur

La correction consiste à construire dynamiquement le nom du hook à partir de plugin_basename( __FILE__ ), exécuté dans le contexte du fichier principal, plutôt que de recopier une chaîne fixe qui deviendra obsolète au moindre renommage futur.

add_filter( 'plugin_action_links_' . plugin_basename( __FILE__ ), function ( $liens ) {
    $liens[] = 'Réglages';
    return $liens;
} );

Cette version reste valide quel que soit le nom du dossier, présent ou futur, puisque plugin_basename() recalcule systématiquement la valeur attendue par WordPress à partir de l’emplacement réel du fichier au moment de l’exécution.

Prévention : auditer les autres endroits où le chemin pourrait être figé

Ce même piège se retrouve ailleurs dans une extension, sous des formes moins visibles : une URL d’asset construite avec le nom du dossier concaténé manuellement plutôt qu’avec plugins_url(), ou un chemin de fichier de traduction codé en dur plutôt que dérivé de plugin_dir_path( __FILE__ ). Un renommage de dossier, qu’il survienne pour une raison de marque ou simplement lors d’une réorganisation de dépôt, révèle systématiquement ces chemins figés.

• Recherche systématique du nom de dossier littéral dans l’ensemble du code avant tout renommage planifié.
• Remplacement par plugin_basename( __FILE__ ), plugin_dir_path( __FILE__ ) ou plugins_url( '', __FILE__ ) selon le besoin exact.
• Test de l’écran des extensions après renommage, pas seulement des fonctionnalités visibles côté front.

Vérifier aussi le nom de la constante de version, souvent lié au même schéma

Un piège proche concerne parfois la définition d’une constante de chemin, elle aussi construite à partir du nom du dossier au lieu d’une fonction native. Un audit rapide via une recherche du nom d’ancien dossier dans l’ensemble des fichiers PHP de l’extension permet de repérer ces occurrences résiduelles en une seule passe.

grep -rn "ancien-nom-dossier" chemin/vers/extension --include="*.php"

En résumé

Un renommage de dossier d’extension, même motivé par un simple changement de nom commercial, révèle systématiquement les chemins codés en dur qui n’auraient jamais dû l’être. Le lien d’action de la liste des extensions constitue l’un des symptômes les plus visibles de ce piège, précisément parce qu’il disparaît sans provoquer la moindre erreur signalée. plugin_basename( __FILE__ ) reste la seule source fiable pour construire ce hook, quel que soit le nom réel du dossier d’installation.