Zmienne superglobalne

OxPHP wypełnia każdą standardową zmienną superglobalną PHP przed uruchomieniem Twojego skryptu, odwzorowując zachowanie, jakiego programiści PHP oczekują od tradycyjnej konfiguracji serwera. Wartości są dostępne od pierwszej linii kodu, bez potrzeby jakiejkolwiek inicjalizacji.

$_SERVER

OxPHP buduje $_SERVER na podstawie przychodzącego żądania HTTP zgodnie ze specyfikacją CGI/1.1. Najpierw importowane są zmienne środowiskowe procesu, a dopiero potem ustawiane są zmienne CGI, dzięki czemu wartości specyficzne dla żądania zawsze nadpisują kolidujące z nimi klucze środowiskowe.

Zmienne standardowe

Zmienna	Opis	Przykład
`SCRIPT_FILENAME`	Bezwzględna ścieżka w systemie plików do wykonywanego skryptu PHP	`/var/www/html/public/index.php`
`DOCUMENT_ROOT`	Katalog główny serwera WWW skonfigurowany zmienną środowiskową `DOCUMENT_ROOT`	`/var/www/html/public`
`SERVER_SOFTWARE`	Identyfikator serwera (zawiera wersję działającego OxPHP)	`OxPHP/0.10.0`
`SERVER_PROTOCOL`	Wynegocjowana wersja protokołu HTTP	`HTTP/2`
`REQUEST_METHOD`	Metoda HTTP	`GET`
`REQUEST_URI`	Pełny URI wraz z ciągiem zapytania	`/app?page=2`
`SCRIPT_NAME`	Ścieżka wykonywanego skryptu względem `DOCUMENT_ROOT` — front controller w trybie Framework, a nie URI żądania	`/index.php`
`DOCUMENT_URI`	Alias dla `SCRIPT_NAME`, dla zgodności z nginx/PHP-FPM	`/index.php`
`PHP_SELF`	`SCRIPT_NAME` wraz z `PATH_INFO`, gdy jest obecne, w przeciwnym razie równe `SCRIPT_NAME`	`/index.php/user/42`
`QUERY_STRING`	Część zapytania URI (pusty ciąg znaków, gdy nie występuje)	`page=2`
`SERVER_NAME`	Nazwa hosta z nagłówka `Host`	`example.com`
`SERVER_PORT`	Port z nagłówka `Host`	`8080`
`REMOTE_ADDR`	Adres IP klienta	`172.17.0.1`
`REMOTE_PORT`	Numer portu klienta	`54321`
`HTTPS`	Ustawione na `"on"`, gdy połączenie korzysta z TLS; w przeciwnym razie nieobecne	`on`
`REQUEST_SCHEME`	`"https"` dla połączeń TLS, w przeciwnym razie `"http"`	`https`
`CONTENT_TYPE`	Wartość nagłówka `Content-Type` (bez prefiksu `HTTP_`)	`application/json`
`CONTENT_LENGTH`	Wartość nagłówka `Content-Length` (bez prefiksu `HTTP_`)	`128`
`REQUEST_TIME`	Znacznik czasu Unix (liczba całkowita) rozpoczęcia żądania	`1738800000`
`REQUEST_TIME_FLOAT`	Znacznik czasu Unix z dokładnością do mikrosekund	`1738800000.123456`
`GATEWAY_INTERFACE`	Ciąg znaków z wersją CGI	`CGI/1.1`

Gdy nagłówek Host jest nieobecny, SERVER_NAME przyjmuje domyślnie wartość localhost, a SERVER_PORT domyślnie 80 (lub 443 dla TLS).

Nagłówki żądania HTTP

Wszystkie nagłówki żądania HTTP są dodawane do $_SERVER z prefiksem HTTP_. Nazwy nagłówków są zamieniane na wielkie litery, a myślniki na podkreślenia, zgodnie z konwencjami 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 i Content-Length pojawiają się bez prefiksu HTTP_ — jako CONTENT_TYPE i CONTENT_LENGTH — zgodnie z wymaganiami specyfikacji CGI.

Za odwrotnym proxy

Gdy TRUSTED_PROXIES jest skonfigurowane, a peer żądania należy do zaufanego zbioru, OxPHP przepisuje następujące klucze $_SERVER na podstawie nagłówków przekazujących (X-Forwarded-* lub Forwarded z RFC 7239):

Zmienna	Wartość, gdy peer jest zaufany	Wartość w przeciwnym razie
`REMOTE_ADDR`	Skrajnie prawy niezaufany adres z `X-Forwarded-For` / `Forwarded`	Adres IP bezpośredniego peera
`REMOTE_PORT`	Port źródłowy klienta z `Forwarded: for=ip:port`, w przeciwnym razie `0`	Port bezpośredniego peera
`HTTPS`	`"on"`, gdy `X-Forwarded-Proto: https`	Ustawione tylko wtedy, gdy połączenie z peerem korzysta z TLS
`REQUEST_SCHEME`	`"https"` / `"http"` z `X-Forwarded-Proto`	Na podstawie rzeczywistego stanu TLS
`SERVER_NAME`	Część z hostem z `X-Forwarded-Host`	Część z hostem z nagłówka `Host`
`SERVER_PORT`	`X-Forwarded-Port`, w przeciwnym razie część z portem z `X-Forwarded-Host`, w przeciwnym razie 443/80 zależnie od schematu	Część z portem z `Host` lub 443/80

