Référence de configuration

OxPHP se configure entièrement au moyen de variables d'environnement. Il n'y a aucun fichier de configuration à gérer, et chaque paramètre possède une valeur par défaut, si bien qu'un déploiement sans configuration fonctionne d'emblée.

Valeurs booléennes

Les variables marquées comme booléennes acceptent un ensemble canonique fixe, insensible à la casse et débarrassé des espaces superflus :

• vraies : on, true, 1, yes
• fausses : off, false, 0, no

Toute valeur non vide en dehors de cet ensemble — des fautes de frappe comme ture — échoue immédiatement au démarrage avec une erreur nommant la variable. On repère ainsi une mauvaise configuration avant l'arrivée du trafic, au lieu de basculer silencieusement un indicateur dans le mauvais sens.

Une variable non définie ou une affectation vide (FOO=) retombe sur la valeur par défaut documentée. Une valeur vide est traitée comme non définie à dessein : une substitution Docker Compose / Kubernetes du type FOO=${FOO} produit FOO= lorsque la variable de l'hôte est absente, et cela ne doit pas empêcher le serveur de démarrer.

Serveur

Workers PHP

Dimensionner l'ensemble en attente

Le nombre de requêtes qui peuvent utilement attendre découle de la vitesse à laquelle le pool les écoule. Avec W workers et un gestionnaire qui prend T millisecondes, le pool admet W / T requêtes par milliseconde, donc un budget de B millisecondes peut laisser entrer environ W × B / T requêtes en attente. Tout ce qui dépasse attend le budget entier et est refusé de toute façon, en détenant une connexion et un corps de requête en tampon pendant tout ce temps.

La valeur par défaut ne peut pas calculer cela — le débit de service n'est pas connu au démarrage — elle est donc délibérément généreuse. Cela convient aux gestionnaires rapides, où le pool résorbe un arriéré profond bien avant la fin du budget, et c'est beaucoup trop grand pour les lents : avec 8 workers, le budget par défaut de 1 s et un gestionnaire à 200 ms, seules 40 requêtes environ peuvent être admises à temps alors que la valeur par défaut en stationne jusqu'à 1024.

Le régler près de W × B / T transforme le surplus en un 529 immédiat plutôt qu'en un 529 une seconde plus tard. Raccourcir QUEUE_WAIT_TIMEOUT_MS obtient le même résultat par l'autre terme. Les deux s'échangent l'un contre l'autre, et sur un gestionnaire lent, le budget plus court est en général le meilleur levier, car il borne aussi le temps qu'un client attend le refus.

L'ensemble est borné une seconde fois, en octets. Chaque requête en attente garde son corps en mémoire aussi longtemps qu'elle attend, si bien qu'un plafond compté en requêtes laisse au trafic la mémoire qu'elles détiennent : les mêmes 1024 requêtes en attente ne coûtent rien sur des GET sans corps, et des gigaoctets sur des uploads. QUEUE_MAX_WAITING_BYTES borne cette somme directement — au-delà, une requête portant un corps est refusée aussitôt au lieu d'être stationnée, tandis que celles sans corps continuent d'attendre normalement. Une application riche en uploads qui doit absorber les rafales plutôt que les délester veut une valeur plus grande ; un conteneur à limite mémoire stricte en veut une plus petite. Les refus dus à l'un ou l'autre plafond sont comptés séparément dans oxphp_admission_refused_total (waiting_full pour le décompte, waiting_bytes pour la mémoire), si bien que la métrique nomme le levier à actionner.

Garder de la marge pour la boucle d'acceptation

Une requête détient sa connexion — et l'un des permis MAX_CONNECTIONS — du moment où elle arrive jusqu'à sa réponse, quoi qu'elle fasse entre-temps. Cela couvre trois populations distinctes, car une place dans la file est libérée dès qu'un worker prend la requête en charge, avant que le script ne s'exécute :

• en cours d'exécution dans un worker : au moins PHP_WORKERS, et davantage en mode worker, où un thread multiplexe des fibers ;
• en file, jusqu'à QUEUE_CAPACITY ;
• stationnées à l'admission, jusqu'à QUEUE_MAX_WAITING.

