Dokumentacja konfiguracji

OxPHP konfiguruje się w całości za pomocą zmiennych środowiskowych. Nie ma żadnych plików konfiguracyjnych do zarządzania, a każde ustawienie ma wartość domyślną, dzięki czemu wdrożenie bez żadnej konfiguracji działa od razu po uruchomieniu.

Wartości logiczne

Zmienne oznaczone jako logiczne akceptują ustalony, kanoniczny zbiór wartości — niewrażliwy na wielkość liter i pozbawiony spacji brzegowych:

prawda: on, true, 1, yes
fałsz: off, false, 0, no

Każda niepusta wartość spoza tego zbioru — literówki w rodzaju ture — powoduje natychmiastowy błąd przy starcie, wskazujący nazwę zmiennej. Dzięki temu błędna konfiguracja zostaje wychwycona jeszcze przed ruchem, zamiast po cichu ustawić flagę na odwrót.

Nieustawiona zmienna lub puste przypisanie (FOO=) wraca do udokumentowanej wartości domyślnej. Puste jest celowo traktowane jak nieustawione: podstawianie w Docker Compose / Kubernetes w rodzaju FOO=${FOO} daje FOO=, gdy zmienna hosta nie istnieje, a to nie powinno uniemożliwiać uruchomienia serwera.

Serwer

Zmienna	Wartość domyślna	Opis
`LISTEN_ADDR`	`0.0.0.0:80`	Adres i port głównego serwera HTTP
`DOCUMENT_ROOT`	`/var/www/html/public`	Katalog główny do serwowania plików i skryptów PHP
`ENTRY_FILE`	(nieustawione)	Pojedynczy kanoniczny skrypt wejściowy. Nieustawione = bezpośrednie mapowanie plików. `*.php` = front controller. Inny niż `.php` = statyczny fallback (SPA). Z `WORKER_MODE_ENABLED=true` = bootstrap workera. Rozwiązywany względem `DOCUMENT_ROOT` (ścieżki względne i `..` są dozwolone; ścieżki absolutne używane bez zmian). Zobacz Routing
`WORKER_MODE_ENABLED`	`false`	Włącza trwały tryb worker. Wymaga, aby `ENTRY_FILE` wskazywał na skrypt `.php`. Wartość logiczna — zobacz Wartości logiczne
`MAX_CONNECTIONS`	`10000`	Maksymalna liczba jednoczesnych połączeń TCP
`TOKIO_WORKERS`	CPU / 2 (min 1)	Wątki asynchronicznego I/O. `1` = jednowątkowo, `N > 1` = stała liczba wątków, nieustawione = automatycznie (CPU / 2, min 1)

Workery PHP

Zmienna	Wartość domyślna	Opis
`EXECUTOR`	`sapi`	Backend wykonawczy PHP. `sapi` do wykonywania PHP, `stub` do benchmarków bez PHP
`PHP_WORKERS`	CPU / 2 (min 1)	Rozmiar puli workerów. `N` = stała pula, `MIN:MAX` = skalowanie dynamiczne, `0` = automatycznie
`PHP_WORKERS_IDLE_SECONDS`	`30`	Liczba sekund bezczynności workera dynamicznego, po których zostaje wycofany (tylko tryb dynamiczny)
`QUEUE_CAPACITY`	Początkowa liczba workerów × 128	Maksymalna liczba oczekujących żądań w kolejce PHP. Po zapełnieniu zwraca 529. W przypadku pul dynamicznych (`MIN:MAX`) początkowa liczba workerów = wartość minimalna

Workery statyczne a dynamiczne

Ustaw PHP_WORKERS na pojedynczą liczbę, aby uzyskać stałą pulę:

bash

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

Ustaw PHP_WORKERS na MIN:MAX, aby uzyskać automatyczne skalowanie:

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

W trybie dynamicznym OxPHP zwiększa liczbę workerów, gdy wszystkie są zajęte, i zmniejsza ją, gdy workery pozostają bezczynne dłużej niż PHP_WORKERS_IDLE_SECONDS.

