Présentation de CW : un observateur de cache pour Symfony

Publié le 15/05/2020 • Actualisé le 05/12/2020

Dans cet article, je vais vous présenter Cw qui est un acronyme pour "Cache Watcher", littéralement un "observateur de cache". Cw est un petit programme Go (Golang) qui observe vos fichiers Symfony et préchauffe votre cache quand c'est nécessaire afin de ne pas avoir à attendre quand vous rafraichissez votre navigateur. C'est parti ! 😎

» Publié dans "Une semaine Symfonique 698" (du 11 au 17 mai 2020).

Prérequis

J'assumerai que avez les compétences de base concernant Symfony et que vous savez comment fonctionnent les commandes relatives au cache.

Introduction

Sur ce blog, quand j'écris un nouvel article, je le fais à la fois en anglais et en français. De ce fait, j'ai toujours de nombreuses modifications à faire dans les fichiers de traduction. À chaque fois, le cache doit être rafraichit. Récemment, j'ai pas mal joué avec Webpack Encore qui fournit une commande d'observation très pratique : yarn run encore dev --watch. Dès que vous modifiez un fichier Js ou CSS, les assets de dev sont recompilées. Ce qui nous fait sauver un temps précieux. C'est pourquoi j'ai eu l'idée de faire la même chose pour le cache standard de l'application.

Une fois n'est pas coutume, soyons fainéants. J'ai déjà écrit une documentation sur le dépôt GitHub, ça m'a prit pas mal de temps, peut-être plus que d'écrire le programme lui même ! Donc, pourquoi faire le travail deux fois ? Nous pouvons dans un premier temps, récupérer le contenu du fichier markdown brut avec le client HTTP Symfony.

Puis dans un deuxième temps, le convertir en HTML grâce au filtre Twig markdown_to_html. Il est rendu disponible par les dépendances composer erusev/parsedown et twig/markdown-extra. Chaque fois que le fichier est modifié sur le dépôt, ce sera répercuté dans cet article.

Maintenant, voici la documentation telle qu'elle apparait sur GitHub, rendez-vous au paragraphe "conclusion" (si vous êtes toujours là !).

---

CacheWatcher

CacheWatcher est un petit programme Go qui observe vos fichiers Symfony et met à jour votre cache si besoin afin que vous n'ayez pas à attendre lors du rafraichissement du navigateur.

Son but est d'améliorer l'expérience Développeur avec Symfony (DX).

Comment ça marche ? 🤔

Le programme "observe" vos fichiers (.env, YAML, Twig, entités Doctrine) et dès qu'il détecte un changement, il appelle la commande Symfony cache:warmup pour rafraichir le cache. Il est important de comprendre que le programme ne va ni appeler ni créer des fichiers sur votre machine par lui-même.

Installation 🛠️

Vous pouvez compiler le programme manuellement (ça implique que vous ayez un environnement de travail Go fonctionnel) ou vous pouvez télécharger un exécutable. Ce programme a été développé avec go1.17.2.

Compilation du programme ⚙️

$ git clone git@github.com:strangebuzz/cache-watcher.git
$ cd cache-watcher
$ make build 

Cela va construire l'exécutable cw or cw.exe selon votre système d'exploitation.

Téléchargement de l'exécutable 🔽

Voici les exécutables des principaux systèmes d'exploitation :

Système d'exploitation	Plateforme	version	date	fichier	Contrôle d'intégrité SHA
darwin (macOS)	amd64	0.5.0	2020-12-05	cw (3.3mo)	80b4011567c71aef7a13e9bbdad9acacee124acb330222fa2b2abf172ce2879e
darwin (macOS M1)	arm64	0.5.1	2022-05-12	cw (2.8mo)	0ba1a666c15900601c0b55762ce839a60309cb81a302fdcb10c931f33a105e98
Linux	amd64	0.5.0	2020-12-05	cw (3.3mo)	7203e4facfd82f54501ff17b569055daf7856164ed71a66b3fbfbe8dd9633293
Windows	amd64	0.5.0	2020-12-05	cw.exe (3.4mo)	2278d95d28011cbd2b97aed08e5e73274f08d245092cab58ac7f9d5c772e6892

