Download the PHP package octo-php/symfony-bridge without Composer

octo-php/symfony-bridge

Core Symfony HttpKernel adapter pour la plateforme async PHP — exécute une application Symfony sur le runtime OpenSwoole via ServerBootstrap::run().

Installation

Compatibilité

Bootstrap minimal

Le bridge est un callable handler pur : aucune commande CLI custom n'est imposée. Pour une intégration automatique via bundle et recipe Flex, voir octo-php/symfony-bundle.

Variables d'environnement

Cycle de vie d'une requête

Séquence invariante pour chaque requête :

1. Extraire X-Request-Id depuis la requête OpenSwoole
2. Convertir OpenSwoole Request → HttpFoundation Request
3. Vérifier ResponseState.isSent() (skip si 408/503 déjà envoyé par le runtime)
4. HttpKernel::handle() → obtenir la Response Symfony
5. Convertir HttpFoundation Response → OpenSwoole Response (via ResponseFacade)
6. $kernel->terminate($request, $response) (collecte Profiler ici)
7. ResetManager::reset() (reset services + hooks custom)
8. Métriques + vérification kernel reboot

Métriques exposées

La RSS inclut la mémoire partagée entre processus et ne constitue pas une preuve formelle de leak. Utilisez conjointement la RSS et le delta mémoire entre requêtes pour diagnostiquer les leaks.

Streaming natif

Le bridge supporte nativement le streaming via ResponseFacade::write(), sans buffering intermédiaire.

StreamedResponse

Le callback est intercepté via ob_start() et chaque chunk est redirigé vers ResponseFacade::write(). Si le callback lève une exception, elle est loguée et la réponse est terminée avec le contenu déjà envoyé.

StreamedJsonResponse

StreamedJsonResponse (Symfony 6.3+) est supporté via le même mécanisme de streaming natif.

SSE basique (Server-Sent Events)

Quand Content-Type: text/event-stream est détecté, le bridge désactive automatiquement la compression HTTP et le buffering (X-Accel-Buffering: no, Cache-Control: no-cache). Chaque chunk est flushé immédiatement.

Pour des helpers SSE avancés (formatage W3C, keep-alive, reconnection ID), voir octo-php/symfony-realtime.

Recommandations anti-leak

Dans un processus long-running, les services stateful fuient entre requêtes si ils ne sont pas réinitialisés.

Services à déclarer comme ResetInterface

Tout service qui accumule de l'état entre requêtes doit implémenter Symfony\Contracts\Service\ResetInterface :

• Caches en mémoire (ArrayAdapter, etc.)
• Repositories avec cache interne
• Services avec compteurs ou buffers

Patterns à éviter

• Singletons statiques : les propriétés static persistent entre requêtes. Préférer l'injection de dépendances.
• Caches globaux : $_SESSION, variables globales, registres statiques.
• État dans les constructeurs : les services sont instanciés une seule fois. Ne pas stocker de données par requête dans les propriétés d'instance sans reset.

Configuration Doctrine recommandée

Enregistrer un DoctrineResetHook pour nettoyer l'EntityManager :

Avec le bundle, les services implémentant ResetHookInterface sont auto-taggés et injectés automatiquement dans le ResetManager.

Kernel reboot (fallback robuste)

Si le reset standard ne suffit pas (leaks dans des services non-resettables), activez le reboot périodique :

Le kernel est reconstruit (shutdown() + boot()) tous les N requêtes. Le worker n'est pas tué — seul le kernel et le container sont reconstruits.

Concurrence et async-safety

Le HttpKernel Symfony s'exécute dans la coroutine de requête OpenSwoole. Les I/O hookées (réseau, fichiers) yield automatiquement à l'event loop.

Doctrine / PDO

Utiliser via IoExecutor / BlockingPool si les hooks PDO ne sont pas validés. Configurer le pool de connexions pour le long-running :

Guzzle / HttpClient

Coroutine-safe si SWOOLE_HOOK_CURL est actif (vérifié au boot par le runtime pack). Aucune action requise.

Filesystem

Coroutine-safe via SWOOLE_HOOK_FILE. Aucune action requise.

Sessions

Ne pas utiliser les sessions fichier natives PHP en long-running (state leak entre requêtes). Utiliser un handler de session externe :

• Redis (RedisSessionHandler)
• Base de données (PdoSessionHandler)

Incompatibilités

Request::createFromGlobals()

Request::createFromGlobals() lit les superglobales PHP ($_SERVER, $_GET, $_POST, etc.) qui ne sont pas mises à jour par OpenSwoole entre les requêtes. Toute bibliothèque utilisant createFromGlobals() n'est pas supportée en mode long-running.

Utilisez toujours l'objet Request injecté par le bridge.

Superglobales PHP

Le bridge ne lit ni ne modifie les superglobales PHP. Toutes les données sont extraites exclusivement de l'objet OpenSwoole\Http\Request.

État global PHP

timezone, locale, mb_internal_encoding doivent être configurés une seule fois au boot du worker et ne doivent pas être modifiés par requête :

RequestIdProcessor (Monolog)

Le bridge fournit un RequestIdProcessor qui propage le request_id dans tous les logs Monolog.

Enregistrement manuel

Enregistrement automatique

Avec le bundle octo-php/symfony-bundle, le RequestIdProcessor est auto-enregistré comme processeur Monolog si Monolog est disponible.

ResetHookInterface custom

Pour enregistrer un hook de reset custom exécuté après le reset Symfony principal :

Chaque hook est exécuté dans un try/catch : un hook qui échoue ne bloque pas les suivants. L'erreur est loguée.

Avec le bundle, les services implémentant ResetHookInterface sont auto-taggés via le ResetHookCompilerPass.

Intégration Profiler / WebDebugToolbar

En mode dev (APP_DEBUG=true), le Profiler et la WebDebugToolbar Symfony fonctionnent normalement :

• Le WebDebugToolbarListener injecte la toolbar dans les réponses HTML avant la conversion vers OpenSwoole
• kernel->terminate() est appelé avant le reset, permettant au Profiler de collecter les données
• Les data collectors sont réinitialisés entre les requêtes via ResetInterface
• Les routes /_profiler et /_wdt sont servies correctement

Le Profiler est automatiquement désactivé en mode production (aucun overhead).

Gestion des erreurs

• Production : exception → HTTP 500 {"error":"Internal Server Error"} sans stacktrace
• Développement : exception → page d'erreur Symfony avec stacktrace complète

Aucune exception ne remonte au runtime pack. Toutes sont interceptées et converties en réponse HTTP.

Packages complémentaires

Licence

MIT