Superglobales

OxPHP renseigne toutes les superglobales PHP standard avant l'exécution de votre script, en reproduisant le comportement que les développeurs PHP attendent d'une configuration serveur traditionnelle. Les valeurs sont disponibles dès la première ligne de votre code, sans aucune initialisation requise.

$_SERVER

OxPHP construit $_SERVER à partir de la requête HTTP entrante en suivant la spécification CGI/1.1. Les variables d'environnement du processus sont importées en premier ; les variables CGI sont définies ensuite, de sorte que les valeurs propres à la requête écrasent toujours les clés d'environnement qui entreraient en collision.

Variables standard

Variable	Description	Exemple
`SCRIPT_FILENAME`	Chemin absolu, sur le système de fichiers, du script PHP en cours d'exécution	`/var/www/html/public/index.php`
`DOCUMENT_ROOT`	Répertoire racine web configuré via la variable d'environnement `DOCUMENT_ROOT`	`/var/www/html/public`
`SERVER_SOFTWARE`	Identifiant du serveur (porte la version d'OxPHP en cours d'exécution)	`OxPHP/0.11.0`
`SERVER_PROTOCOL`	Version du protocole HTTP négociée	`HTTP/2`
`REQUEST_METHOD`	Méthode HTTP	`GET`
`REQUEST_URI`	URI complète avec chaîne de requête	`/app?page=2`
`SCRIPT_NAME`	Chemin du script exécuté, relatif à `DOCUMENT_ROOT` — le contrôleur frontal en mode Framework, et non l'URI de la requête	`/index.php`
`DOCUMENT_URI`	Alias de `SCRIPT_NAME`, pour la compatibilité avec nginx/PHP-FPM	`/index.php`
`PHP_SELF`	`SCRIPT_NAME` suivi de `PATH_INFO` lorsqu'il est présent, sinon égal à `SCRIPT_NAME`	`/index.php/user/42`
`QUERY_STRING`	Portion de requête de l'URI (chaîne vide en son absence)	`page=2`
`SERVER_NAME`	Nom d'hôte issu de l'en-tête `Host`	`example.com`
`SERVER_PORT`	Port issu de l'en-tête `Host`	`8080`
`REMOTE_ADDR`	Adresse IP du client	`172.17.0.1`
`REMOTE_PORT`	Numéro de port du client	`54321`
`HTTPS`	Défini à `"on"` lorsque la connexion utilise TLS ; absent sinon	`on`
`REQUEST_SCHEME`	`"https"` pour les connexions TLS, `"http"` sinon	`https`
`CONTENT_TYPE`	Valeur de l'en-tête `Content-Type` (sans le préfixe `HTTP_`)	`application/json`
`CONTENT_LENGTH`	Valeur de l'en-tête `Content-Length` (sans le préfixe `HTTP_`)	`128`
`REQUEST_TIME`	Horodatage Unix (entier) au démarrage de la requête	`1738800000`
`REQUEST_TIME_FLOAT`	Horodatage Unix avec précision à la microseconde	`1738800000.123456`
`GATEWAY_INTERFACE`	Chaîne de version CGI	`CGI/1.1`

Lorsque l'en-tête Host est absent, SERVER_NAME vaut par défaut localhost et SERVER_PORT vaut par défaut 80 (ou 443 en TLS).

En-têtes de requête HTTP

Tous les en-têtes de la requête HTTP sont ajoutés à $_SERVER avec un préfixe HTTP_. Les noms d'en-tête sont mis en majuscules et les tirets remplacés par des tirets bas, conformément aux conventions CGI/1.1 :

text

Accept: text/html            -> HTTP_ACCEPT
X-Forwarded-For: 1.2.3.4    -> HTTP_X_FORWARDED_FOR
Authorization: Bearer abc    -> HTTP_AUTHORIZATION
Cookie: session=xyz          -> HTTP_COOKIE

Note

Content-Type et Content-Length apparaissent sans le préfixe HTTP_ — sous la forme CONTENT_TYPE et CONTENT_LENGTH — comme l'exige la spécification CGI.

Derrière un reverse proxy

Lorsque TRUSTED_PROXIES est configuré et que le pair de la requête fait partie de l'ensemble de confiance, OxPHP réécrit les clés $_SERVER suivantes à partir des en-têtes transférés (X-Forwarded-* ou Forwarded de la RFC 7239) :