Tryb worker

Zmienna	Wartość domyślna	Opis
`WORKER_MAX_MEMORY_MIB`	`0`	Maksymalna pamięć w MiB na worker przed recyklingiem. `0` = bez limitu

Ustaw WORKER_MODE_ENABLED=true i skieruj ENTRY_FILE na swój skrypt bootstrap workera (np. ENTRY_FILE=worker.php lub ENTRY_FILE=../worker.php). Procesy PHP pozostają wtedy żywe pomiędzy żądaniami, utrzymując stan bootstrapu (autoloadery, połączenia z bazą danych) w pamięci. Workery są recyklowane automatycznie, gdy przekroczą WORKER_MAX_MEMORY_MIB, lub na żądanie, gdy aplikacja wywoła Worker::scheduleExit(). Parametr WORKER_MAX_REQUESTS z wcześniejszych wydań jest przestarzały i ignorowany — nie ustawiaj żadnego z nich lub przejdź na Worker::scheduleExit().

Przestarzałe: `INDEX_FILE` i `WORKER_FILE`

Starsze zmienne INDEX_FILE i WORKER_FILE są nadal parsowane w celu zachowania zgodności wstecznej. Gdy są ustawione, przy starcie emitują wpis logu WARN i są mapowane na nowy model:

Dawniej	Odpowiednik dzisiaj
`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`

Jeśli ustawiono zarówno stare, jak i nowe zmienne, wygrywają ENTRY_FILE / WORKER_MODE_ENABLED. Migruj w dogodnym momencie; przestarzałe formy zostaną usunięte w przyszłym wydaniu.

SAPI / PHP

Zmienna	Wartość domyślna	Opis
`SUPERGLOBALS_ENABLED`	`true`	Wypełnia superglobalne PHP (`$_GET`, `$_POST`, `$_COOKIE`, `$_FILES`, `$_SERVER`, `php://input`) przed wykonaniem skryptu. Ustaw na wartość fałszywą, aby pominąć wypełnianie — dane żądania są wtedy dostępne wyłącznie przez API obiektowe (`oxphp_http_request()`). Przydatne w aplikacjach, które korzystają bezpośrednio z API obiektowego i chcą uniknąć kosztu budowania superglobalnych przy każdym żądaniu

Limity czasu

Zmienna	Wartość domyślna	Opis
`HEADER_TIMEOUT_SECONDS`	`5`	Maksymalna liczba sekund na odebranie nagłówków HTTP po nawiązaniu połączenia (ochrona przed Slowloris)
`DRAIN_TIMEOUT_SECONDS`	`25`	Maksymalna liczba sekund oczekiwania na trwające połączenia podczas łagodnego zamknięcia

Czas wykonania PHP jest ograniczany przez własną dyrektywę ini max_execution_time (oraz set_time_limit() w czasie działania), a nie przez zmienną środowiskową OxPHP.

Ograniczanie liczby żądań

Zmienna	Wartość domyślna	Opis
`RATE_LIMIT`	`0` (wyłączone)	Maksymalna liczba żądań na IP w oknie czasowym. `0` wyłącza ograniczanie liczby żądań
`RATE_WINDOW_SECONDS`	`60`	Czas trwania okna ograniczania liczby żądań w sekundach

Bezpieczeństwo

