Dokumentacja OxPHP

OxPHP to wydajny serwer aplikacji PHP, który zastępuje nginx + PHP-FPM pojedynczym plikiem binarnym — w komplecie wbudowany TLS, kompresja Brotli, ograniczanie liczby żądań, kontrole stanu, metryki Prometheus, strumieniowanie SSE oraz trwały tryb worker.

Dlaczego OxPHP

Typowa aplikacja PHP na produkcji to kilka kontenerów: nginx, PHP-FPM, czasem osobne proxy TLS i eksporter metryk. Konfiguracja jest rozproszona pomiędzy nimi, a doprowadzenie do tego, by wszystko działało razem, wymaga utrzymywania spójności ustawień gniazd, limitów czasu i ścieżek. OxPHP zastępuje cały ten stos jednym kontenerem. W środku jest jeden proces, który przyjmuje połączenia HTTP, wykonuje PHP i serwuje pliki statyczne.

Serwer działa od razu po uruchomieniu, z rozsądnymi wartościami domyślnymi. Dostrajanie odbywa się poprzez zmienne środowiskowe: TLS włącza się dwiema zmiennymi (TLS_CERT, TLS_KEY), ograniczanie liczby żądań jedną (RATE_LIMIT), a kompresja Brotli jest włączona domyślnie. Nie trzeba edytować konfiguracji nginx ani budować osobnych modułów.

Na dedykowanym porcie wewnętrznym dostępne są kontrole stanu (/health), metryki Prometheus (/metrics) oraz migawka konfiguracji (/config). To wystarcza dla sond liveness/readiness w Kubernetesie oraz do podłączenia Grafany, bez dodatkowych kontenerów sidecar.

Logi mają postać ustrukturyzowanego JSON-a: metoda, ścieżka, status, czas odpowiedzi oraz ID żądania w każdej linii. Łatwo je parsować w Loki, Elasticsearchu czy dowolnym innym narzędziu, bez dodatkowych wzorców grok.

Aby wypróbować tryb worker, w którym proces PHP nie jest tworzony na nowo przy każdym żądaniu, ustaw WORKER_MODE_ENABLED=true i ENTRY_FILE=worker.php. Framework inicjalizuje się raz, a następnie obsługuje tysiące żądań bez przeładowywania. Aby wrócić do klasycznego trybu, usuń tę zmienną.

OxPHP zawiera też możliwości, które zwykle wymagają osobnych narzędzi lub bibliotek firm trzecich:

Pierwsze kroki

  • Szybki start — zbuduj i uruchom swoją pierwszą aplikację OxPHP w niecałe 5 minut
  • Instalacja — wymagania systemowe i opcje instalacji
  • Przewodnik po Dockerze — pliki Dockerfile, konfiguracja Compose, wolumeny i wzorce wdrożeniowe
  • Interfejs wiersza poleceń — składnia polecenia oxphp: serve, run pojedynczego skryptu PHP, config oraz zrzucanie uprawnień przez --user

Operacje

  • Dokumentacja konfiguracji — kompletna lista zmiennych środowiskowych z wartościami domyślnymi i opisami
  • Kontrole stanu — endpointy serwera wewnętrznego /health, /metrics i /config
  • Metryki — dokumentacja metryk zgodnych z Prometheusem
  • Łagodne zamknięcie — zachowanie przy opróżnianiu, limity czasu i sekwencja zamykania

Funkcje

  • Routing — trzy tryby routingu: tradycyjne mapowanie plików, frameworkowy front-controller oraz przekierowanie awaryjne SPA. Tryb worker to ortogonalny przełącznik modelu wykonania i działa na wierzchu dowolnego trybu routingu
  • Pliki statyczne — cache plików, wykrywanie typów MIME, nagłówki ETag/Last-Modified oraz strumieniowanie
  • Tryb worker — trwałe procesy PHP z automatycznym miękkim resetem między żądaniami
  • Multipleksowanie Fiberów — obsługa setek współbieżnych żądań na wątek workera dzięki kooperacyjnej wielozadaniowości
  • Kompresja — kompresja Brotli dla odpowiedzi tekstowych
  • TLS — wbudowana terminacja TLS z konfiguracją certyfikatu i klucza
  • Ograniczanie liczby żądań — ograniczanie liczby żądań per-IP z konfigurowalnymi oknami i limitami
  • Limity czasu — limity czasu odczytu nagłówków oraz żądania
  • Rejestrowanie dostępu — ustrukturyzowane logi dostępu w formacie JSON z ID żądania, metodą, ścieżką, statusem i czasem trwania
  • ID żądań — automatyczne generowanie i przekazywanie nagłówka X-Request-ID
  • Strony błędów — własne strony błędów w HTML dla dowolnego kodu statusu HTTP
  • SSE — strumieniowanie Server-Sent Events z PHP w czasie rzeczywistym
  • Wczesna odpowiedź — wyślij odpowiedź natychmiast i kontynuuj przetwarzanie w tle
  • Asynchroniczne promisy — uruchamiaj domknięcia PHP w wątkach w tle i oczekuj na wyniki
  • Dekoratory — przechwytywanie wywołań funkcji i metod za pomocą atrybutów PHP 8
  • Śledzenie rozproszone i APM — W3C Trace Context, OpenTelemetry, automatyczna instrumentacja oraz SDK do śledzenia w PHP
  • Serwer wewnętrzny — dedykowany port dla kontroli stanu, metryk Prometheus oraz podglądu bieżącej konfiguracji

