docs: Add warning on stateful services and shared memory model

docs/fr/worker.md

@@ -3,6 +3,37 @@
 Démarrez votre application une fois et gardez-la en mémoire.
 FrankenPHP traitera les requêtes entrantes en quelques millisecondes.
 
+## Avertissement sur la conception Stateful
+
+Contrairement au modèle PHP-FPM traditionnel, l'application reste **chargée en mémoire** entre les requêtes. Par conséquent, tout état stocké dans vos services (propriétés d'objet, singletons, etc.) sera conservé et partagé entre les requêtes successives traitées par le même worker. Cela peut entraîner des fuites de données et de mémoires ou des états incohérents si votre application n'est pas conçue pour cela.
+
+### Concevoir une application Stateless
+
+Le défi est de gérer le cycle de vie de vos objets, en particulier ceux qui sont des instances partagées par le conteneur de dépendances.
+
+Principes à respecter :
+
+- **Éviter l'état global :** Les variables globales et les propriétés statiques ne doivent pas être modifiées.
+- **Prudence avec les services :** Évitez de stocker des valeurs via des setters ou de modifier les propriétés publiques d'un service partagé, car ces changements affecteront la prochaine requête.
+- **Priorité aux nouveaux objets :** Tout ce qui est lié à la requête ou aux paramètres utilisateur doit être retourné comme un nouvel objet pour chaque requête.
+
+### Détection des problèmes (Analyse Statique)
+
+Des outils d'analyse statique peuvent vous aider à identifier les services potentiellement stateful. Ces outils vérifient notamment :
+
+- L'utilisation de propriétés publiques ou statiques mutables dans les services partagés.
+- L'usage de fonctions comme `die()` ou `exit()`.
+
+Un outil notable est **[denzyldick/phanalist](https://github.com/denzyldick/phanalist)**. Après installation, vous pouvez l'exécuter spécifiquement avec la règle E0012 (pour "Service compatibility with Shared Memory Model") pour obtenir une liste des endroits problématiques dans votre code.
+
+### L'interface de réinitialisation (Symfony)
+
+L'approche idéale est de concevoir vos services pour qu'ils soient naturellement `stateless`.
+
+Toutefois, dans les cas où il vous est difficile de rendre un service partagé complètement stateless (par exemple, un service avec un cache interne ou une configuration spécifique à la requête), vous pouvez utiliser l'interface `Symfony\Contracts\Service\ResetInterface`.
+
+Lorsqu'un service implémente cette interface, sa méthode reset() est automatiquement appelée par le conteneur de services à la fin de chaque requête. Cela permet de nettoyer spécifiquement l'état interne du service (par exemple, vider un cache interne, réinitialiser des propriétés...).
+
 ## Démarrage des scripts workers
 
 ### Docker

docs/worker.md

@@ -3,6 +3,37 @@
 Boot your application once and keep it in memory.
 FrankenPHP will handle incoming requests in a few milliseconds.
 
+## Designing for Stateful Applications
+
+Unlike the traditional PHP-FPM model, the application remains **loaded in memory** between requests. Consequently, any state stored within your services (object properties, singletons, etc.) will be retained and shared between successive requests handled by the same worker. This can lead to data and memory leaks or inconsistent states if your application is not designed for this.
+
+### Designing a Stateless Application
+
+The challenge is managing the lifecycle of your objects, especially those that are shared instances by the dependency container.
+
+**Key Principles to Follow:**
+
+- **Avoid Global State:** Global variables and static properties must not be modified.
+- **Caution with Services:** Avoid storing values via setters or modifying public properties of a shared service, as these changes will affect the next request.
+- **Prioritize New Objects:** Anything tied to the request or user parameters must be returned as a new object for each request.
+
+### Issue Detection (Static Analysis)
+
+Static analysis tools can help you identify potentially stateful services. These tools primarily check for:
+
+- The use of mutable public or static properties in shared services.
+- The use of functions like `die()` or `exit()`.
+
+A notable tool is **[denzyldick/phanalist](https://github.com/denzyldick/phanalist)**. After installation, you can run it specifically with rule E0012 (for "Service compatibility with Shared Memory Model") to get a list of problematic areas in your code.
+
+### The Reset Interface (Symfony)
+
+The ideal approach is to design your services to be naturally **`stateless`**.
+
+However, in cases where it is difficult to make a shared service completely stateless (e.g., a service with an internal cache or request-specific configuration), you can use the **`Symfony\Contracts\Service\ResetInterface`**.
+
+When a service implements this interface, its `reset()` method is automatically called by the service container at the end of each request. This allows you to specifically clean up the service's internal state (e.g., emptying an internal cache, resetting properties...).
+
 ## Starting Worker Scripts
 
 ### Docker