« Impossible de mettre à jour une entrée qui n’existe pas » : ce genre de message, courant dans d’autres systèmes de cache, met le doigt sur une nuance que wp_cache_set() seule ne permet pas d’exprimer. Cette dernière écrase ou crée une entrée sans distinction, ce qui est parfait la plupart du temps, mais problématique dès qu’une entrée absente doit rester absente.
wp_cache_replace() comble cette nuance : elle ne modifie une valeur que si la clé existe déjà dans le cache, et retourne false sinon, sans jamais créer d’entrée par erreur.
Le cas d’usage concret
Imaginons un compteur de tentatives de connexion, mis en cache uniquement après une première tentative échouée. Une fonction qui incrémenterait ce compteur avec un simple wp_cache_set() risquerait, en cas de logique mal ordonnée, de recréer une entrée à zéro puis de l’incrémenter, alors qu’elle aurait dû rester totalement absente tant qu’aucune tentative n’a eu lieu.
function incrementer_tentatives( $identifiant ) {
$tentatives = wp_cache_get( $identifiant, 'tentatives_connexion' );
if ( false === $tentatives ) {
return; // Aucune entrée : on ne crée rien ici.
}
$reussi = wp_cache_replace(
$identifiant,
$tentatives + 1,
'tentatives_connexion'
);
if ( ! $reussi ) {
// L'entrée a disparu entre la lecture et l'écriture
// (expiration, purge concurrente) : à traiter séparément.
}
}
Ce découpage rend explicite une situation qu’un simple wp_cache_set() masquerait silencieusement : l’entrée peut avoir disparu entre la lecture et l’écriture, notamment sur un cache distribué partagé par plusieurs processus.
La famille complète des fonctions d’écriture
| Fonction | Comportement si la clé existe déjà | Comportement si la clé est absente |
|---|---|---|
wp_cache_set() | Écrase la valeur | Crée l’entrée |
wp_cache_add() | Échoue, ne modifie rien | Crée l’entrée |
wp_cache_replace() | Écrase la valeur | Échoue, ne crée rien |
Ces trois fonctions couvrent chacune un cas d’intention différent. Choisir la bonne dès l’écriture d’une fonction de cache évite de devoir ajouter, plus tard, un test manuel pour reproduire un comportement que l’API native propose déjà.
Un piège de lecture rapide
- Le nom
wp_cache_replace()peut laisser croire, à tort, qu’elle crée l’entrée si elle est absente — c’est exactement l’inverse de son comportement réel. - Sur un backend de cache persistant (Redis, Memcached), la latence réseau rend les situations de concurrence plus fréquentes qu’avec le cache mémoire par défaut d’une seule requête PHP.
- Le groupe de cache doit être identique entre l’écriture et la lecture ultérieure, sans quoi la clé apparaît absente même si elle a bien été enregistrée ailleurs.
Un repère de conception utile : si une fonction ne doit jamais créer d’entrée de cache par elle-même, seulement en mettre à jour une déjà existante,
wp_cache_replace()rend cette intention explicite dans le code, sans commentaire nécessaire pour l’expliquer.
En résumé
Choisir entre wp_cache_set(), wp_cache_add() et wp_cache_replace() revient à choisir explicitement ce qui doit se passer selon que la clé existe déjà ou non. Cette nuance, souvent ignorée au profit du seul wp_cache_set(), évite des créations d’entrées non désirées dans des scénarios où l’absence d’une clé porte une information à part entière.