Surowe klucze HTTP_X_FORWARDED_FOR, HTTP_X_FORWARDED_PROTO, HTTP_X_FORWARDED_HOST, HTTP_X_FORWARDED_PORT oraz HTTP_FORWARDED pozostają w $_SERVER bez zmian — dostępne są zarówno wartości przepisane, jak i oryginalne nagłówki.

REMOTE_PORT ma wartość "0" za zaufanym proxy, chyba że proxy wysyła Forwarded: for=ip:port zgodne z RFC 7239 — ani X-Forwarded-For, ani wybór skrajnie prawego niezaufanego adresu nie przenoszą portu źródłowego klienta, więc syntetyczna wartość jest zerowana, a nie zgadywana.

Gdy TRUSTED_PROXIES nie jest ustawione, przepisywanie nie następuje, a REMOTE_ADDR jest zawsze bezpośrednim peerem — zazwyczaj Twoim load balancerem, a nie końcowym klientem. Ręczne parsowanie X-Forwarded-For jest podatne na błędy (skrajnie lewy kontra skrajnie prawy, brak sprawdzania zaufania na podstawie CIDR); lepiej skonfigurować TRUSTED_PROXIES. Zobacz Zaufane proxy, aby poznać algorytm zaufania i składnię konfiguracji.

Zmienne kontekstu śledzenia

Gdy śledzenie rozproszone jest włączone, OxPHP dodaje do $_SERVER zmienne kontekstu śledzenia:

Zmienna	Opis	Przykład
`OXPHP_TRACE_ID`	Identyfikator śledzenia W3C dla bieżącego żądania	`4bf92f3577b34da6a3ce929d0e0e4736`
`OXPHP_SPAN_ID`	Identyfikator spanu dla spanu serwera OxPHP	`00f067aa0ba902b7`
`OXPHP_PARENT_SPAN_ID`	Identyfikator spanu nadrzędnego z usługi nadrzędnej (pusty, jeśli jest korzeniem)	`b9c7c989f97918e1`

Zmienne te są obecne tylko wtedy, gdy przychodzi prawidłowy nagłówek traceparent lub gdy OxPHP generuje nowy ślad. Jeśli śledzenie nie jest skonfigurowane, klucze te są nieobecne.

Różnice względem PHP-FPM

Następujące zmienne zachowują się inaczej niż w standardowej konfiguracji PHP-FPM:

Zmienna	Zachowanie
`SERVER_ADDR`	Nieustawione. OxPHP nie wypełnia lokalnego adresu IP serwera.
`PATH_INFO`	Ustawiane automatycznie — zobacz Zachowanie PATH_INFO poniżej.
`PATH_TRANSLATED`	Nieustawione.
`PHP_AUTH_USER` / `PHP_AUTH_PW` / `AUTH_TYPE`	Nie są wyodrębniane z nagłówka `Authorization`. Odczytaj `$_SERVER['HTTP_AUTHORIZATION']` bezpośrednio.
`REDIRECT_STATUS`	Nieustawione. OxPHP nie korzysta z wewnętrznego mechanizmu przekierowań.

Przykład

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
}

Zachowanie PATH_INFO

$_SERVER['PATH_INFO'] jest wypełniane automatycznie na podstawie aktywnego trybu routingu. Nie ma żadnej flagi funkcji — wcześniejsza zmienna środowiskowa SPLIT_PATH_INFO_ENABLED została usunięta.

Tryb routingu	Kiedy ustawiane	Wartość
Traditional (`ENTRY_FILE` nieustawione)	Tylko gdy URI zawiera `.php/` i prefiks skryptu istnieje na dysku	Końcówka po segmencie skryptu
Framework (`ENTRY_FILE=index.php`)	Tylko gdy żądanie jawnie wskazuje plik wejściowy z końcowym segmentem (`/index.php/extra`)	Końcówka po pliku wejściowym, np. `/news`
SPA (`ENTRY_FILE=index.html`)	Nigdy — PHP działa wyłącznie dla dokładnych plików `.php`, bez PATH_INFO	—

SCRIPT_NAME zawsze wskazuje wykonywany skrypt (rozwiązany plik względem katalogu głównego dokumentów), więc przy zwykłym routingu PATH_INFO jest obecne tylko wtedy, gdy SCRIPT_NAME jest dosłownym prefiksem ścieżki żądania. Gdy żądanie zostaje przepisane na front controller, którego nie wskazuje (trasa aplikacji, indeks katalogu, awaryjny wariant przy nietrafieniu w plik statyczny), PATH_INFO jest nieobecne, a oryginalna ścieżka znajduje się w REQUEST_URI. (Wariant awaryjny PHP_DENY_PATHS to celowy wyjątek: ustawia PATH_INFO na oryginalny, oczyszczony URI, aby skrypt awaryjny mógł na jego podstawie routować.)

