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

Variable	Valeur par défaut	Description
`LISTEN_ADDR`	`0.0.0.0:80`	Adresse et port du serveur HTTP principal
`DOCUMENT_ROOT`	`/var/www/html/public`	Répertoire racine pour servir les fichiers et les scripts PHP
`ENTRY_FILE`	(non défini)	Script d'entrée canonique unique. Non défini = mappage direct des fichiers. `*.php` = contrôleur frontal. Non-`.php` = repli statique (SPA). Avec `WORKER_MODE_ENABLED=true` = script d'amorçage du worker. Résolu par rapport à `DOCUMENT_ROOT` (chemins relatifs et `..` autorisés ; chemins absolus utilisés tels quels). Voir Routage
`WORKER_MODE_ENABLED`	`false`	Active le mode worker persistant. Nécessite que `ENTRY_FILE` pointe vers un script `.php`. Booléen — voir Valeurs booléennes
`MAX_CONNECTIONS`	`10000`	Nombre maximal de connexions TCP simultanées
`TOKIO_WORKERS`	CPU / 2 (min. 1)	Threads d'E/S asynchrones. `1` = mono-thread, `N > 1` = nombre de threads fixe, non défini = automatique (CPU / 2, min. 1)

Workers PHP

Variable	Valeur par défaut	Description
`EXECUTOR`	`sapi`	Backend d'exécution PHP. `sapi` pour l'exécution PHP, `stub` pour le benchmarking sans PHP
`PHP_WORKERS`	CPU / 2 (min. 1)	Taille du pool de workers. `N` = pool fixe, `MIN:MAX` = mise à l'échelle dynamique, `0` = automatique
`PHP_WORKERS_IDLE_SECONDS`	`30`	Nombre de secondes pendant lesquelles un worker dynamique reste inactif avant d'être retiré (mode dynamique uniquement)
`QUEUE_CAPACITY`	Workers initiaux × 128	Nombre maximal de requêtes en attente dans la file PHP. Renvoie 529 lorsqu'elle est pleine. Pour les pools dynamiques (`MIN:MAX`), le nombre de workers initiaux = le minimum

Workers statiques ou dynamiques

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

bash

PHP_WORKERS=8      # Fixed 8 workers
PHP_WORKERS=0      # Auto-detect: CPU / 2 (min 1)

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

bash

PHP_WORKERS=2:16   # Scale between 2 and 16 workers
PHP_WORKERS=4:0    # 4 minimum, auto-detect maximum (CPU × 2)
PHP_WORKERS=0:16   # auto-detect minimum (CPU / 4, min 1), 16 maximum

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

Variable	Valeur par défaut	Description
`WORKER_MAX_MEMORY_MIB`	`0`	Mémoire maximale en MiB par worker avant recyclage. `0` = illimité

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 :

Héritée	Équivalent actuel
`INDEX_FILE=index.php`	`ENTRY_FILE=index.php`
`INDEX_FILE=index.html`	`ENTRY_FILE=index.html`
`WORKER_FILE=/path/worker.php`	`WORKER_MODE_ENABLED=true ENTRY_FILE=/path/worker.php`

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

Variable	Valeur par défaut	Description
`SUPERGLOBALS_ENABLED`	`true`	Renseigne les superglobales PHP (`$_GET`, `$_POST`, `$_COOKIE`, `$_FILES`, `$_SERVER`, `php://input`) avant l'exécution du script. Définissez sur une valeur fausse pour ignorer ce remplissage — les données de la requête ne sont alors accessibles que via l'API objet (`oxphp_http_request()`). Utile pour les applications qui consomment directement l'API objet et veulent éviter le coût de construction des superglobales à chaque requête

Délais d'expiration

Variable	Valeur par défaut	Description
`HEADER_TIMEOUT_SECONDS`	`5`	Nombre maximal de secondes pour recevoir les en-têtes HTTP après la connexion (protection contre Slowloris)
`DRAIN_TIMEOUT_SECONDS`	`25`	Nombre maximal de secondes d'attente des connexions en cours lors d'un arrêt gracieux

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