Variable	Valeur lorsque le pair est de confiance	Valeur sinon
`REMOTE_ADDR`	Adresse non fiable la plus à droite de `X-Forwarded-For` / `Forwarded`	IP du pair direct
`REMOTE_PORT`	Port source du client issu de `Forwarded: for=ip:port`, sinon `0`	Port du pair direct
`HTTPS`	`"on"` lorsque `X-Forwarded-Proto: https`	Défini uniquement lorsque la connexion du pair est en TLS
`REQUEST_SCHEME`	`"https"` / `"http"` d'après `X-Forwarded-Proto`	D'après l'état TLS réel
`SERVER_NAME`	Partie hôte de `X-Forwarded-Host`	Partie hôte de l'en-tête `Host`
`SERVER_PORT`	`X-Forwarded-Port`, sinon la partie port de `X-Forwarded-Host`, sinon 443/80 selon le schéma	Partie port de `Host`, ou 443/80

Les clés brutes HTTP_X_FORWARDED_FOR, HTTP_X_FORWARDED_PROTO, HTTP_X_FORWARDED_HOST, HTTP_X_FORWARDED_PORT et HTTP_FORWARDED restent inchangées dans $_SERVER — les valeurs réécrites et les en-têtes d'origine sont tous deux disponibles.

REMOTE_PORT vaut "0" derrière un proxy de confiance, sauf si le proxy envoie Forwarded: for=ip:port de la RFC 7239 — ni X-Forwarded-For ni la sélection de l'adresse non fiable la plus à droite ne portent de port source client, si bien que la valeur synthétique est mise à zéro plutôt que devinée.

Lorsque TRUSTED_PROXIES n'est pas défini, aucune réécriture n'a lieu et REMOTE_ADDR correspond toujours au pair direct — généralement votre répartiteur de charge, et non le client final. Analyser X-Forwarded-For à la main est source d'erreurs (adresse la plus à gauche ou la plus à droite, absence de vérification de confiance CIDR) ; préférez la configuration de TRUSTED_PROXIES. Consultez Proxys de confiance pour l'algorithme de confiance et la syntaxe de configuration.

Variables de contexte de trace

Lorsque le traçage distribué est activé, OxPHP ajoute des variables de contexte de trace à $_SERVER :

Variable	Description	Exemple
`OXPHP_TRACE_ID`	ID de trace W3C pour la requête en cours	`4bf92f3577b34da6a3ce929d0e0e4736`
`OXPHP_SPAN_ID`	ID de span pour le span serveur d'OxPHP	`00f067aa0ba902b7`
`OXPHP_PARENT_SPAN_ID`	ID du span parent issu du service en amont (vide si racine)	`b9c7c989f97918e1`

Ces variables ne sont présentes que lorsqu'un en-tête traceparent valide arrive ou lorsqu'OxPHP génère une nouvelle trace. Si le traçage n'est pas configuré, ces clés sont absentes.

Différences avec PHP-FPM

Les variables suivantes se comportent différemment par rapport à une configuration PHP-FPM standard :

Variable	Comportement
`SERVER_ADDR`	Non défini. OxPHP ne renseigne pas l'adresse IP locale du serveur.
`PATH_INFO`	Défini automatiquement — voir Comportement de PATH_INFO ci-dessous.
`PATH_TRANSLATED`	Non défini.
`PHP_AUTH_USER` / `PHP_AUTH_PW` / `AUTH_TYPE`	Non extraits de l'en-tête `Authorization`. Lisez directement `$_SERVER['HTTP_AUTHORIZATION']`.
`REDIRECT_STATUS`	Non défini. OxPHP n'utilise pas de mécanisme de redirection interne.

Exemple

php

<?php
$method  = $_SERVER['REQUEST_METHOD'];
$uri     = $_SERVER['REQUEST_URI'];
$ip      = $_SERVER['REMOTE_ADDR'];
$host    = $_SERVER['SERVER_NAME'];
$scheme  = $_SERVER['REQUEST_SCHEME'];  // "http" or "https"

// Read a custom header
$token = $_SERVER['HTTP_AUTHORIZATION'] ?? '';

// REMOTE_ADDR is already the real client IP when TRUSTED_PROXIES is configured.
// Without it, REMOTE_ADDR is the direct peer (usually a load balancer).
$clientIp = $_SERVER['REMOTE_ADDR'];

// Check TLS without checking the port
if (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] === 'on') {
    // Secure connection
}

Comportement de PATH_INFO

$_SERVER['PATH_INFO'] est renseigné automatiquement selon le mode de routage actif. Il n'existe aucun indicateur de fonctionnalité — l'ancienne variable d'environnement SPLIT_PATH_INFO_ENABLED a été supprimée.