Une fois téléchargé, vous pouvez vérifier que le fichier n'est pas compromis. Comparez d'une part, le code de contrôle d'intégrité SHA en exécutant la commande suivante et d'autre part, la valeur affichée dans le tableau précédent :

$ shasum -a 256 ./cw 
b35078644ac3b3f025276a0c5fcd77b3d2c8fe9cd15d136df969772e6f513973  ./cw

Sur Linux et macOS, donnez le droit d'exécution au programme :

$ chmod +x ./cw

Si vous avez besoin d'un autre type d'exécutable, vous pouvez créer un ticket en mentionnant le système d'exploitation et plateforme dont vous avez besoin. Vous trouverez les valeurs possibles dans cet article.

Par commodité, ajoutez cw à votre path pour y accéder de n'importe où.

💡 L'exécutable est "assez" gros (plusieurs mo), car il embarque le run-time Go et n'a pas de dépendance externe.

Lancement ⚡

Maintenant que vous avez compilé ou téléchargé le programme, essayons-le. Si vous le lancez sans arguments, il affiche un message d'aide. Si vous êtes à la racine de votre application Symfony, vous pouvez commencer à observer vos fichiers avec la commande suivante :

$ cw .

Vous devriez avoir la sortie suivante :

——————————————————————————————————————————————————————————————————————
  CacheWatcher version v0.5.1 by COil - https://www.strangebuzz.com 🐝
——————————————————————————————————————————————————————————————————————
CacheWatcher watches your files (.env, YAML, Twig) and automatically refreshes your application cache.
——————————————————————————————————————————————————————————————————————
 > Project directory: /Users/coil/Sites/strangebuzz.com
 > Symfony console path: bin/console
 > Symfony env: Symfony 5.4.0 (env: dev, debug: true)
 > 400 file(s) watched in /Users/coil/Sites/strangebuzz.com in 12 millisecond(s).
 > CTRL+C to stop watching or run kill -9 7817.

Et voilà ! Si vous avez un projet Symfony 4 ou 5 avec la structure de répertoire Flex, c'est tout ce dont vous avez besoin.

Quand une modification est détectée sur votre fichier services.yaml par exemple, vous avez le retour suivant :

⬇ Update detected at 17:09:03 > refreshing cache...
  ✅  Done! in 2.43 second(s).

Maintenant, rafraichissez votre page. Elle devrait être rapide puisque le cache est déjà prêt : 🐰

Au lieu d'avoir une page "lente" : 🐌

💡 Vous pouvez aussi passer un chemin relatif ou absolu comme argument :

$ cw ../strangebuzz.com
$ cw /Users/coil/Sites/strangebuzz.com 

Je l'utilise dans le terminal inclus dans PHPStorm :

/‼️\ Attention, si vous fermez la fenêtre PHPStorm, le processus cw ne sera pas automatiquement arrêté. /‼️\

Arrêt ⛔

Vous pouvez soit utiliser CTRL+C ou arrêter le processus manuellement grâce au PID qui a été affiché dans le message d'accueil :

$ kill -9 28157

Configuration 🎛️

Comme nous l'avons vu précédemment, si votre projet a une structure Flex, les paramètres par défaut devraient être bons. Ces paramètres par défaut seront toujours adaptés à la dernière version mineure de Symfony, actuellement 5.4 :

