Désynchronisation WP-CLI et WordPress : causes et solutions

Les versions de plugins affichées par WP-CLI diffèrent souvent de celles du back-office WordPress à cause du système de cache transient. Ce problème bien documenté touche particulièrement les sites utilisant Redis ou Memcached, et les plugins premium. La mise à jour WP-CLI v2.12.0 (mai 2025) introduit le flag --force-check qui résout la plupart des cas, mais des solutions manuelles restent nécessaires pour les configurations complexes.

Comment WordPress détecte les mises à jour de plugins

Le mécanisme de détection repose sur la fonction wp_update_plugins() qui stocke les informations dans le transient update_plugins (enregistré comme _site_transient_update_plugins en base de données). WordPress interroge l’API api.wordpress.org et met en cache la réponse avec des délais variables selon le contexte : 1 minute lors du chargement de update-core.php, mais jusqu’à 12 heures dans d’autres contextes comme les appels CLI.

WP-CLI lit directement ce transient sans forcément le rafraîchir, contrairement à la page d’administration qui déclenche une vérification immédiate. Cette différence de comportement constitue la source principale des désynchronisations observées.

Pourquoi WP-CLI et l’admin WordPress ne sont pas synchronisés ?

L’isolation du cache objet représente la cause la plus fréquente. Avec Redis ou Memcached, les processus CLI et web fonctionnent dans des espaces mémoire distincts. Les modifications effectuées via WP-CLI sont bien enregistrées en base de données, mais le cache objet du serveur web conserve des données obsolètes. Le GitHub issue #283 documente ce problème depuis 2013, avec un avertissement spécifique implémenté pour APC : « Running WP-CLI while the APC object cache is activated can result in cache corruption. »

Le contexte is_admin() affecte particulièrement les plugins premium. Ces extensions utilisent souvent des vérifications is_admin() avant d’enregistrer leurs filtres de mise à jour. Comme WP-CLI retourne false pour cette fonction, les hooks de détection ne s’exécutent jamais. L’issue #106 du repository extension-command détaille ce comportement : des plugins comme User Role Editor Pro ou WooCommerce Subscriptions n’apparaissent pas dans le transient update_plugins en contexte CLI.

Les permissions fichiers créent des incohérences silencieuses. L’issue #90 révèle un bug critique : wp plugin update --all affiche « Success: Plugin already updated » même lorsque la mise à jour échoue à cause de permissions insuffisantes. Le message d’erreur réel apparaît uniquement dans les logs, masquant le problème à l’utilisateur.

Les configurations wp-config.php peuvent bloquer les mises à jour. Les constantes DISALLOW_FILE_MODS, AUTOMATIC_UPDATER_DISABLED et FS_METHOD modifient le comportement de détection. Une valeur FS_METHOD incorrecte ou DISALLOW_FILE_MODS à true empêche toute mise à jour.

La solution native depuis WP-CLI v2.12.0

La version 2.12.0 publiée en mai 2025 introduit le flag --force-check spécifiquement pour résoudre ce problème de synchronisation. La commande efface automatiquement les transients avant d’afficher les résultats :

wp plugin list --fields=name,status,update,version,update_version --force-check

Les notes de version précisent : « When displaying the list of plugins or themes, WP-CLI now always ensures you get fresh data. No need to manually clear transients anymore! » Cette modification provient des pull requests #446 et #426 du repository extension-command.

Solutions manuelles pour versions antérieures

Pour les environnements utilisant des versions plus anciennes de WP-CLI, une séquence de commandes résout systématiquement les désynchronisations. La suppression du transient update_plugins force WordPress à interroger l’API lors du prochain appel :

wp transient delete update_plugins --network
wp eval "wp_update_plugins();"
wp plugin list --update=available

Pour les sites utilisant un cache objet persistant, le flush préalable est indispensable :

wp cache flush
wp transient delete --all --network
wp eval "delete_site_transient('update_plugins'); wp_update_plugins();"

En environnement multisite, chaque site possède potentiellement ses propres transients. Une boucle complète les efface tous :

wp transient delete --all --network && wp site list --field=url | xargs -n1 -I % wp --url=% transient delete --all

Corrections des problèmes de permissions

L’exécution de WP-CLI avec le même utilisateur que le serveur web élimine les conflits de permissions. Sur un serveur Nginx typique :

sudo -u www-data wp plugin update --all

Les permissions standard WordPress requièrent 755 pour les répertoires et 644 pour les fichiers. Le répertoire wp-content nécessite des droits d’écriture (775) pour permettre les mises à jour. Une vérification rapide identifie les incohérences :

find /var/www/html/wp-content/plugins -type d ! -perm 755 -exec ls -la {} \;

Cas particulier des plugins premium

Les plugins non hébergés sur wordpress.org (ACF Pro, WooCommerce extensions, Gravity Forms) requièrent une approche spécifique. Ces extensions implémentent leurs propres systèmes de mise à jour qui dépendent souvent du contexte admin. Une solution documentée dans l’issue #106 consiste à simuler ce contexte :

// Fichier wp-admin-mock.php
<?php
if (!defined('WP_ADMIN')) {
    define('WP_ADMIN', true);
}
wp plugin update --all --require=wp-admin-mock.php

Cette technique force les hooks de mise à jour des plugins premium à s’enregistrer correctement.

Pourquoi Redis aggrave les désynchronisations WP-CLI ?

La cohérence de configuration entre les contextes CLI et web prévient la plupart des désynchronisations Redis. Dans wp-config.php, les paramètres doivent être identiques quel que soit le contexte d’exécution :

define('WP_REDIS_HOST', '127.0.0.1');
define('WP_REDIS_PORT', 6379);
define('WP_REDIS_DATABASE', 0);
define('WP_CACHE_KEY_SALT', 'monsite_');  // Préfixe constant

Pour le débogage, Redis peut être temporairement désactivé en CLI :

if (defined('WP_CLI') && WP_CLI) {
    define('WP_REDIS_DISABLED', true);
}

Workflow de diagnostic complet

Une procédure systématique identifie rapidement la source du problème. Vérifier d’abord l’état du cache objet :

wp eval "echo wp_using_ext_object_cache() ? 'Cache externe: OUI' : 'Cache externe: NON';"

Comparer ensuite le contenu du transient avec les plugins installés :

wp eval "var_dump(array_keys(get_site_transient('update_plugins')->response ?? []));"
wp plugin list --fields=name,version,update_version

Un écart entre ces deux sorties confirme une désynchronisation du transient.

Ce qu’il faut retenir pour éviter les désynchronisations WP-CLI

Les désynchronisations entre WP-CLI et le back-office WordPress résultent principalement du cache transient et de l’isolation des caches objets. La mise à jour vers WP-CLI 2.12.0 et l’utilisation du flag --force-check constituent la solution la plus simple. Pour les environnements contraints, la séquence wp cache flush && wp transient delete update_plugins --network && wp eval "wp_update_plugins();" résout systématiquement le problème. Les plugins premium nécessitent une attention particulière en raison de leurs dépendances au contexte is_admin(). La cohérence des configurations Redis/Memcached et l’exécution de WP-CLI sous le même utilisateur que le serveur web préviennent la majorité des cas de désynchronisation.