Mode de routage	Quand il est défini	Valeur
Traditionnel (`ENTRY_FILE` non défini)	Uniquement lorsque l'URI contient `.php/` et que le préfixe du script existe sur le disque	Fin de chaîne après le segment du script
Framework (`ENTRY_FILE=index.php`)	Uniquement lorsque la requête nomme explicitement le fichier d'entrée avec un segment final (`/index.php/extra`)	Fin de chaîne après le fichier d'entrée, par ex. `/news`
SPA (`ENTRY_FILE=index.html`)	Jamais — PHP ne s'exécute que pour les fichiers `.php` exacts, pas de PATH_INFO	—

SCRIPT_NAME identifie toujours le script exécuté (le fichier résolu, relatif à la racine du document), de sorte qu'en routage normal PATH_INFO n'est présent que lorsque SCRIPT_NAME est un préfixe littéral du chemin de la requête. Lorsqu'une requête est réécrite vers un contrôleur frontal qu'elle ne nomme pas (une route applicative, un index de répertoire, un repli sur échec de fichier statique), PATH_INFO est absent et le chemin d'origine se trouve dans REQUEST_URI. (Le repli PHP_DENY_PATHS est une exception délibérée : il définit PATH_INFO à l'URI d'origine assainie afin que le script de repli puisse s'en servir pour le routage.)

Exemples en mode traditionnel

OxPHP parcourt l'URI de gauche à droite à la recherche du premier segment .php qui correspond à un fichier réel sur le disque. Tout ce qui suit devient PATH_INFO :

URI de la requête	Fichier sur le disque	`SCRIPT_NAME`	`PATH_INFO`	`PHP_SELF`
`/app.php/user/42`	`app.php` existe	`/app.php`	`/user/42`	`/app.php/user/42`
`/index.php/api/v2/users`	`index.php` existe	`/index.php`	`/api/v2/users`	`/index.php/api/v2/users`
`/app.php`	`app.php` existe	`/app.php`	(absent)	`/app.php`
`/missing.php/foo`	fichier introuvable	repli sur `/index.php`	—	dépend du repli

Exemples en mode framework

Chaque requête non statique est réécrite vers index.php. PATH_INFO n'est défini que lorsque la requête nomme explicitement le fichier d'entrée avec un segment final ; pour les routes applicatives, le chemin d'origine est lu depuis REQUEST_URI.

URI de la requête	`SCRIPT_NAME`	`PATH_INFO`
`/api/users`	`/index.php`	(absent)
`/about.php`	`/index.php`	(absent)
`/index.php/news/local`	`/index.php`	`/news/local`
`/index.php`	`/index.php`	(absent)

Note

PATH_TRANSLATED n'est pas renseigné. Il est rarement utilisé en pratique et n'est pas défini par défaut par nginx ni par PHP-FPM.

$_GET

Les paramètres de la chaîne de requête sont analysés automatiquement à partir de l'URI de la requête.

php

<?php
// Request: GET /search?q=oxphp&page=2
$query = $_GET['q'];     // "oxphp"
$page  = $_GET['page'];  // "2"

La syntaxe de tableau fonctionne comme attendu :

php

<?php
// Request: GET /filter?tags[]=php&tags[]=async
$tags = $_GET['tags'];  // ["php", "async"]

Ce que voit filter_input(INPUT_GET, …)

filter_input(), filter_input_array() et filter_has_var() ne lisent pas $_GET, $_POST ni $_COOKIE. L'extension filter garde sa propre copie de l'entrée analysée, et dans un worker persistant cette copie est remplie par chaque requête — elle doit donc aussi être rendue par chaque requête, sans quoi les valeurs de requête, cookies de session et champs de corps d'un client restent lisibles par toutes les requêtes que le worker sert ensuite. OxPHP la rend au début de chaque requête, si bien que ces trois fonctions répondent pour la requête qui demande et pour aucune autre.

Le mode worker ajoute une limite. Si votre requête se met en pause (sleep(), un await, un appel intercepté) et qu'une autre requête s'exécute sur ce worker dans l'intervalle, le stockage devient celui de cette requête-là. Les lectures après la reprise répondent null plutôt que l'entrée de quelqu'un d'autre, et la copie qu'avait votre requête a disparu à ce moment-là. Il suffit que l'autre requête y démarre ou y reprenne — elle n'a pas besoin de se terminer. $_GET, $_POST et $_COOKIE voyagent avec la requête à travers une suspension et ne sont pas affectés : lisez-les, ou lisez les fonctions filter avant de vous suspendre.