Przykłady trybu Traditional

OxPHP skanuje URI od lewej do prawej w poszukiwaniu pierwszego segmentu .php, któremu odpowiada rzeczywisty plik na dysku. Wszystko, co następuje po nim, staje się PATH_INFO:

URI żądania	Plik na dysku	`SCRIPT_NAME`	`PATH_INFO`	`PHP_SELF`
`/app.php/user/42`	`app.php` istnieje	`/app.php`	`/user/42`	`/app.php/user/42`
`/index.php/api/v2/users`	`index.php` istnieje	`/index.php`	`/api/v2/users`	`/index.php/api/v2/users`
`/app.php`	`app.php` istnieje	`/app.php`	(nieobecne)	`/app.php`
`/missing.php/foo`	plik nie znaleziony	przechodzi awaryjnie do `/index.php`	—	zależy od wariantu awaryjnego

Przykłady trybu Framework

Każde niestatyczne żądanie jest przepisywane na index.php. PATH_INFO jest ustawiane tylko wtedy, gdy żądanie jawnie wskazuje plik wejściowy z końcowym segmentem; w przypadku tras aplikacji oryginalna ścieżka jest odczytywana z REQUEST_URI.

URI żądania	`SCRIPT_NAME`	`PATH_INFO`
`/api/users`	`/index.php`	(nieobecne)
`/about.php`	`/index.php`	(nieobecne)
`/index.php/news/local`	`/index.php`	`/news/local`
`/index.php`	`/index.php`	(nieobecne)

Note

PATH_TRANSLATED nie jest wypełniane. W praktyce jest rzadko używane i domyślnie nie jest ustawiane ani przez nginx, ani przez PHP-FPM.

$_GET

Parametry ciągu zapytania są parsowane automatycznie z URI żądania.

php

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

Składnia tablicowa działa zgodnie z oczekiwaniami:

php

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

$_POST

OxPHP obsługuje dwa standardowe typy zawartości dla przesyłanych formularzy:

application/x-www-form-urlencoded — standardowe dane formularza HTML
multipart/form-data — przesyłanie plików w połączeniu z polami formularza

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"

W przypadku JSON lub innych typów zawartości użyj zamiast tego 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]"

Ciasteczka są parsowane z nagłówka żądania Cookie.

php

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

Note

Ciasteczka z prefiksem __oxp_ są zarezerwowane dla wewnętrznych wtyczek OxPHP. Są usuwane z nagłówka Cookie, zanim dotrze on do PHP, i nie pojawią się w $_COOKIE.

$_FILES

Pliki przesłane przez multipart/form-data wypełniają tablicę $_FILES standardową strukturą PHP:

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 to scalona tablica $_GET, $_POST i opcjonalnie $_COOKIE, budowana przez PHP zgodnie z dyrektywą INI request_order (domyślnie: "GP" — GET, a następnie POST). OxPHP nie modyfikuje tego zachowania.

php

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

php://input

Surowe ciało żądania jest dostępne przez strumień php://input. To standardowy sposób odczytu ładunków JSON, XML lub dowolnego typu zawartości innego niż przesyłane formularze.

php

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

php://input można przewijać i odczytywać wielokrotnie w obrębie tego samego żądania.

Note

php://input jest puste dla żądań multipart/form-data. W ich przypadku użyj $_POST i $_FILES.

Wyłączanie zmiennych superglobalnych

Ustaw SUPERGLOBALS_ENABLED=false, aby wyłączyć wypełnianie $_GET, $_POST, $_COOKIE, $_FILES i $_SERVER. Po wyłączeniu tablice te są puste. Aby uzyskać dostęp do danych żądania, użyj zamiast tego API żądań HTTP (oxphp_http_request()).

bash

SUPERGLOBALS_ENABLED=false # superglobals are empty arrays

Następujące elementy pozostają dostępne niezależnie od tego ustawienia:

Co	Dlaczego
`$_SESSION`	Zarządzane przez moduł sesji PHP, a nie przez SAPI
`php://input`	Strumień, a nie zmienna superglobalna
`header()`, `headers_list()` itp.	Funkcje SAPI, a nie zmienne superglobalne
`session_start()` i inne funkcje `session_*()`	Natywne funkcje PHP
`oxphp_http_request()`	Zawsze dostępna — zalecana alternatywa

Bieżące ustawienie można sprawdzić w czasie działania:

php

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

Zobacz też

API żądań HTTP -- typowany, leniwie ładowany obiekt żądania jako alternatywa dla zmiennych superglobalnych
Funkcje PHP -- oxphp_request_id(), oxphp_worker_id() i inne funkcje rozszerzenia
Tryb worker -- jak zmienne superglobalne są odświeżane między żądaniami workera
Dokumentacja konfiguracji -- DOCUMENT_ROOT i inne zmienne konfiguracyjne serwera