Magento 2 : cache:clean, cache:flush et setup:upgrade – Comprendre et optimiser leur usage

Différences entre cache:clean et cache:flush

La question revient souvent : quelle est la différence entre cache:clean et cache:flush sur Magento 2 ?

cache:clean nettoie uniquement les entrées de cache Magento devenues obsolètes ou invalides, sans toucher aux autres données stockées dans le backend de cache. Cela permet de rafraîchir la configuration ou le contenu sans perturber d’autres applications ou instances Magento utilisant le même système de cache
cache:flush vide totalement le stockage du cache : toutes les entrées, Magento ou non, sont supprimées. Cette commande est plus radicale et force Magento à tout reconstruire, ce qui peut ralentir temporairement le site jusqu’à ce que le cache soit regénéré

À retenir :

Utilisez cache:clean pour les mises à jour courantes (layouts, configs, etc.), c’est plus rapide et moins risqué. Utilisez
cache:flush uniquement en cas de problème persistant ou après une grosse mise à jour, car cela impacte toutes les données du cache, y compris celles d’autres applications si le backend est partagé
Il est possible de clean ou flush un ou plusieurs types de cache spécifiques pour cibler précisément l’opération et éviter de tout ralentir.
On peut créer des types de cache personnalisés pour des développements spécifiques.

Attention : le cache de configuration (config) est le plus long à se régénérer. Évitez de le purger trop souvent, que ce soit en local ou en production.

setup:upgrade – Ce que fait réellement la commande

La commande setup:upgrade est essentielle lors de l’évolution de votre projet Magento :

Elle relit tous les fichiers db_schema.xml pour mettre à jour le schéma de la base de données.
Elle exécute les setup patch data (scripts de migration de données, à ne pas confondre avec du contenu).
Elle lit les fichiers module.xml et met à jour le fichier app/etc/config.php (l’ordre des modules y est défini, ce qui peut impacter le comportement global).
Elle purge également le cache, les fichiers générés (generated) et les statics. Pour éviter de perdre du temps à regénérer ces fichiers, on peut utiliser l’option --keep-generated.

Bon à savoir :
La commande setup:db:status est censée indiquer si un setup:upgrade est nécessaire, mais en pratique, elle signale presque toujours qu’une mise à jour est requise, même si ce n’est pas le cas.

Bonnes pratiques de développement et de déploiement

En développement :

Modification d’un layout : flush uniquement le cache layout (ou désactivez-le en local, comme tous les autres caches sauf le cache config).
Modification/ajout d’un di.xml : flush le cache config (inévitablement long).
Modification d’un fichier LESS : clean les statics et le dossier var/view_preprocessed.
Création d’un controller : flush le cache (Magento stocke des métadonnées nécessaires au fonctionnement des controllers).
Modification d’un controller (constructeur) : clean uniquement le dossier generated.
Modification d’un block PHP ou d’un template : rien à faire si le full page cache est désactivé (ce qui est recommandé en dev).
Modification du schéma BDD ou ajout d’un patch data : lancez un setup:upgrade avec --keep-generated pour gagner du temps.

En production :

Après déploiement : flush du cache.
Pendant le déploiement : exécutez setup:upgrade (souvent avec --keep-generated car les statics sont générés en CI).
En cas de souci : une purge du Full Page Cache (FPC) suffit souvent. On évite toujours une purge globale du cache en production pour ne pas impacter les performances du site.

Flush, clean ou Upgrade ?

Bien comprendre et utiliser à bon escient cache:clean, cache:flush et setup:upgrade permet de gagner un temps précieux en développement et d’éviter des ralentissements inutiles en production. Adaptez vos commandes à chaque situation pour optimiser votre workflow Magento 2.