Un appel n'a pas du tout le droit de se mettre en pause. filter_input_array() avec un tableau de définitions par champ lit le stockage une fois par champ, si bien qu'un FILTER_CALLBACK qui fait des E/S s'exécute en retenant le worker pour toute sa durée au lieu de le céder à une autre requête, et un Fiber::suspend() explicite dans un tel callback lève une exception. L'attente a tout de même lieu — c'est le thread worker qui attend plutôt que la requête — donc un callback lent se manifeste en latence pour tout ce qui fait la queue derrière lui, et passé QUEUE_WAIT_TIMEOUT_MS, ces requêtes en file sont délestées. Sa durée possible est fixée par ce à quoi le callback parle, pas par le serveur : un wrapper de flux abandonne après default_socket_timeout (60 secondes par défaut), tandis que mysqlnd attend mysqlnd.net_read_timeout (un jour par défaut). Donnez à un tel appel un délai explicite — ou, mieux, exécutez la validation qui atteint une base de données ou un cache sur la valeur après que filter_input_array() l'a renvoyée.

$_POST

OxPHP prend en charge les deux types de contenu standard pour les soumissions de formulaire :

application/x-www-form-urlencoded — données de formulaire HTML standard
multipart/form-data — envois de fichiers combinés à des champs de formulaire

php

<?php
// Request: POST /login
// Content-Type: application/x-www-form-urlencoded
// Body: username=admin&password=secret

$username = $_POST['username'];  // "admin"
$password = $_POST['password'];  // "secret"

Pour du JSON ou d'autres types de contenu, utilisez plutôt php://input :

php

<?php
// Request: POST /api/users
// Content-Type: application/json
// Body: {"name":"Alice","email":"[email protected]"}

$data  = json_decode(file_get_contents('php://input'), true);
$name  = $data['name'];   // "Alice"
$email = $data['email'];  // "[email protected]"

Note

filter_input(INPUT_POST, …) lit la copie du corps propre à l'extension filter plutôt que $_POST — voir la note sous $_GET pour ce qu'est cette copie et combien de temps elle dure.

$_COOKIE

Les cookies sont analysés à partir de l'en-tête de requête Cookie.

php

<?php
// Request with: Cookie: session=abc123; theme=dark
$session = $_COOKIE['session'];  // "abc123"
$theme   = $_COOKIE['theme'];    // "dark"

Note

Les cookies portant le préfixe __oxp_ sont réservés aux plugins internes d'OxPHP. Ils sont retirés de l'en-tête Cookie avant qu'il n'atteigne PHP et n'apparaîtront pas dans $_COOKIE.

Note

filter_input(INPUT_COOKIE, …) lit la copie des cookies propre à l'extension filter plutôt que $_COOKIE — voir la note sous $_GET pour ce qu'est cette copie et combien de temps elle dure.

$_FILES

Les envois de fichiers effectués via multipart/form-data remplissent le tableau $_FILES avec la structure PHP standard :

php

<?php
// $_FILES['avatar'] structure:
// [
//     'name'     => 'photo.jpg',       // Original filename sent by the client
//     'type'     => 'image/jpeg',      // MIME type declared by the client
//     'tmp_name' => '/tmp/phpAb12Cd',  // Temporary file path on the server
//     'error'    => 0,                 // UPLOAD_ERR_OK (0 means no error)
//     'size'     => 204800,            // File size in bytes
// ]

if ($_FILES['avatar']['error'] === UPLOAD_ERR_OK) {
    $tmp  = $_FILES['avatar']['tmp_name'];
    $name = basename($_FILES['avatar']['name']);
    move_uploaded_file($tmp, "/uploads/$name");
}

$_REQUEST

$_REQUEST est un tableau fusionné de $_GET, $_POST et, éventuellement, $_COOKIE, construit par PHP selon la directive INI request_order (par défaut : "GP" — GET, puis POST). La fusion elle-même suit les règles de PHP, inchangées.

php

<?php
// GET /form?action=preview with POST body: action=submit
$action = $_REQUEST['action'];  // "submit" (POST overrides GET with default order)

Mode worker

$_REQUEST est reconstruit pour chaque requête. PHP le construit normalement de façon paresseuse, une seule fois, au premier chargement d'un script qui le mentionne — ce qui, dans un worker persistant, signifierait que chaque requête ultérieure lit les paramètres de la première. OxPHP force la reconstruction, si bien que le tableau fusionné décrit toujours la requête en cours de traitement.