Seule la troisième a un plafond dérivé de MAX_CONNECTIONS. Gardez PHP_WORKERS + QUEUE_CAPACITY + QUEUE_MAX_WAITING en dessous de MAX_CONNECTIONS. Au-delà, le mode de défaillance change pour le pire : la boucle d'acceptation prend un permis de connexion avant de commencer à servir une connexion, si bien qu'une fois que le chemin PHP les détient tous, elle se met en pause, et un client qui arrive alors n'obtient aucune réponse au lieu d'un 529 — ce qu'un répartiteur de charge ne peut pas distinguer d'une instance morte, tandis que la sonde de santé sur INTERNAL_ADDR reste au vert parce qu'elle ne passe par aucune des deux limites.

Le serveur le vérifie au démarrage et avertit quand la somme atteint le budget, en nommant chaque valeur ; oxphp config --check rapporte la même chose, sans changer son verdict ni son code de sortie. Considérez la disparition de l'avertissement comme nécessaire plutôt que suffisante : les connexions keep-alive inactives, les requêtes de fichiers statiques et les poignées de main en cours détiennent elles aussi des permis, et aucune ne peut être comptée au démarrage.

Abaisser MAX_CONNECTIONS est la manière habituelle de déclencher l'avertissement, car la valeur par défaut de QUEUE_CAPACITY est dimensionnée d'après le nombre de workers et ne le suit pas vers le bas — 7 workers et MAX_CONNECTIONS=1000 donnent 7 + 896 + 500 face à un budget de 1000. Notez quel levier actionner : relever MAX_CONNECTIONS seul ne le fait pas disparaître tant que QUEUE_MAX_WAITING reste à sa valeur par défaut, car cette valeur vaut la moitié de MAX_CONNECTIONS et monte avec lui — à 7 workers, la somme se stabilise à 1799 et la condition ne se dissipe qu'à partir de MAX_CONNECTIONS=1800. Abaissez QUEUE_CAPACITY, ou définissez QUEUE_MAX_WAITING explicitement puis relevez le budget.

Pour un pool dynamique (MIN:MAX), le terme en cours d'exécution est le minimum, le même nombre qui dimensionne les valeurs par défaut de la file, si bien qu'un pool monté à son maximum détient plus que ce que la somme annonce.

La comparaison compte des connexions alors que le budget se dépense en requêtes, si bien qu'un déploiement à dominante HTTP/2 peut légitimement se situer au-dessus : une connexion transporte jusqu'à H2_MAX_CONCURRENT_STREAMS requêtes, le même arriéré est donc détenu par une fraction des connexions. L'avertissement y est attendu. Un grand pool avec le budget d'origine l'atteint aussi — un pool auto-dimensionné de 39 workers donne 39 + 4992 + 4992 face à 10 000 — et celui-là mérite d'être traité plutôt qu'ignoré.

Workers statiques ou dynamiques

Définissez PHP_WORKERS sur un seul nombre pour un pool fixe :

Définissez PHP_WORKERS sur MIN:MAX pour une mise à l'échelle automatique :

En mode dynamique, OxPHP augmente le nombre de workers lorsqu'ils sont tous occupés et le réduit lorsque des workers sont restés inactifs plus longtemps que PHP_WORKERS_IDLE_SECONDS.

Mode worker

Définissez WORKER_MODE_ENABLED=true et faites pointer ENTRY_FILE vers votre script d'amorçage de worker (par exemple ENTRY_FILE=worker.php ou ENTRY_FILE=../worker.php). Les processus PHP restent alors en vie d'une requête à l'autre, en gardant en mémoire l'état d'amorçage (autoloaders, connexions à la base de données). Les workers sont recyclés automatiquement lorsqu'ils dépassent WORKER_MAX_MEMORY_MIB, ou à la demande lorsque l'application appelle Worker::scheduleExit(). Le réglage WORKER_MAX_REQUESTS des versions antérieures est déprécié et ignoré — ne définissez ni l'un ni l'autre, ou migrez vers Worker::scheduleExit().

Déprécié : INDEX_FILE et WORKER_FILE