Variable	Valeur par défaut	Description
`RATE_LIMIT`	`0` (désactivé)	Nombre maximal de requêtes par IP et par fenêtre de temps. `0` désactive la limitation de débit
`RATE_WINDOW_SECONDS`	`60`	Durée de la fenêtre de limitation de débit en secondes

Sécurité

Variable	Valeur par défaut	Description
`FRAME_OPTIONS`	`DENY`	Protection contre le clickjacking. `DENY` bloque tout affichage en cadre (framing), `SAMEORIGIN` autorise le framing de même origine, `off` le désactive (à utiliser lorsque vous gérez le framing via votre propre CSP). Définit à la fois `X-Frame-Options` et `Content-Security-Policy: frame-ancestors`. Les en-têtes de sécurité du serveur servent de repli : les valeurs définies par l'application (par exemple via `header()` en PHP) ont la priorité et ne sont jamais écrasées. La paire de framing est liée dans les deux sens — un `X-Frame-Options` défini par l'application supprime le `Content-Security-Policy: frame-ancestors` du serveur (CSP l'emporte sur `X-Frame-Options` dans les navigateurs modernes), et une CSP applicative contenant une directive `frame-ancestors` supprime le `X-Frame-Options` du serveur. Notez que cette priorité s'applique aussi à `X-Content-Type-Options` : une valeur définie par l'application est conservée telle quelle même si `nosniff` est sa seule valeur valide — une valeur invalide désactive la protection
`TRUSTED_PROXIES`	(non défini)	Réseaux de proxys inverses de confiance (CIDR séparés par des virgules ou `private`). Lorsqu'elle est définie, OxPHP extrait la véritable IP du client à partir des en-têtes `Forwarded` (RFC 7239) ou `X-Forwarded-For` en appliquant l'algorithme rightmost-non-trusted (le nœud non fiable le plus à droite). Traite également `X-Forwarded-Proto` et `X-Forwarded-Host` pour `$_SERVER['HTTPS']`, `REQUEST_SCHEME`, `SERVER_NAME` et `SERVER_PORT`. Non défini = fonctionnalité désactivée
`PHP_DENY_PATHS`	(non défini)	Motifs glob séparés par des virgules dont les fichiers `.php` ne doivent jamais s'exécuter via un URI direct (par exemple `/uploads/,/cache/,/admin/legacy.php`). Les motifs peuvent cibler des répertoires entiers ou des fichiers isolés. S'applique dans les modes de mappage direct — Traditionnel et SPA ; ignoré avec un avertissement au démarrage dans les modes Framework et Worker, qui n'exécutent jamais directement des fichiers `.php` arbitraires. Couvre aussi les scripts atteints via la résolution d'index de répertoire (`/uploads/` → `uploads/index.php`). Pour les URI `.php` directs, la correspondance a lieu avant toute E/S disque, si bien que les chemins refusés produisent la même réponse que le fichier existe ou non (pas d'oracle d'existence). L'ancien nom `PHP_DENY_DIRS` est accepté comme alias déprécié et émet un `WARN` au démarrage. Voir Liste de refus d'exécution PHP
`PHP_DENY_FALLBACK`	`404`	Ce qui est renvoyé en cas de correspondance avec `PHP_DENY_PATHS`. Soit un statut HTTP `400`–`599` (associé à `ERROR_PAGES_DIR` pour un HTML personnalisé), soit un chemin d'URI préfixé par `/` vers un script PHP de repli situé dans `DOCUMENT_ROOT`. Le script de repli reçoit `OXPHP_DENIED_PATH` et `OXPHP_DENIED_PATTERN` dans `$_SERVER`. Validé au démarrage : le script doit exister, se canonicaliser à l'intérieur de `DOCUMENT_ROOT`, et ne doit pas lui-même correspondre à `PHP_DENY_PATHS` (prévention des boucles)
`SYMLINK_ALLOW_PATHS`	(non défini)	Liste, séparée par des virgules, de chemins absolus sous lesquels les liens symboliques sont autorisés à sortir de `DOCUMENT_ROOT`. Chaque entrée doit déjà exister sur le disque ; les chemins relatifs et les chemins manquants interrompent le démarrage. Non défini = aucune sortie par lien symbolique autorisée. Voir Liste d'autorisation de liens symboliques

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.

TLS

Variable	Valeur par défaut	Description
`TLS_CERT`	(non défini)	Chemin vers le certificat TLS encodé en PEM. `TLS_CERT` et `TLS_KEY` doivent tous deux être définis pour activer TLS
`TLS_KEY`	(non défini)	Chemin vers la clé privée TLS encodée en PEM
`TLS_MIN_VERSION`	`1.2`	Version minimale acceptée du protocole TLS : `1.2` ou `1.3`. Validée au démarrage (et par `oxphp config --check`) même lorsque TLS n'est pas activé — toute autre valeur, y compris des octets non-UTF-8, constitue une erreur de démarrage fatale. Une valeur vide est traitée comme non définie

HTTP/2

Variable	Valeur par défaut	Description
`H2_MAX_CONCURRENT_STREAMS`	`PHP_WORKERS_MAX × 4` (min. 32)	Nombre maximal de flux ouverts simultanément par connexion HTTP/2
`H2_MAX_PENDING_RESET`	`20`	Nombre maximal de trames `RST_STREAM` en file d'attente avant fermeture d'une connexion (protection contre Rapid Reset)
`H2_MAX_HEADER_LIST_BYTES`	`65536`	Nombre maximal total d'octets d'en-tête décodés par requête
`H2_KEEPALIVE_INTERVAL_SECS`	`20`	Nombre de secondes entre les trames PING HTTP/2 ; `0` désactive
`H2_KEEPALIVE_TIMEOUT_SECS`	`10`	Nombre de secondes d'attente d'une réponse PING avant de fermer la connexion

Fichiers statiques

Variable	Valeur par défaut	Description
`STATIC_MAX_AGE`	`30d`	`Cache-Control: max-age` pour les fichiers statiques. Accepte : `30s`, `5m`, `2h`, `30d`, `1w`, `1y`, un nombre de secondes brut (`3600`), ou `off` pour désactiver l'en-tête. Remplace `STATIC_CACHE_TTL`, déprécié.
`STATIC_REVALIDATE`	`off`	Booléen — voir Valeurs booléennes. Définissez sur une valeur vraie pour activer la revalidation par mtime du cache de contenu en mémoire : la date de modification du fichier est revérifiée au plus une fois toutes les 3 secondes par fichier (pas par requête) et les entrées périmées sont évincées automatiquement, si bien que les changements deviennent visibles en moins de 3 secondes. Remplace `STATIC_CACHE`, déprécié (où `off` avait le sens inverse).
`COMPRESSION_LEVEL`	`4`	Qualité de compression Brotli (0–11). `0` désactive la compression

Journalisation

Variable	Valeur par défaut	Description
`LOG_LEVEL`	`info`	Verbosité des journaux : `trace`, `debug`, `info`, `warn`, `error`
`ACCESS_LOG`	(non défini)	Journal d'accès par requête : `all` = chaque requête, `error` = 4xx/5xx uniquement, non défini = désactivé

Note

ACCESS_LOG accepte all ou error. Laissez la variable non définie pour désactiver totalement la journalisation des accès.

Observabilité

Variable	Valeur par défaut	Description
`INTERNAL_ADDR`	(non défini)	Adresse du serveur interne (`/health`, `/metrics`, `/config`). Le serveur interne n'est pas démarré lorsque cette variable n'est pas définie. Une valeur ne comportant qu'un port (`:9090` ou `9090`) se lie à `127.0.0.1` ; liez explicitement `0.0.0.0:9090` pour l'exposer hors de l'hôte
`INTERNAL_ALLOW_IPS`	(non défini)	Liste d'autorisation CIDR/IP, séparée par des virgules, pour le serveur interne. Un pair extérieur à la liste reçoit `403` sur `/metrics`, `/config` et les chemins de plugins ; les sondes de santé (`/health`, `/healthz`, `/readyz`, `/startupz` et leurs formes longues) restent accessibles. Non défini/vide = tout est autorisé. Le bouclage (loopback) n'est pas implicite — listez `127.0.0.1/32` pour conserver l'accès depuis localhost. Une liste mal formée interrompt le démarrage
`ERROR_PAGES_DIR`	(non défini)	Répertoire contenant les pages d'erreur personnalisées nommées `{status}.html` (par exemple `404.html`, `503.html`)
`MAX_QUERY_BODY`	`524288`	Taille maximale du corps de requête, en octets, pour les endpoints de requête internes (512 KiB)
`TRACE_CONTEXT`	`false`	Booléen — voir Valeurs booléennes. Lorsque la valeur est vraie, active la propagation du W3C Trace Context : lit les en-têtes `traceparent`/`tracestate` et les transmet à PHP via `$_SERVER`

OpenTelemetry

Variable	Valeur par défaut	Description
`OTEL_ENABLED`	`false`	Active l'export de spans OpenTelemetry. Définit automatiquement `TRACE_CONTEXT=true`. Booléen — voir Valeurs booléennes
`OTEL_EXPORTER_OTLP_PROTOCOL`	`grpc`	Protocole d'export : `grpc` ou `http/protobuf`
`OTEL_EXPORTER_OTLP_ENDPOINT`	`http://localhost:4317` (gRPC) ou `http://localhost:4318` (HTTP)	Endpoint du collecteur OTLP
`OTEL_EXPORTER_OTLP_TIMEOUT`	`10000`	Délai d'expiration de l'export en millisecondes
`OTEL_EXPORTER_OTLP_HEADERS`	(non défini)	En-têtes d'authentification : `key=value,key2=value2`
`OTEL_SERVICE_NAME`	`oxphp`	Nom du service dans les spans exportés
`OTEL_SERVICE_VERSION`	(non défini)	Attribut de version du service
`OTEL_RESOURCE_ATTRIBUTES`	(non défini)	Attributs de ressource supplémentaires : `env=prod,region=us-east-1`
`OTEL_TRACES_SAMPLER`	`parentbased_traceidratio`	Stratégie d'échantillonnage : `always_on`, `always_off`, `traceidratio`, `parentbased_always_on`, `parentbased_always_off`, `parentbased_traceidratio`
`OTEL_TRACES_SAMPLER_ARG`	`1.0`	Taux d'échantillonnage (0.0–1.0) pour les échantillonneurs basés sur un ratio

Note

Les valeurs OTEL_TRACES_SAMPLER_ARG invalides ou hors plage sont ramenées à [0.0, 1.0] et journalisées au niveau warn. Les valeurs OTEL_TRACES_SAMPLER inconnues retombent sur parentbased_traceidratio et sont journalisées.

APM

Variable	Valeur par défaut	Description
`OTEL_APM_ENABLED`	`false`	Active l'APM : instrumentation automatique, capture des erreurs et SDK de traçage PHP. Nécessite `OTEL_ENABLED=true`. Booléen — voir Valeurs booléennes
`OTEL_APM_SLOW_QUERY_MS`	`100`	Seuil de requête lente en millisecondes. Les requêtes de base de données qui le dépassent reçoivent un attribut de span `oxphp.db.slow=true`
`OTEL_APM_DB_CAPTURE_PARAMS_ENABLED`	`false`	Enregistre les paramètres liés (bind) dans l'attribut de span `db.params`. À désactiver en production si les paramètres peuvent contenir des données sensibles. Booléen — voir Valeurs booléennes
`OTEL_APM_STACKTRACE_MAX_BYTES`	`8192`	Taille maximale, en octets, de l'attribut `exception.stacktrace`. Au-delà du plafond, la trace d'appels est tronquée par la fin avec un marqueur `…(truncated)`. `0` désactive la troncature
`OTEL_APM_MESSAGE_MAX_BYTES`	`4096`	Taille maximale, en octets, de l'attribut `exception.message` (la valeur par défaut correspond à la limite de valeur par attribut de New Relic). Au-delà du plafond, le message est tronqué par la fin avec un marqueur `…(truncated)`. `0` désactive la troncature

Lorsque l'APM est activé, OxPHP intercepte automatiquement 33 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

Variable	Valeur par défaut	Description
`ASYNC_WORKERS`	`0` (désactivé)	Nombre de threads de workers asynchrones dédiés. Lorsque la valeur est `0`, les fonctions asynchrones (`oxphp_async`, etc.) sont enregistrées mais lèvent `OxPHP\Async\AsyncException` à l'appel. Définissez une valeur positive pour activer l'exécution de tâches en arrière-plan
`ASYNC_QUEUE_CAPACITY`	`ASYNC_WORKERS × 64`	Nombre maximal de tâches en attente dans la file asynchrone. `0` = automatique (workers × 64)
`ASYNC_MAX_FIBERS`	`256`	Plafond, par worker, du nombre de Fibers de tâches asynchrones concurrentes. La limite globale du processus (en attente + en cours d'exécution) est `ASYNC_MAX_FIBERS × ASYNC_WORKERS` ; un envoi au-delà est rejeté immédiatement avec `OxPHP\Async\AsyncException`, si bien qu'une composition en fan-out ne peut pas provoquer d'interblocage

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.

É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.

Variable	Valeur par défaut	Description
`SHARED_ENABLED`	`true`	Booléen — voir Valeurs booléennes. Interrupteur principal de l'ensemble du sous-système `OxPHP\Shared\*`
`SHARED_MAX_ENTRIES`	`100000`	Plafond global sur l'ensemble des entrées Shared combinées. Une insertion au-delà échoue avec `CapacityException`
`SHARED_MAX_BYTES`	`1073741824` (1 GiB)	Plafond global sur la mémoire estimée pour l'ensemble des entrées Shared
`SHARED_SOFT_LIMIT_RATIO`	`0.7`	Commence à délester le travail de plus faible priorité lorsque l'utilisation franchit cette fraction de `SHARED_MAX_BYTES` / `SHARED_MAX_ENTRIES`
`SHARED_METRICS_ENABLED`	`true`	Booléen. Active/désactive l'exposition Prometheus `oxphp_shared_*`
`SHARED_INTROSPECTION_ENABLED`	`true`	Booléen. Active/désactive l'API d'introspection `/__ox_shared/*` sur le serveur interne
`SHARED_INTROSPECTION_PREVIEW_ENABLED`	`true`	Booléen. Active/désactive les aperçus de valeurs dans les réponses d'introspection (désactivez-les lorsque les aperçus pourraient divulguer des données sensibles)
`SHARED_CYCLE_DETECT_DEPTH`	`16`	Profondeur du parcours BFS lors de la vérification des cycles. À augmenter pour des graphes profonds légitimes
`SHARED_CYCLE_DETECT_EDGES`	`10000`	Nombre d'arêtes parcourues lors de la vérification des cycles. À augmenter pour des graphes denses légitimes
`SHARED_MAX_VALUE_SIZE`	`1048576` (1 MiB)	Plafond de taille par valeur. L'insertion d'une valeur plus grande échoue immédiatement
`SHARED_MAX_CHANNEL_BYTES`	`67108864` (64 MiB)	Plafond de charge utile totale par canal
`SHARED_POISON_STRICT`	`false`	Booléen. Lorsque la valeur est vraie, un panic à l'intérieur d'une closure Mutex/Once empoisonne la primitive de façon permanente au lieu d'une récupération au mieux
`SHARED_LOCK_DIAGNOSTICS`	`off`	Diagnostics de contention de verrous : `off`, `count` ou `trace`
`SHARED_LOCK_POLL_INTERVAL_MS`	`100`	Intervalle d'échantillonnage utilisé par l'échantillonneur de diagnostics de verrous
`SHARED_PREVIEW_STRING_LIMIT`	`256`	Troncature par chaîne dans les aperçus `/entry?id=…`
`SHARED_PREVIEW_ARRAY_LIMIT`	`20`	Nombre d'entrées échantillonnées dans les aperçus `/entry?id=…`

Profilage

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

Variable	Valeur par défaut	Description
`PROFILER_ENABLED`	`false`	Booléen — voir Valeurs booléennes. Interrupteur principal. Toutes les autres variables `PROFILER_*` sont tout de même analysées au démarrage, de sorte que les fautes de frappe apparaissent immédiatement
`PROFILER_SAMPLE_RATE`	`0.0`	Probabilité (0.0–1.0) qu'une requête soit échantillonnée. Les valeurs hors plage sont ramenées dans les bornes
`PROFILER_INTERNAL`	`false`	Booléen. Lorsque la valeur est vraie, les requêtes vers le serveur interne (`/health`, `/metrics`, endpoints de plugins) sont elles aussi éligibles à l'échantillonnage
`PROFILER_AUTH_TOKEN`	(non défini)	Jeton bearer facultatif. Lorsqu'il est défini, les fonctions PHP `oxphp_profiler_*` exigent que les requêtes portent ce jeton pour activer le profilage à la demande
`PROFILER_MAX_SPANS`	`50000`	Plafond de spans de profil par requête. Les profils dépassant ce plafond sont tronqués
`PROFILER_MAX_DEPTH`	`256`	Profondeur maximale de la pile d'appels capturée par échantillon. Plafonnée en dur à `65535`
`PROFILER_OUTPUT_DIR`	`/tmp/oxphp-profiles`	Répertoire des fichiers de profil sur disque
`PROFILER_OUTPUT_FORMATS`	`xhprof,speedscope`	Liste, séparée par des virgules, des formats de sortie à écrire sur disque
`PROFILER_DISK_MAX_PER_SEC`	`10`	Limite de débit sur les fichiers de profil écrits sur disque par seconde
`PROFILER_RETENTION_COUNT`	`100`	Nombre maximal de fichiers de profil conservés dans `PROFILER_OUTPUT_DIR`. Les fichiers plus anciens sont supprimés
`PROFILER_EXPORT_URL`	(non défini)	Endpoint distant vers lequel envoyer (POST) les profils. Lorsqu'il est défini, les écritures sur disque ont toujours lieu, sauf si `PROFILER_OUTPUT_FORMATS` est vide
`PROFILER_EXPORT_FORMAT`	`xhprof`	Format de transmission (wire) pour les envois vers `PROFILER_EXPORT_URL`
`PROFILER_EXPORT_AUTH_TOKEN`	(non défini)	Jeton bearer facultatif envoyé avec chaque requête d'export
`PROFILER_EXPORT_XHGUI`	(détection automatique)	Booléen. Force l'encapsulation de la charge utile d'export au format compatible XHGui. Non défini = détection automatique lorsque le chemin de `PROFILER_EXPORT_URL` se termine par `/run/import` (les indices d'hôte/de requête ne sont pas pris en compte)
`PROFILER_EXPORT_BUGGREGATOR`	(détection automatique)	Booléen. Force l'enveloppe Buggregator. Non défini = détection automatique lorsque le chemin de `PROFILER_EXPORT_URL` se termine par `/api/profiler/store`. L'enveloppe émet toujours du xhprof, si bien que `PROFILER_EXPORT_FORMAT` est ignoré dans ce cas (une valeur non-xhprof émet un avertissement, non fatal). Mutuellement exclusif avec `PROFILER_EXPORT_XHGUI` — activer les deux est une erreur de démarrage
`PROFILER_EXPORT_APP_NAME`	(non défini)	`app_name` Buggregator pour le regroupement par projet
`PROFILER_EXPORT_TAGS`	(non défini)	`tags` Buggregator sous la forme `key=value,key2=value2` ; un jeton mal formé, une clé vide ou une clé en double est une erreur de démarrage

Exemples de configurations

Développement

bash

LISTEN_ADDR=127.0.0.1:8080
DOCUMENT_ROOT=./public
LOG_LEVEL=debug
ACCESS_LOG=all
PHP_WORKERS=1
INTERNAL_ADDR=127.0.0.1:9090

Production (Framework)

bash

LISTEN_ADDR=0.0.0.0:80
DOCUMENT_ROOT=/var/www/html/public
ENTRY_FILE=index.php
PHP_WORKERS=8
QUEUE_CAPACITY=1024
LOG_LEVEL=warn
ACCESS_LOG=error
MAX_CONNECTIONS=10000
INTERNAL_ADDR=127.0.0.1:9090
RATE_LIMIT=100
RATE_WINDOW_SECONDS=60
TRUSTED_PROXIES=private
HEADER_TIMEOUT_SECONDS=5
DRAIN_TIMEOUT_SECONDS=25
COMPRESSION_LEVEL=4
STATIC_MAX_AGE=30d

Production (mode worker)

bash

LISTEN_ADDR=0.0.0.0:80
DOCUMENT_ROOT=/var/www/html/public
WORKER_MODE_ENABLED=true
ENTRY_FILE=../worker.php
PHP_WORKERS=8
WORKER_MAX_MEMORY_MIB=128
QUEUE_CAPACITY=1024
LOG_LEVEL=warn
ACCESS_LOG=error
INTERNAL_ADDR=127.0.0.1:9090

TLS

bash

LISTEN_ADDR=0.0.0.0:443
TLS_CERT=/etc/ssl/oxphp/cert.pem
TLS_KEY=/etc/ssl/oxphp/key.pem
DOCUMENT_ROOT=/var/www/html/public
ENTRY_FILE=index.php

Inspecter la configuration active

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

bash

curl -s http://localhost:9090/config | jq .

json

{
  "listen_addr": "0.0.0.0:80",
  "document_root": "/var/www/html/public",
  "entry_file": "/var/www/html/public/index.php",
  "log_level": "warn",
  "executor_type": "sapi",
  "php_workers": "8",
  "tokio_workers": 4,
  "queue_capacity": 1024,
  "max_connections": 10000,
  "drain_timeout_seconds": 30,
  "header_timeout_seconds": 5,
  "rate_limit": 100,
  "rate_window_seconds": 60,
  "tls_enabled": true,
  "compression_level": 4,
  "access_log": "all",
  "max_query_body": 524288,
  "worker_mode_enabled": false,
  "worker_max_memory_mib": 0,
  "static_max_age": 2592000,
  "static_revalidate": false,
  "async_workers": 0,
  "async_queue_capacity": 0,
  "async_max_fibers": 256,
  "async_in_flight_cap": 0,
  "trace_context": true,
  "superglobals_enabled": true,
  "trusted_proxies": false,
  "plugins": {
    "otel": {
      "enabled": true,
      "protocol": "grpc",
      "service_name": "oxphp"
    },
    "apm": {
      "enabled": true,
      "slow_query_ms": 100,
      "db_capture_params": false,
      "hooks_registered": 33
    }
  }
}

Note

La réponse /config servie expurge quelques clés que porte la représentation interne Config : les chemins du certificat et de la clé TLS ne sont jamais émis (tls_enabled indique si TLS est actif), et internal_addr et error_pages_dir sont retirés — topologie de déploiement et chemins de système de fichiers qui aident un attaquant et ne sont pas nécessaires aux collecteurs de métriques.

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

Référence de configuration

Valeurs booléennes

Serveur

Workers PHP

Workers statiques ou dynamiques

Mode worker

Déprécié : INDEX_FILE et WORKER_FILE

SAPI / PHP

Délais d'expiration

Limitation de débit

Sécurité

TLS

HTTP/2

Fichiers statiques

Journalisation

Observabilité

OpenTelemetry

APM

Workers asynchrones

État partagé

Profilage

Exemples de configurations

Développement

Production (Framework)

Production (mode worker)

TLS

Inspecter la configuration active

Voir aussi

Déprécié : `INDEX_FILE` et `WORKER_FILE`