Clé	Valeur par défaut	Description
console_path	bin/console	Chemin relatif vers la console Symfony
env	dev	Correspond au paramètre APP_ENV de l'application Symfony
debug	true	Correspond au paramètre APP_DEBUG de l'application Symfony (true ou false)
config_dir	config	Chemin relatif ou sont stockés les fichiers de configuration de l'application Symfony
translations_dir	translations	Chemin relatif ou sont stockés les fichiers de traductions de l'application Symfony
templates_dir	templates	Chemin relatif ou sont stockés les templates de l'application Symfony
entities_dir	src/Entity	Chemin relatif ou sont stockés les entités Doctrine
templates_extension	twig	Extension par défaut des templates
yaml_extension	yaml	Extension par défaut des fichiers YAML, on considère qu'elle est cohérente pour l'ensemble de l'application
sleep_time	30	Pause entre deux analyses du système de fichiers en millisecondes

Si vous n'utilisez pas Flex, vous pouvez mettre un fichier .cw.yaml à la racine de votre projet. Voici la configuration que j'utilise pour un de mes anciens projets Symfony 4.4 :

config_dir:       app/config
translations_dir: src/AppBundle/Resources/translations
templates_dir:    src/AppBundle/Resources/views
yaml_extension:   yml
sleep_time:       30

💡 Le temps de pause (sleep_time) est le paramètre en millisecondes entre deux analyses du système de fichiers. Plus petite est la valeur, plus rapide sera le rafraichissement du cache, mais plus haute sera l'utilisation du processeur. J'ai constaté que 30 ms était un bon compromis pour mon Mac Mini 2018 (i7 / 3,2 GHz / 16 go), mais vous voudrez surement trouver la valeur la plus adaptée à votre système (avec top ou htop).

À faire 📋

• [ ] Ajouter une CI avec les actions GitHub
• [ ] Ajouter une option pour afficher les fichiers surveillés
• [ ] Permettre d'avoir une liste blanche additionnelle de fichiers à observer
• [ ] Libre à vous de créer un ticket ➕.

Contribuer 🤝

Vous êtes la bienvenue. Mais n'oubliez pas que je veux garder ce programme aussi léger que possible avec un seul but en tête. Même si ce projet est très récent, les fonctionnalités principales sont déjà implémentées.

Truc marrant (ou pas) 😄

Quand je développais cw, j'ai beaucoup joué avec les fichiers de configuration. Une fois, j'ai modifié un fichier .env et il se trouve que quand j'ai rafraîchi la page, elle était rapide, genre 50ms. J'ai répété l'opération plusieurs fois, même résultat ! 🤔 Ça m'a pris quelques instants avant de comprendre qu'un processus cw tournait toujours en tâche de fond. C'est pourquoi je ne pouvais pas constater un chargement "lent" de ma page. Et voilà, j'avais ma preuve, ça fonctionne ! ™ 😊

Mérites ™

• Symfony ™ est une marque déposée de Symfony SAS.
• Logo par Claire Brunaud.
• Logo Golang original "Gopher" par Renee French.

Licence ™

Ce logiciel est publié sous la licence MIT.

Remerciements 👏

• Jonathan Scheiber pour ces nombreuses relectures de la documentation et des articles du blog.

Changelog 📒

V0.5.1

• Ajout de l'executable pour Mac M1

V0.5.0

• Ajout du support pour surveiller les entités Doctrine (utile pour API Platform)

V0.4.0

• Version initiale

---

Conclusion ¶

Quand j'ai écrit cet article, le fait d'utiliser Cw m'a donné une sensation de fluidité lors des aller-retours de mon IDE au navigateur. C'est certain que ça a bien amélioré mon expérience de développement 🙏. Est-ce que ce sera le cas pour vous ? J'espère que vous ferez un essai 😉.

Et voilà ! J'espère que vous avez aimé. Découvrez d'autres informations en rapport à cet article avec les liens ci-dessous. Comme toujours, retours, likes et retweets sont les bienvenus. (voir la boîte ci-dessous) À tantôt ! COil. 😊

  Lire la doc   Contribuer   Télécharger  Plus sur le web

  Travaillez avec moi !

---