Zmienna	Wartość domyślna	Opis
`FRAME_OPTIONS`	`DENY`	Ochrona przed clickjackingiem. `DENY` blokuje wszelkie osadzanie w ramkach, `SAMEORIGIN` zezwala na osadzanie z tego samego pochodzenia, `off` wyłącza (użyj, gdy osadzaniem zarządzasz przez własne CSP). Ustawia zarówno `X-Frame-Options`, jak i `Content-Security-Policy: frame-ancestors`. Nagłówki bezpieczeństwa serwera są wartościami zapasowymi: wartości ustawione przez aplikację (np. PHP `header()`) mają pierwszeństwo i nigdy nie są nadpisywane. Para nagłówków dotyczących ramek jest powiązana w obie strony — ustawiony przez aplikację `X-Frame-Options` wyłącza serwerowy `Content-Security-Policy: frame-ancestors` (CSP ma pierwszeństwo nad `X-Frame-Options` w nowoczesnych przeglądarkach), a CSP aplikacji zawierający dyrektywę `frame-ancestors` wyłącza serwerowy `X-Frame-Options`. Zwróć uwagę, że to pierwszeństwo dotyczy również `X-Content-Type-Options`: wartość ustawiona przez aplikację jest zachowywana bez zmian, mimo że `nosniff` jest jej jedyną poprawną wartością — niepoprawna wartość wyłącza tę ochronę
`TRUSTED_PROXIES`	(nieustawione)	Sieci zaufanych reverse proxy (CIDR-y rozdzielone przecinkami lub `private`). Gdy ustawione, OxPHP wyodrębnia rzeczywisty adres IP klienta z nagłówków `Forwarded` (RFC 7239) lub `X-Forwarded-For`, używając algorytmu rightmost-non-trusted. Przetwarza również `X-Forwarded-Proto` i `X-Forwarded-Host` na potrzeby `$_SERVER['HTTPS']`, `REQUEST_SCHEME`, `SERVER_NAME` i `SERVER_PORT`. Nieustawione = funkcja wyłączona
`PHP_DENY_PATHS`	(nieustawione)	Wzorce glob rozdzielone przecinkami, których pliki `.php` nigdy nie mogą być wykonywane przez bezpośredni URI (np. `/uploads/,/cache/,/admin/legacy.php`). Wzorce mogą wskazywać całe katalogi lub pojedyncze pliki. Obowiązuje w trybach bezpośredniego mapowania — Traditional i SPA; ignorowane z ostrzeżeniem przy starcie w trybach Framework i Worker, które nigdy nie wykonują dowolnych plików `.php` bezpośrednio. Obejmuje również skrypty osiągane przez rozwiązywanie indeksu katalogu (`/uploads/` → `uploads/index.php`). W przypadku bezpośrednich URI `.php` dopasowanie następuje przed operacjami dyskowymi, więc zablokowane ścieżki dają tę samą odpowiedź niezależnie od tego, czy plik istnieje (brak wyroczni istnienia). Dawna nazwa `PHP_DENY_DIRS` jest akceptowana jako przestarzały alias i emituje `WARN` przy starcie. Zobacz Lista blokowania wykonywania PHP
`PHP_DENY_FALLBACK`	`404`	Co zwrócić przy dopasowaniu do `PHP_DENY_PATHS`. Albo status HTTP `400`–`599` (współpracuje z `ERROR_PAGES_DIR` dla własnego HTML), albo ścieżka URI z przedrostkiem `/` do zapasowego skryptu PHP wewnątrz `DOCUMENT_ROOT`. Skrypt zapasowy otrzymuje `OXPHP_DENIED_PATH` i `OXPHP_DENIED_PATTERN` w `$_SERVER`. Walidowane przy starcie: skrypt musi istnieć, po kanonizacji mieścić się wewnątrz `DOCUMENT_ROOT` i sam nie może pasować do `PHP_DENY_PATHS` (zapobieganie pętlom)
`SYMLINK_ALLOW_PATHS`	(nieustawione)	Rozdzielona przecinkami lista ścieżek absolutnych, w obrębie których dowiązania symboliczne mogą wychodzić poza `DOCUMENT_ROOT`. Każdy wpis musi już istnieć na dysku; ścieżki względne i nieistniejące przerywają start. Nieustawione = brak zgody na wyjścia poprzez dowiązania symboliczne. Zobacz Dozwolone ścieżki dowiązań symbolicznych