Bezpieczeństwo

  • Blokowanie ścieżek z kropką — automatyczne blokowanie ukrytych plików i katalogów (.env, .git/, .htaccess)
  • Zaufane proxy — wydobywanie prawdziwego IP klienta z nagłówków Forwarded (RFC 7239) oraz X-Forwarded-* z zaufaniem opartym na CIDR
  • Lista blokowania wykonywania PHP — blokowanie wykonywania .php w zapisywalnych ścieżkach publicznych (np. /uploads/** lub konkretnych starszych skryptów), aby udaremnić ataki z wgranymi shellami na starsze aplikacje
  • Dozwolone ścieżki dowiązań symbolicznych — opcjonalna lista dozwolonych celów dowiązań symbolicznych poza DOCUMENT_ROOT; obsługuje storage:link w stylu Laravela oraz współdzielone wolumeny zasobów bez osłabiania domyślnej ochrony przed ucieczką przez dowiązania symboliczne

PHP

  • API żądania HTTP — obiektowy dostęp do żądania przez oxphp_http_request(): parametry zapytania, sparsowane ciało, nagłówki, ciasteczka, przesłane pliki i więcej
  • Funkcje — wbudowane funkcje PHP dostarczane przez OxPHP (oxphp_worker(), oxphp_request_id(), oxphp_server_info() i więcej)
  • Superglobalne — jak wypełniane są $_SERVER, $_GET, $_POST, $_COOKIE, $_FILES oraz php://input
  • OPcache i JIT — konfiguracja OPcache oraz ustawienia kompilacji JIT

Stan współdzielony

Współbieżne prymitywy obejmujące cały proces, dzięki którym workery mogą koordynować zmienny stan bez Redisa, Memcached czy APCu — wszystko żyje wewnątrz procesu, więc koszt pojedynczej operacji liczony jest w mikrosekundach, a nie w rundach sieciowych.

  • Wprowadzenie — model rejestru, cykl życia uchwytu oraz kiedy sięgać po stan współdzielony
  • Rejestr — rejestr obejmujący cały proces, cykl życia wpisu oraz introspekcja
  • Counter — atomowy akumulator int64 (get, set, add, compareAndSet)
  • Atomic — atomowy int64 z jawną kontrolą uporządkowania pamięci
  • Flag — atomowa wartość logiczna dla jednorazowych przejść
  • Once — kontener uruchamiany raz z fabryką bezpieczną przy reentrancji
  • Mutex — zatruwalny mutex nad przechowywaną wartością z wykrywaniem zakleszczeń
  • Channel — ograniczona kolejka MPMC świadoma Fiberów
  • Map — współbieżny magazyn kluczowany stringami z dostępem wsadowym
  • Pool — ograniczona pula obiektów z powinowactwem per-wątek
  • Konwencje nazewnicze — ściągawka nazewnictwa metod w całej rodzinie Shared\*
  • Obserwowalność — liczniki Prometheus oraz endpointy introspekcji JSON
  • Migracja do zewnętrznego magazynu — kiedy i jak przejść na Redisa lub APCu

Architektura

  • Przegląd architektury — jak działa OxPHP: asynchroniczna obsługa HTTP, pula workerów PHP, przepływ żądania oraz gwarancje bezpieczeństwa

Przykłady

Kompletne przepisy na uruchamianie popularnych aplikacji PHP na OxPHP — każdy to gotowy projekt Docker Compose z plikiem Dockerfile, docker-compose.yml, krokami instalacji oraz uwagami specyficznymi dla OxPHP, których standardowa dokumentacja (nginx + PHP-FPM) nie obejmuje.

Znalazłeś błąd? Zgłoś go →