Les variables héritées INDEX_FILE et WORKER_FILE sont toujours analysées à des fins de rétrocompatibilité. Lorsqu'elles sont définies, elles émettent une ligne de journal WARN au démarrage et se traduisent dans le nouveau modèle :

Si l'ancienne et la nouvelle sont toutes deux définies, ENTRY_FILE / WORKER_MODE_ENABLED l'emportent. Migrez à votre convenance ; les formes dépréciées seront supprimées dans une version future.

SAPI / PHP

Délais d'expiration

Le temps d'exécution PHP est borné par la directive ini max_execution_time de PHP (et set_time_limit() à l'exécution), et non par une variable d'environnement OxPHP.

Limitation de débit

Sécurité

La valeur spéciale private se développe en tous les réseaux privés RFC-1918, l'adresse de bouclage (loopback) et les adresses link-local (IPv4 et IPv6) : 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8, 169.254.0.0/16, ::1/128, fc00::/7, fe80::/10.

Protection contre le clickjacking

Le clickjacking est une attaque où une page hostile intègre votre site dans une <iframe> invisible et pousse l'utilisateur à cliquer sur quelque chose qu'il ne voit pas : un bouton « oui, supprimer mon compte », un achat en un clic, une invite « autoriser » OAuth. La défense consiste à dire au navigateur qui, le cas échéant, a le droit d'encadrer vos pages. FRAME_OPTIONS contrôle cela.

Deux en-têtes gouvernent le framing — l'historique X-Frame-Options (compris par tous les navigateurs) et le moderne Content-Security-Policy: frame-ancestors (qui le supplante là où les deux sont présents) — OxPHP émet donc les deux, et la politique tient sur les navigateurs anciens comme récents. Une seule valeur de FRAME_OPTIONS correspond à une paire assortie :