Specjalna wartość private rozwija się do wszystkich prywatnych sieci RFC-1918, adresów loopback oraz link-local (IPv4 i 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

Zmienna	Wartość domyślna	Opis
`TLS_CERT`	(nieustawione)	Ścieżka do certyfikatu TLS zakodowanego w PEM. Aby włączyć TLS, muszą być ustawione zarówno `TLS_CERT`, jak i `TLS_KEY`
`TLS_KEY`	(nieustawione)	Ścieżka do klucza prywatnego TLS zakodowanego w PEM
`TLS_MIN_VERSION`	`1.2`	Minimalna akceptowana wersja protokołu TLS: `1.2` lub `1.3`. Walidowana przy starcie (oraz przez `oxphp config --check`) nawet wtedy, gdy TLS nie jest włączony — każda inna wartość, w tym bajty spoza UTF-8, to twardy błąd startu. Pusta wartość jest traktowana jak nieustawiona

HTTP/2

Zmienna	Wartość domyślna	Opis
`H2_MAX_CONCURRENT_STREAMS`	`PHP_WORKERS_MAX × 4` (min 32)	Maksymalna liczba jednocześnie otwartych strumieni na połączenie HTTP/2
`H2_MAX_PENDING_RESET`	`20`	Maksymalna liczba ramek `RST_STREAM` w kolejce, zanim połączenie zostanie zamknięte (ochrona przed Rapid Reset)
`H2_MAX_HEADER_LIST_BYTES`	`65536`	Maksymalna łączna liczba zdekodowanych bajtów nagłówków na żądanie
`H2_KEEPALIVE_INTERVAL_SECS`	`20`	Liczba sekund między ramkami PING HTTP/2; `0` wyłącza
`H2_KEEPALIVE_TIMEOUT_SECS`	`10`	Liczba sekund oczekiwania na odpowiedź PING przed zamknięciem połączenia

Pliki statyczne

Zmienna	Wartość domyślna	Opis
`STATIC_MAX_AGE`	`30d`	`Cache-Control: max-age` dla plików statycznych. Akceptuje: `30s`, `5m`, `2h`, `30d`, `1w`, `1y`, same sekundy (`3600`) lub `off`, aby wyłączyć nagłówek. Zastępuje przestarzałą `STATIC_CACHE_TTL`.
`STATIC_REVALIDATE`	`off`	Wartość logiczna — zobacz Wartości logiczne. Ustaw na prawdę, aby włączyć rewalidację na podstawie mtime dla pamięciowego cache treści: czas modyfikacji pliku jest ponownie sprawdzany najwyżej raz na 3 sekundy na plik (nie na żądanie), a nieaktualne wpisy są automatycznie usuwane, dzięki czemu zmiany stają się widoczne w ciągu 3 sekund. Zastępuje przestarzałą `STATIC_CACHE` (gdzie `off` miało odwrotne znaczenie).
`COMPRESSION_LEVEL`	`4`	Jakość kompresji Brotli (0–11). `0` wyłącza kompresję

Logowanie

Zmienna	Wartość domyślna	Opis
`LOG_LEVEL`	`info`	Szczegółowość logów: `trace`, `debug`, `info`, `warn`, `error`
`ACCESS_LOG`	(nieustawione)	Rejestrowanie dostępu dla każdego żądania: `all` = każde żądanie, `error` = tylko 4xx/5xx, nieustawione = wyłączone

Note

ACCESS_LOG przyjmuje all lub error. Pozostaw nieustawione, aby całkowicie wyłączyć rejestrowanie dostępu.

Obserwowalność

Zmienna	Wartość domyślna	Opis
`INTERNAL_ADDR`	(nieustawione)	Adres serwera wewnętrznego (`/health`, `/metrics`, `/config`). Gdy nieustawione, serwer wewnętrzny nie jest uruchamiany. Wartość zawierająca tylko port (`:9090` lub `9090`) wiąże się z `127.0.0.1`; ustaw jawnie `0.0.0.0:9090`, aby udostępnić go poza hostem
`INTERNAL_ALLOW_IPS`	(nieustawione)	Lista dozwolonych CIDR/IP dla serwera wewnętrznego, rozdzielona przecinkami. Klient spoza listy otrzymuje `403` na `/metrics`, `/config` oraz ścieżkach wtyczek; sondy stanu (`/health`, `/healthz`, `/readyz`, `/startupz` oraz ich długie formy) pozostają osiągalne. Nieustawione/puste = zezwól wszystkim. Loopback nie jest domyślnie uwzględniony — dodaj `127.0.0.1/32` do listy, aby zachować dostęp z localhost. Nieprawidłowa lista przerywa start
`ERROR_PAGES_DIR`	(nieustawione)	Katalog zawierający własne strony błędów o nazwach `{status}.html` (np. `404.html`, `503.html`)
`MAX_QUERY_BODY`	`524288`	Maksymalny rozmiar ciała żądania w bajtach dla wewnętrznych endpointów zapytań (512 KiB)
`TRACE_CONTEXT`	`false`	Wartość logiczna — zobacz Wartości logiczne. Gdy prawda, włącza propagację W3C Trace Context: odczytuje nagłówki `traceparent`/`tracestate` i przekazuje je do PHP przez `$_SERVER`

OpenTelemetry

Zmienna	Wartość domyślna	Opis
`OTEL_ENABLED`	`false`	Włącza eksport spanów OpenTelemetry. Automatycznie ustawia `TRACE_CONTEXT=true`. Wartość logiczna — zobacz Wartości logiczne
`OTEL_EXPORTER_OTLP_PROTOCOL`	`grpc`	Protokół eksportu: `grpc` lub `http/protobuf`
`OTEL_EXPORTER_OTLP_ENDPOINT`	`http://localhost:4317` (gRPC) lub `http://localhost:4318` (HTTP)	Endpoint kolektora OTLP
`OTEL_EXPORTER_OTLP_TIMEOUT`	`10000`	Limit czasu eksportu w milisekundach
`OTEL_EXPORTER_OTLP_HEADERS`	(nieustawione)	Nagłówki uwierzytelniania: `key=value,key2=value2`
`OTEL_SERVICE_NAME`	`oxphp`	Nazwa usługi w eksportowanych spanach
`OTEL_SERVICE_VERSION`	(nieustawione)	Atrybut wersji usługi
`OTEL_RESOURCE_ATTRIBUTES`	(nieustawione)	Dodatkowe atrybuty zasobu: `env=prod,region=us-east-1`
`OTEL_TRACES_SAMPLER`	`parentbased_traceidratio`	Strategia próbkowania: `always_on`, `always_off`, `traceidratio`, `parentbased_always_on`, `parentbased_always_off`, `parentbased_traceidratio`
`OTEL_TRACES_SAMPLER_ARG`	`1.0`	Współczynnik próbkowania (0.0–1.0) dla samplerów opartych na współczynniku

Note

Nieprawidłowe lub wykraczające poza zakres wartości OTEL_TRACES_SAMPLER_ARG są przycinane do [0.0, 1.0] i logowane na poziomie warn. Nieznane wartości OTEL_TRACES_SAMPLER wracają do parentbased_traceidratio i są logowane.

APM

Zmienna	Wartość domyślna	Opis
`OTEL_APM_ENABLED`	`false`	Włącza APM: automatyczną instrumentację, przechwytywanie błędów oraz SDK śledzenia dla PHP. Wymaga `OTEL_ENABLED=true`. Wartość logiczna — zobacz Wartości logiczne
`OTEL_APM_SLOW_QUERY_MS`	`100`	Próg wolnego zapytania w milisekundach. Zapytania do bazy danych przekraczające ten próg otrzymują atrybut spanu `oxphp.db.slow=true`
`OTEL_APM_DB_CAPTURE_PARAMS_ENABLED`	`false`	Zapisuje parametry wiązania w atrybucie spanu `db.params`. Wyłącz w środowisku produkcyjnym, jeśli parametry mogą zawierać dane wrażliwe. Wartość logiczna — zobacz Wartości logiczne
`OTEL_APM_STACKTRACE_MAX_BYTES`	`8192`	Maksymalny rozmiar w bajtach atrybutu `exception.stacktrace`. Po przekroczeniu limitu ślad stosu jest obcinany od końca znacznikiem `…(truncated)`. `0` wyłącza obcinanie
`OTEL_APM_MESSAGE_MAX_BYTES`	`4096`	Maksymalny rozmiar w bajtach atrybutu `exception.message` (wartość domyślna odpowiada limitowi wartości na atrybut w New Relic). Po przekroczeniu limitu komunikat jest obcinany od końca znacznikiem `…(truncated)`. `0` wyłącza obcinanie

Gdy APM jest włączone, OxPHP automatycznie podpina się pod 33 wewnętrzne funkcje PHP (PDO, mysqli, cURL, Redis, Memcached, operacje we/wy na plikach), aby tworzyć spany potomne. Funkcje PHP oxphp_apm_*() są rejestrowane niezależnie od tego, czy APM jest włączone — gdy jest wyłączone, są bezpiecznymi operacjami no-op.

Workery asynchroniczne

Zmienna	Wartość domyślna	Opis
`ASYNC_WORKERS`	`0` (wyłączone)	Liczba dedykowanych wątków workerów asynchronicznych. Gdy `0`, funkcje asynchroniczne (`oxphp_async` itd.) są rejestrowane, ale przy wywołaniu rzucają `OxPHP\Async\AsyncException`. Ustaw wartość dodatnią, aby włączyć wykonywanie zadań w tle
`ASYNC_QUEUE_CAPACITY`	`ASYNC_WORKERS × 64`	Maksymalna liczba oczekujących zadań w kolejce asynchronicznej. `0` = automatycznie (liczba workerów × 64)
`ASYNC_MAX_FIBERS`	`256`	Limit na worker liczby jednoczesnych Fiberów zadań asynchronicznych. Globalny dla procesu limit zadań w toku (w kolejce + wykonywanych) wynosi `ASYNC_MAX_FIBERS × ASYNC_WORKERS`; próba wysłania ponad ten limit jest natychmiast odrzucana z `OxPHP\Async\AsyncException`, aby kompozycja fan-out nie mogła doprowadzić do zakleszczenia

Pula workerów asynchronicznych obsługuje zadania w tle typu fire-and-forget wysyłane z PHP. Jest odrębna od puli workerów PHP i nie jest wymagana do standardowej obsługi żądań.

Nieprawidłowa wartość w którejkolwiek z tych trzech zmiennych (np. ASYNC_WORKERS=8x) to błąd startu — powrót do wartości domyślnej po cichu wyłączyłby lub błędnie skonfigurował pulę. Dokładnie pusta wartość jest traktowana jak nieustawiona.

Stan współdzielony

Wewnątrzprocesowe prymitywy współbieżności (OxPHP\Shared\Counter, Map, Channel, Mutex, Once, Pool, Atomic, Flag, Registry). Przewodnik po API znajdziesz w Stan współdzielony.

Zmienna	Wartość domyślna	Opis
`SHARED_ENABLED`	`true`	Wartość logiczna — zobacz Wartości logiczne. Główny przełącznik całego podsystemu `OxPHP\Shared\*`
`SHARED_MAX_ENTRIES`	`100000`	Globalny limit łącznej liczby wszystkich wpisów Shared. Wstawienie ponad ten limit kończy się `CapacityException`
`SHARED_MAX_BYTES`	`1073741824` (1 GiB)	Globalny limit szacowanej pamięci dla wszystkich wpisów Shared
`SHARED_SOFT_LIMIT_RATIO`	`0.7`	Rozpoczyna odrzucanie pracy o najniższym priorytecie, gdy zużycie przekroczy ten ułamek `SHARED_MAX_BYTES` / `SHARED_MAX_ENTRIES`
`SHARED_METRICS_ENABLED`	`true`	Wartość logiczna. Włącza lub wyłącza ekspozycję Prometheus `oxphp_shared_*`
`SHARED_INTROSPECTION_ENABLED`	`true`	Wartość logiczna. Włącza lub wyłącza API introspekcji `/__ox_shared/*` na serwerze wewnętrznym
`SHARED_INTROSPECTION_PREVIEW_ENABLED`	`true`	Wartość logiczna. Włącza lub wyłącza podglądy wartości w odpowiedziach introspekcji (wyłącz, gdy podglądy mogłyby ujawnić dane wrażliwe)
`SHARED_CYCLE_DETECT_DEPTH`	`16`	Głębokość BFS podczas sprawdzania cykli. Zwiększ dla głębokich, prawidłowych grafów
`SHARED_CYCLE_DETECT_EDGES`	`10000`	Liczba krawędzi przechodzonych podczas sprawdzania cykli. Zwiększ dla gęstych, prawidłowych grafów
`SHARED_MAX_VALUE_SIZE`	`1048576` (1 MiB)	Limit rozmiaru pojedynczej wartości. Wstawienie większej wartości kończy się natychmiastowym błędem
`SHARED_MAX_CHANNEL_BYTES`	`67108864` (64 MiB)	Limit łącznego ładunku na kanał
`SHARED_POISON_STRICT`	`false`	Wartość logiczna. Gdy prawda, panika wewnątrz domknięcia Mutex/Once trwale zatruwa prymityw zamiast próby odzyskania w miarę możliwości
`SHARED_LOCK_DIAGNOSTICS`	`off`	Diagnostyka rywalizacji o blokady: `off`, `count` lub `trace`
`SHARED_LOCK_POLL_INTERVAL_MS`	`100`	Interwał odpytywania używany przez sampler diagnostyki blokad
`SHARED_PREVIEW_STRING_LIMIT`	`256`	Obcinanie pojedynczego łańcucha znaków w podglądach `/entry?id=…`
`SHARED_PREVIEW_ARRAY_LIMIT`	`20`	Liczba wpisów próbkowanych w podglądach `/entry?id=…`

Profilowanie

Profiler próbkujący, który emituje ślady xhprof / speedscope. Formaty wyjściowe oraz integrację z przeglądarkami śladów opisano w Profilowanie.

Zmienna	Wartość domyślna	Opis
`PROFILER_ENABLED`	`false`	Wartość logiczna — zobacz Wartości logiczne. Główny przełącznik. Wszystkie pozostałe zmienne `PROFILER_*` są mimo to parsowane przy starcie, aby literówki ujawniały się natychmiast
`PROFILER_SAMPLE_RATE`	`0.0`	Prawdopodobieństwo (0.0–1.0), że żądanie zostanie spróbkowane. Wartości spoza zakresu są przycinane
`PROFILER_INTERNAL`	`false`	Wartość logiczna. Gdy prawda, żądania do serwera wewnętrznego (`/health`, `/metrics`, endpointy wtyczek) również kwalifikują się do próbkowania
`PROFILER_AUTH_TOKEN`	(nieustawione)	Opcjonalny token bearer. Gdy ustawiony, funkcje PHP `oxphp_profiler_*` wymagają, aby żądania niosły ten token, w celu włączenia profilowania na żądanie
`PROFILER_MAX_SPANS`	`50000`	Limit spanów profilu na żądanie. Profile przekraczające ten limit są obcinane
`PROFILER_MAX_DEPTH`	`256`	Maksymalna głębokość stosu wywołań przechwytywana na próbkę. Twardy limit to `65535`
`PROFILER_OUTPUT_DIR`	`/tmp/oxphp-profiles`	Katalog na pliki profili zapisywane na dysku
`PROFILER_OUTPUT_FORMATS`	`xhprof,speedscope`	Rozdzielona przecinkami lista formatów wyjściowych zapisywanych na dysk
`PROFILER_DISK_MAX_PER_SEC`	`10`	Ograniczenie liczby plików profili zapisywanych na dysk na sekundę
`PROFILER_RETENTION_COUNT`	`100`	Maksymalna liczba plików profili przechowywanych w `PROFILER_OUTPUT_DIR`. Starsze pliki są usuwane
`PROFILER_EXPORT_URL`	(nieustawione)	Zdalny endpoint, do którego profile są wysyłane metodą POST. Gdy ustawiony, zapisy na dysk nadal następują, chyba że `PROFILER_OUTPUT_FORMATS` jest puste
`PROFILER_EXPORT_FORMAT`	`xhprof`	Format transmisji dla wysyłek `PROFILER_EXPORT_URL`
`PROFILER_EXPORT_AUTH_TOKEN`	(nieustawione)	Opcjonalny token bearer wysyłany z każdym żądaniem eksportu
`PROFILER_EXPORT_XHGUI`	(automatyczne wykrywanie)	Wartość logiczna. Wymusza opakowanie ładunku eksportu zgodne z XHGui. Nieustawione = automatyczne wykrywanie, gdy ścieżka `PROFILER_EXPORT_URL` kończy się na `/run/import` (wskazówki z hosta/query nie są dopasowywane)
`PROFILER_EXPORT_BUGGREGATOR`	(automatyczne wykrywanie)	Wartość logiczna. Wymusza kopertę Buggregator. Nieustawione = automatyczne wykrywanie, gdy ścieżka `PROFILER_EXPORT_URL` kończy się na `/api/profiler/store`. Koperta zawsze emituje xhprof, więc `PROFILER_EXPORT_FORMAT` jest dla niej ignorowane (wartość inna niż xhprof powoduje ostrzeżenie, nie jest krytyczna). Wzajemnie wykluczające się z `PROFILER_EXPORT_XHGUI` — włączenie obu to błąd startu
`PROFILER_EXPORT_APP_NAME`	(nieustawione)	`app_name` Buggregatora do grupowania projektów
`PROFILER_EXPORT_TAGS`	(nieustawione)	`tags` Buggregatora w postaci `key=value,key2=value2`; nieprawidłowy token, pusty klucz lub zduplikowany klucz to błąd startu

Przykładowe konfiguracje

Środowisko deweloperskie

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

Produkcja (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

Produkcja (tryb 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

Sprawdzanie aktywnej konfiguracji

Gdy serwer wewnętrzny działa, odpytaj endpoint /config, aby zobaczyć rozwiązaną konfigurację:

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

Serwowana odpowiedź /config usuwa kilka kluczy, które niesie wewnętrzna reprezentacja Config: ścieżki certyfikatu i klucza TLS nigdy nie są emitowane (tls_enabled wskazuje, czy TLS jest aktywny), a internal_addr oraz error_pages_dir są usuwane — to topologia wdrożenia i ścieżki w systemie plików, które pomagają atakującemu, a nie są potrzebne narzędziom zbierającym metryki.

Zobacz również

Routing — tryby routingu i zachowanie ENTRY_FILE
Kontrole stanu — endpointy serwera wewnętrznego
Metryki — dokumentacja metryk zgodnych z Prometheus
Łagodne zamknięcie — jak DRAIN_TIMEOUT_SECONDS wpływa na zamykanie
TLS — konfiguracja TLS i wymagania dotyczące certyfikatów
Ograniczanie liczby żądań — szczegóły ograniczania liczby żądań na IP
Tryb worker — architektura trwałych workerów PHP
Kompresja — szczegóły kompresji Brotli
Pliki statyczne — cache'owanie i serwowanie plików
Śledzenie rozproszone i APM — eksport OTel, automatyczna instrumentacja i SDK śledzenia dla PHP

Dokumentacja konfiguracji

Wartości logiczne

Serwer

Workery PHP

Workery statyczne a dynamiczne

Tryb worker

Przestarzałe: INDEX_FILE i WORKER_FILE

SAPI / PHP

Limity czasu

Ograniczanie liczby żądań

Bezpieczeństwo

TLS

HTTP/2

Pliki statyczne

Logowanie

Obserwowalność

OpenTelemetry

APM

Workery asynchroniczne

Stan współdzielony

Profilowanie

Przykładowe konfiguracje

Środowisko deweloperskie

Produkcja (Framework)

Produkcja (tryb worker)

TLS

Sprawdzanie aktywnej konfiguracji

Zobacz również

Przestarzałe: `INDEX_FILE` i `WORKER_FILE`