# wp_cache_replace : mettre à jour une valeur en cache seulement si elle existe

> « Erreur : voulait mettre à jour un cache absent. » Ce genre de bug silencieux disparaît avec la bonne fonction, qui refuse justement de créer une entrée par erreur.

- Auteur : WordPress Développement
- Publié le : 2021-06-07
- Mis à jour le : 2021-06-07
- Catégorie : Astuces
- URL : https://www.wpmoderne.fr/tips/wp-cache-replace-mettre-a-jour-valeur-existante/

## L’essentiel

- Échoue proprement si la clé n'existe pas déjà dans le cache
- Évite de recréer par erreur une entrée qui aurait dû être absente
- Complète wp_cache_add et wp_cache_set dans la même famille de fonctions

« 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.

> L'essentiel à retenir : Échoue proprement si la clé n'existe pas déjà dans le cache ; Évite de recréer par erreur une entrée qui aurait dû être absente ; Complète wp_cache_add et wp_cache_set dans la même famille de fonctions

```
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.