$_ENV

$_ENV contient l'environnement du processus. En mode traditionnel, il se comporte exactement comme sous PHP-FPM : PHP le repeuple depuis l'environnement à chaque requête, sous réserve de variables_order.

Le mode worker le fige. Un worker s'amorce une fois, et les chargeurs de .env (vlucas/phpdotenv, symfony/dotenv, le Env de Laravel) écrivent leurs valeurs directement dans $_ENV sans toucher à l'environnement du processus. Repeupler $_ENV à chaque requête effacerait donc la configuration de l'application dès sa deuxième requête ; en mode worker, le tableau est donc conservé pour la vie du worker une fois qu'il existe — les écritures que votre amorçage y fait restent visibles pour chaque requête que ce worker sert.

php

<?php
// bootstrap, before oxphp_worker()
Dotenv\Dotenv::createImmutable(__DIR__)->load();   // writes into $_ENV

oxphp_worker(function () {
    echo $_ENV['DATABASE_URL'];  // still there on request 10_000
});

Ce que voit filter_input(INPUT_ENV, …)

filter_input(INPUT_ENV, …), filter_input_array(INPUT_ENV) et filter_has_var(INPUT_ENV, …) lisent l'environnement du processus en mode worker. Ils ne lisent pas $_ENV, si bien que les valeurs que votre amorçage y a écrites n'en font pas partie. C'est ainsi que PHP se comporte partout, parce qu'écrire dans $_ENV donne au tableau sa propre copie et que l'extension filter continue de lire l'instantané de l'environnement pris par le moteur. Le mode worker ajoute une subtilité : l'instantané est celui pris quand $_ENV a été construit pour la première fois sur le worker, si bien qu'un appel putenv() fait ensuite n'y figure pas non plus. getenv() lit l'environnement vivant et n'est pas affecté ; $_ENV contient les valeurs du processus plus ce que votre amorçage a ajouté. Tout ceci ne concerne que INPUT_ENV : INPUT_GET, INPUT_POST et INPUT_COOKIE lisent un stockage qui leur est propre dans l'extension filter, décrit dans la note sous $_GET ci-dessus.

Le gel repose sur le auto_globals_jit=1 par défaut de PHP. Avec auto_globals_jit=0, PHP repeuple $_ENV depuis l'environnement du processus à chaque requête avant qu'aucune extension ne puisse intervenir, et les valeurs d'un chargeur de .env ne survivront pas en mode worker.

php://input

Le corps brut de la requête est disponible via le flux php://input. C'est la manière standard de lire des charges utiles JSON, XML ou tout type de contenu autre que des soumissions de formulaire.

php

<?php
$body = file_get_contents('php://input');
$data = json_decode($body, true);

php://input peut être rembobiné et lu plusieurs fois au sein d'une même requête.

Note

php://input est vide pour les requêtes multipart/form-data. Utilisez $_POST et $_FILES dans ce cas.

Désactiver les superglobales

Définissez SUPERGLOBALS_ENABLED=false pour désactiver le remplissage de $_GET, $_POST, $_COOKIE, $_FILES et $_SERVER. Une fois désactivés, ces tableaux sont vides. Utilisez plutôt l'API de requête HTTP (oxphp_http_request()) pour accéder aux données de la requête.

bash

SUPERGLOBALS_ENABLED=false # superglobals are empty arrays

Les éléments suivants restent disponibles quel que soit ce réglage :

Quoi	Pourquoi
`$_SESSION`	Géré par le module de session de PHP, et non par la SAPI
`php://input`	Un flux, pas une superglobale
`header()`, `headers_list()`, etc.	Fonctions de la SAPI, pas des superglobales
`session_start()` et les autres fonctions `session_*()`	Fonctions natives de PHP
`oxphp_http_request()`	Toujours disponible — l'alternative recommandée

Vous pouvez vérifier le réglage courant à l'exécution :

php

if (!oxphp_superglobals_enabled()) {
    $request = oxphp_http_request();
    $page = $request->query('page', 1);
}

Voir aussi

API de requête HTTP -- objet de requête typé, à chargement paresseux, comme alternative aux superglobales
Fonctions PHP -- oxphp_request_id(), oxphp_worker_id() et les autres fonctions de l'extension
Mode worker -- comment les superglobales sont rafraîchies entre les requêtes des workers
Référence de configuration -- DOCUMENT_ROOT et les autres variables de configuration du serveur