Choisir une valeur. SAMEORIGIN est la valeur par défaut : elle bloque le framing inter-origines sur lequel le clickjacking repose réellement, tout en laissant vos propres pages s'intégrer les unes dans les autres — ce que beaucoup d'applications font légitimement (aperçus d'admin, widgets de tableau de bord, composants de paiement hébergés sur la même origine). Choisissez DENY quand rien sur votre site n'est jamais censé être encadré, pas même par lui-même, pour la posture la plus stricte. Choisissez off uniquement quand vous gérez le framing vous-même via une Content-Security-Policy complète que votre application définit — voir ci-dessous.

Encadrer depuis des origines externes. Aucune valeur de X-Frame-Options ne peut nommer une origine autorisée précise (ALLOW-FROM a été retiré du standard). Pour permettre à un tiers nommé d'encadrer vos pages, définissez FRAME_OPTIONS=off et faites émettre à votre application sa propre Content-Security-Policy avec une liste frame-ancestors explicite, par exemple header("Content-Security-Policy: frame-ancestors 'self' https://partner.example.com");.

Les en-têtes applicatifs l'emportent. Les en-têtes serveur sont des replis, appliqués uniquement quand la réponse ne porte pas déjà un tel en-tête : une application qui définit son propre X-Frame-Options ou sa propre Content-Security-Policy via header() en PHP les conserve intacts. Les deux en-têtes de framing sont traités comme une seule politique, si bien que le serveur ne contredit jamais l'application :

• Si votre application définit X-Frame-Options, OxPHP omet son repli frame-ancestors (une CSP serveur écraserait le choix de votre application dans les navigateurs modernes).
• Si votre application définit une Content-Security-Policy contenant une directive frame-ancestors, OxPHP omet son repli X-Frame-Options (un X-Frame-Options serveur plus strict sur-bloquerait dans les navigateurs anciens qui ignorent la CSP).

La même priorité s'applique à X-Content-Type-Options, qu'OxPHP définit à nosniff sur chaque réponse : une valeur définie par l'application est conservée telle quelle. Notez que nosniff est la seule valeur qui fasse quelque chose — une application qui la remplace par autre chose désactive silencieusement la protection contre le MIME-sniffing.

TLS

HTTP/2

Fichiers statiques

Journalisation

Observabilité

OpenTelemetry

APM

Lorsque l'APM est activé, OxPHP intercepte automatiquement 34 fonctions PHP internes (PDO, mysqli, cURL, Redis, Memcached, E/S sur fichiers) pour créer des spans enfants. Les fonctions PHP oxphp_apm_*() sont enregistrées que l'APM soit activé ou non — lorsqu'il est désactivé, ce sont des no-ops sans effet.

Workers asynchrones

Le pool de workers asynchrones traite les tâches d'arrière-plan de type « fire-and-forget » envoyées depuis PHP. Il est distinct du pool de workers PHP et n'est pas nécessaire au traitement standard des requêtes.

Une valeur mal formée dans l'une de ces trois variables (par exemple ASYNC_WORKERS=8x) constitue une erreur de démarrage — retomber sur une valeur par défaut désactiverait ou mal configurerait silencieusement le pool. Une valeur exactement vide est traitée comme non définie.

Hooks d'exécution

Les hooks prennent effet dans les Fibers de requête du mode worker et dans les Fibers de tâches asynchrones. Hors d'une Fiber (contexte de requête traditionnel/framework/SPA, CLI), le comportement natif d'origine est préservé, y compris les erreurs de validation d'arguments. Avec les hooks sleep activés, du code tiers appelant sleep() cesse d'épingler le thread worker — aucune modification de code requise. Annuler une tâche asynchrone pendant un sleep intercepté la déroule avec OxPHP\Async\AsyncException, et un sleep() intercepté renvoie toujours 0 (la valeur de retour d'interruption par signal de la fonction native ne survient pas).

Ce que couvre le hook streams

Ce que le hook streams rend coopératif, c'est une lecture bloquante sur un flux socket PHP et une attente dans stream_select(). Avant de compter dessus, vérifiez que votre client attend de l'une de ces deux manières. Plusieurs clients courants ne le font pas, et pour eux rien ne change :

• ext/curl. curl_exec() et curl_multi_* parlent aux sockets eux-mêmes, sous les flux PHP, si bien que le hook ne les voit jamais. Cela couvre tous les clients HTTP bâtis sur curl — Guzzle avec son handler par défaut en fait partie. Un client curl peut être pointé vers le handler à wrappers de flux, qui, lui, passe par les flux PHP.
• socket_select(). C'est ext/sockets, une API différente sur des descripteurs bruts, et elle n'est pas interceptée. stream_select() l'est. Il en va de même pour l'attente dans stream_socket_accept(), qui n'est pas interceptée non plus.
• Les flux issus de socket_export_stream(). Ils portent une table d'opérations différente, privée à PHP, qui ne peut pas être modifiée depuis une extension.
• Les flux unix://, udp:// et udg://. Même raison : leurs tables d'opérations sont privées à PHP.
• ssl:// et tls:// une fois le chiffrement actif. Avant que stream_socket_enable_crypto() ne réussisse, les lectures d'un flux SSL sont déléguées à la lecture du socket en clair et suspendent donc bien ; à partir de la poignée de main, elles ne suspendent plus.
• L'établissement de connexion et la résolution DNS. Un client qui garde sa connexion ouverte en bénéficie à chaque requête ; l'établissement de la connexion, non.
• MySQL atteint via localhost. Le client MySQL lit localhost comme « utiliser le socket unix », qui n'est pas un flux tcp:// — écrivez plutôt 127.0.0.1 dans le DSN. Cela vaut pour PDO_MySQL comme pour mysqli, et c'est facile à manquer parce que tout continue de fonctionner, simplement sans le bénéfice.
• Les écritures. Seules les lectures attendent. La disponibilité en lecture reste acquise tant qu'une Fiber possède le descripteur et que rien d'autre ne le vide, alors que la place dans le tampon d'envoi est accordée et retirée par le pair : une Fiber réveillée sur la disponibilité en écriture peut trouver la fenêtre refermée au moment où l'écriture s'exécute, après quoi PHP bloque de toute façon le thread pour son délai complet. Une écriture qui remplit le tampon du socket se comporte donc exactement comme sans le hook. En pratique cela coûte peu : c'est attendre une réponse qui prend du temps, pas remettre une requête au noyau. (Les écritures sont tout de même examinées, pour une seule chose : savoir quel échange de quelle Fiber la connexion transporte en ce moment — voir la note sur les connexions partagées plus bas. Sur une connexion qu'aucune autre Fiber n'utilise, c'est-à-dire toutes les connexions dans le cas ordinaire, l'écriture suit le chemin natif intact.)

Dans ce périmètre, le hook conserve le contrat natif : les délais de socket (stream_set_timeout(), default_socket_timeout) s'appliquent inchangés, une lecture expirée rapporte toujours timed_out via stream_get_meta_data(), et l'identité du flux est intacte, si bien que socket_import_stream() et consorts continuent de fonctionner. Une limite sur le délai : l'échéance n'est examinée qu'une fois par tick de l'ordonnanceur, elle ne se déclenche donc pas avant le tick suivant — au mieux 100 µs en mode worker et 50 µs dans le pool asynchrone, et davantage sous charge, puisqu'un tick dure aussi longtemps que ce que le worker exécute. Le pool asynchrone fait des pauses plus longues que cela quand il ne se passe rien, mais jamais au-delà d'une échéance qu'il détient : une échéance de lecture ou d'écriture raccourcit la pause pour tomber sur elle-même, si bien qu'attendre plus longtemps ne retarde pas le délai. Avec default_socket_timeout à 60 secondes, ce n'est pas quelque chose que la plupart des déploiements peuvent observer.

stream_select() est intercepté en attendant sur les descripteurs que ses trois tableaux nomment, puis en remettant l'appel à PHP avec le délai mis à zéro, si bien que PHP décide encore de tout ce que vous pouvez observer : le nombre renvoyé, la réécriture des tableaux réduits aux flux prêts, les avertissements et les erreurs d'argument. L'attente est sautée — et l'appel s'exécute exactement comme sans le hook — dès que les tableaux contiennent quelque chose que le hook ne remplacera pas : un flux en lecture avec des données déjà en tampon (auquel stream_select() répond depuis le tampon, sans regarder un descripteur), un flux sans descripteur du tout, un élément qui n'est pas un flux vivant (un flux fermé laissé dans le tableau, par exemple — PHP y répond par une erreur, pas par une attente), un descripteur dont le noyau ne surveillera jamais la disponibilité (un fichier ordinaire est le cas usuel, et il compte comme prêt dès qu'on le demande), ou un descripteur égal ou supérieur à FD_SETSIZE, que le select() de PHP refuse d'emblée. Ce dernier cas est un vrai plafond plutôt qu'une formalité : un worker occupé peut détenir plus de 1024 descripteurs ouverts, et un stream_select() qui en nomme un échoue de la même façon avec ou sans le hook.

Connexions partagées entre Fibers concurrentes

Une connexion partagée entre Fibers concurrentes est sûre pour les clients qu'OxPHP protège, et n'y gagne rien. C'est la forme normale d'une application en mode worker plutôt qu'un cas limite : WordPress, Laravel et Symfony ouvrent leurs clients de base de données et de cache une fois à l'amorçage du worker et confient les mêmes à chaque requête, et à moins de réécrire leur couche d'accès aux données, on ne peut pas leur demander une connexion par Fiber.

Un protocole client est une suite d'échanges — écrire une commande, lire la réponse — sans que rien sur la connexion ne marque où l'un se termine. Une Fiber stationnée sur une lecture est stationnée au milieu d'un échange, et la commande d'une seconde Fiber qui y atterrit casse le protocole. Les deux clients échouent différemment sur ce point, et aucun ne le fait bien : mysqlnd suit l'état de sa connexion et refuse la commande avant d'envoyer quoi que ce soit, tandis que phpredis n'a pas un tel contrôle et les deux Fibers lisent les réponses l'une de l'autre — les données d'une requête renvoyées à une autre sans qu'aucune erreur soit levée.

Une Fiber revendique donc une connexion avant de s'en servir, aux deux niveaux où cela doit se faire : les opérations de socket, qui gardent les octets en ordre, et les points d'entrée client de PDO et mysqli, puisque le refus de mysqlnd survient avant toute E/S et que rien au niveau du socket ne peut être atteint à temps pour l'empêcher. Une autre Fiber qui atteint la même connexion attend qu'elle soit rendue au niveau client, où rien d'autre que l'identité de la connexion n'est détenu ; au niveau du socket, elle n'attend pas mais est refusée, comme l'est un délai de socket, parce qu'une Fiber suspendue dans une opération sur le flux de quelqu'un d'autre détiendrait un pointeur que son propriétaire peut libérer. phpredis est protégé au niveau client aussi, méthode par méthode, exactement pour cette raison. Ce que le niveau client revendique est la connexion elle-même et non l'objet PHP qui la détient, si bien qu'une connexion persistante atteinte via plusieurs objets PDO compte pour une seule, et qu'une connexion ouverte avec PDO::connect() — qui renvoie la sous-classe propre au pilote plutôt qu'un PDO — est couverte comme n'importe quelle autre.

Lisez donc le gain du hook comme appartenant aux connexions qu'une Fiber ouvre pour elle-même : une tâche asynchrone faisant ses propres appels HTTP ou base de données, une requête ouvrant son propre client. Ce qu'une connexion partagée obtient, c'est le thread worker rendu pendant qu'elle attend, pour que d'autres requêtes exécutent le travail qui n'est pas sur cette connexion ; ses propres échanges s'exécutent l'un après l'autre, exactement comme avec le hook désactivé. Quatre limites méritent d'être connues :

1. Une Fiber qui a interrogé une fois garde la connexion jusqu'à la fin de sa requête, parce que la fin de la requête est le premier moment certainement postérieur à la fin d'un échange. Elle la garde aussi pendant qu'elle est stationnée sur autre chose, si bien qu'une requête qui a interrogé puis attend un travail à elle qui a besoin de la même connexion s'attend elle-même ; les deux se séparent sur la borne ci-dessous au lieu d'avancer.
2. L'attente est toujours bornée : par le plus petit de max_execution_time et default_socket_timeout. Ne définissez ni l'un ni l'autre et cette borne est de 30 secondes, puisqu'une SAPI serveur prend les valeurs par défaut du moteur — 30 pour le premier et 60 pour le second ; elle vaut les 60 de default_socket_timeout uniquement là où max_execution_time est à 0. max_execution_time est lu tel que la requête l'a en ce moment, puisque set_time_limit() est la manière dont une requête déclare combien de temps elle peut s'exécuter ; default_socket_timeout est lu tel qu'au démarrage du processus, parce que c'est l'échéance par défaut d'une opération de socket, et une requête qui le resserre pour un appel à elle — chose courante pour une bibliothèque, et qu'elle laisse souvent derrière elle — ne doit pas raccourcir cette borne pour les requêtes qui la suivent sur le même worker. Passé la borne, l'appel retombe sur le comportement non protégé et en donne la raison dans le log du serveur : pour PDO et mysqli, il est remis au client, dont le propre refus d'une commande émise au milieu d'un échange est l'erreur que l'application gère déjà, tandis que pour phpredis, qui n'a pas un tel refus et lirait à la place la réponse de quelqu'un d'autre, il lève une RedisException et n'envoie rien. Un conflit au niveau du socket n'a pas de borne propre parce qu'il n'attend jamais : l'opération échoue aussitôt comme le fait un délai expiré, si bien que stream_get_meta_data() rapporte timed_out. Deux Fibers détenant chacune ce que l'autre attend se séparent donc sur cette borne au lieu de s'attendre l'une l'autre pour de bon.
3. Certains cas sont délibérément laissés sans couverture. Un objet statement ou résultat conservé d'une requête à l'autre, qu'aucun appel revendiqué ne précède : PDOStatement::execute() sur un statement préparé dans une requête antérieure se comporte comme sans revendication du tout. Construire un second handle sur une connexion persistante pendant qu'une autre Fiber y est au milieu d'un échange : PDO vérifie qu'une connexion du pool est vivante avant de la remettre, cette vérification échoue au milieu d'un échange, et PDO répond en abandonnant la connexion. Un protocole écrit à la main sur un socket brut — écrire une commande, se suspendre sur autre chose, lire la réponse plus tard — puisque le niveau socket ne refuse que pendant que le détenteur est stationné sur la réponse elle-même, et qu'entre ces deux points une autre Fiber s'empare de la connexion ; les trois clients ci-dessus sont couverts ici par leur revendication au niveau client, dont un protocole écrit à la main n'a pas d'équivalent. Et tout ce qui atteint une connexion complètement hors d'une Fiber, comme un destructeur exécuté par le collecteur de cycles du moteur entre les requêtes, qu'aucune revendication ne peut voir.
4. Fermer une connexion partagée pendant qu'une autre requête est stationnée à la lire met fin à cette requête, avec un 500 et une ligne de log nommant ce qui s'est passé. La revendication tient deux échanges à l'écart l'un de l'autre ; elle ne peut pas garder une connexion en vie, et la réponse de la requête stationnée se trouve sur une connexion qui n'existe plus — la réponse honnête est donc d'y mettre fin plutôt que de rendre ce que la mémoire libérée contient désormais. Les appels capables de cela dépendent du client, et un seul d'entre eux attend : mysqli::close() et mysqli_close() sont des appels revendiqués, ils attendent donc le détenteur et ferment une fois cette attente épuisée, tandis que Redis::close() est revendiqué aussi mais lève une RedisException au lieu de fermer. Tout le reste ferme aussitôt — fclose() sur un flux brut, et, surtout, PDO, qui n'a pas de méthode close() du tout : une connexion est libérée en abandonnant la dernière référence au handle (unset($pdo), le réassigner, ou le laisser sortir de portée), et ce chemin s'exécute dans le démontage d'objets du moteur lui-même, où aucune revendication n'est consultée. L'assistant de reconnexion qui réassigne un handle PDO partagé met donc fin aux requêtes stationnées sur l'ancienne connexion, sans l'attente bornée qu'obtient son équivalent mysqli. La requête est prévenue dès que la fermeture a lieu plutôt qu'à sa propre échéance de lecture, qui pour mysqlnd serait mysqlnd.net_read_timeout — un jour entier par défaut. Les applications qui ferment une connexion partagée pour forcer une reconnexion (le $wpdb->check_connection() de WordPress est le cas usuel) doivent s'attendre à ce que les requêtes qui y sont stationnées à ce moment-là échouent plutôt qu'elles ne renvoient de mauvaises données.

Une dernière limite : faire tourner le hook sous un ordonnanceur de Fibers en espace utilisateur (AMPHP, Revolt) retombe sur des E/S bloquantes. Une Fiber démarrée par un tel ordonnanceur s'exécute sur son propre contexte, que l'ordonnanceur d'OxPHP ne peut pas reprendre, si bien que le hook le détecte et prend le chemin natif plutôt que de corrompre l'un ou l'autre ordonnanceur. Il s'agit là d'une Fiber qu'un ordonnanceur en espace utilisateur démarre à l'intérieur d'une requête. La Fiber propre de la requête est pilotée par OxPHP, et en mode worker c'est une vraie Fiber — Fiber::getCurrent() dans une requête la renvoie — si bien que les bibliothèques qui n'ont besoin que de distinguer les requêtes concurrentes fonctionnent sans aucun repli. C'est le même fait qui explique pourquoi Revolt refuse d'exécuter sa boucle d'événements depuis l'intérieur d'une requête en mode worker.

Activation et coût

1, true et all activent toutes les catégories, streams comprise. Un déploiement qui définit déjà RUNTIME_HOOKS=1 pour les hooks sleep se met donc à intercepter les sockets à la mise à niveau sans la moindre modification de sa part ; listez les catégories explicitement (RUNTIME_HOOKS=sleep) si ce n'est pas ce que vous voulez. Activer streams modifie aussi en mémoire, au démarrage, une entrée de la table d'opérations de flux de PHP ; la page est remise comme elle a été trouvée, mais sur une plateforme où sa protection d'origine ne peut pas être déterminée, elle reste inscriptible — une petite perte de durcissement, signalée dans le log du serveur.

Le coût, mesuré : environ 3–5 µs par aller-retour de socket sur un worker sans rien d'autre de stationné, environ 5–6 µs avec 64 Fibers stationnées sur des descripteurs, et environ 7–11 µs avec 200. La disponibilité est résolue via un ensemble que le noyau conserve entre les attentes, si bien que ce que le chiffre suit est le nombre de descripteurs devenus prêts, pas le nombre en attente. Un worker inactif attend sur ces descripteurs au lieu de dormir un intervalle fixe et de remarquer la disponibilité à son tick suivant, ce qui compte énormément : dormir à l'aveugle coûtait environ 2 ms par aller-retour à la place.

Un stream_select() large porte un surcoût que le cas étroit n'a pas, parce que chaque descripteur nommé par un appel est enregistré avant l'attente et retiré après. Mesuré en retirant l'attente elle-même — chaque descripteur déjà lisible, si bien que l'appel revient aussitôt et qu'il ne reste que le surcoût — cela donne environ 6 µs contre 5 µs sans hook à un descripteur, 56 µs contre 9 µs à 64, et 130–150 µs contre 16–21 µs à 200 : environ 0,65 µs par descripteur.

Lisez cela comme un coût fixe par appel, pas comme un ralentissement du même travail. Un stream_select() qui attend réellement — ce pour quoi une boucle de select est écrite — l'éclipse : une milliseconde d'attente ramène même le chiffre à 200 descripteurs à environ un dixième de l'appel, et ce qu'il achète est le thread worker, que l'appel non intercepté détient pendant toute l'attente. Deux formes font exception, et pour elles la catégorie est mieux laissée désactivée : un appel sur de nombreux descripteurs qui n'attend presque jamais, parce qu'il n'y a pas de temps de thread à récupérer ; et une requête qui est la boucle d'événements, où le thread n'a de toute façon rien d'autre à exécuter. Les clients qui attendent sur une seule connexion — mysqlnd, phpredis, les wrappers de flux HTTP — se situent en haut du tableau, où le surcoût est de l'ordre de la microseconde.

RUNTIME_HOOKS et oxphp_sleep()

Le hook ne remplace pas la primitive maison — ils couvrent des cas différents :

• Choisissez oxphp_sleep() / oxphp_usleep() dans le code que vous écrivez. Ils suspendent la Fiber en mode worker inconditionnellement, sans indicateur d'environnement, et oxphp_sleep() accepte des secondes fractionnaires (oxphp_sleep(0.25)) — une précision que le sleep() natif (secondes entières) ne peut pas exprimer.
• Activez RUNTIME_HOOKS=sleep pour le code que vous ne pouvez pas modifier — un framework ou une bibliothèque tierce qui appelle directement les sleep()/usleep() natifs. Il est désactivé par défaut, ne s'applique qu'à l'intérieur d'une Fiber et conserve le contrat natif (un sleep() intercepté prend toujours un int et renvoie 0).

Compter sur RUNTIME_HOOKS pour vos propres gestionnaires attache leur coopérativité à un réglage de déploiement plutôt qu'au code ; préférez-y le oxphp_sleep() explicite.

État partagé

Primitives de concurrence intra-processus (OxPHP\Shared\Counter, Map, Channel, Mutex, Once, Pool, Atomic, Flag, Registry). Voir État partagé pour un tour d'horizon de l'API.

Profilage

Profileur par échantillonnage qui émet des traces xhprof / speedscope. Voir Profilage pour les formats de sortie et l'intégration avec les visualiseurs.

Exemples de configurations

Développement

Production (Framework)

Production (mode worker)

TLS

Inspecter la configuration active

Lorsque le serveur interne est en cours d'exécution, interrogez l'endpoint /config pour voir la configuration résolue :

Voir aussi

• Routage — modes de routage et comportement de ENTRY_FILE
• Contrôles de santé — endpoints du serveur interne
• Métriques — référence des métriques compatibles Prometheus
• Arrêt gracieux — comment DRAIN_TIMEOUT_SECONDS influe sur l'arrêt
• TLS — configuration TLS et exigences relatives aux certificats
• Limitation de débit — détails de la limitation de débit par IP
• Mode worker — architecture des workers PHP persistants
• Compression — détails de la compression Brotli
• Fichiers statiques — mise en cache et service de fichiers
• Traçage distribué & APM — export OTel, auto-instrumentation et SDK de traçage PHP