GitHub

Documentation OxPHP

OxPHP est un serveur d'applications PHP haute performance qui remplace nginx + PHP-FPM par un processus unique — TLS, compression, limitation de débit, contrôles de santé, métriques Prometheus, streaming SSE et mode worker persistant inclus.

Pourquoi OxPHP

Une application PHP typique en production, c'est plusieurs conteneurs : nginx, PHP-FPM, parfois un proxy TLS distinct et un exportateur de métriques. La configuration est éparpillée entre eux, et faire fonctionner l'ensemble revient à maintenir en cohérence les réglages de socket, les délais d'expiration et les chemins. OxPHP remplace toute la pile par un conteneur unique. À l'intérieur, un seul processus accepte les connexions HTTP, exécute PHP et sert les fichiers statiques.

Le serveur fonctionne d'emblée avec des valeurs par défaut sensées. Le réglage fin se fait via des variables d'environnement : TLS s'active avec deux variables (TLS_CERT, TLS_KEY), la limitation de débit avec une seule (RATE_LIMIT), et la compression est activée par défaut. Nul besoin d'éditer des configs nginx ou de compiler des modules séparés.

Sur un port interne dédié, les contrôles de santé (/health, plus un endpoint dédié pour chaque type de sonde Kubernetes), les métriques Prometheus (/metrics) et un instantané de la configuration (/config) sont disponibles. Cela suffit pour les sondes liveness/readiness de Kubernetes et pour brancher Grafana, sans conteneurs sidecar supplémentaires.

Les journaux sont au format JSON structuré : méthode, chemin, statut, temps de réponse et ID de requête sur chaque ligne. Ils s'analysent facilement dans Loki, Elasticsearch ou tout autre outil, sans patterns grok additionnels.

Pour essayer le mode worker, dans lequel l'état PHP n'est pas reconstruit à chaque requête, définissez WORKER_MODE_ENABLED=true et ENTRY_FILE=worker.php. Le framework s'initialise une seule fois, puis traite des milliers de requêtes sans rechargement. Pour revenir au mode classique, supprimez la variable.

OxPHP inclut également des fonctionnalités qui exigent habituellement des outils dédiés ou des bibliothèques tierces :

  • Service de fichiers statiques — mise en cache en mémoire, ETag/Last-Modified, types MIME automatiques
  • Trois modes de routage — basé sur les fichiers, framework et SPA, choisis par ENTRY_FILE ; le mode worker persistant les remplace par son propre routage, qui confie à un script d'entrée .php toute requête non servie comme fichier statique
  • Réponse anticipée — envoyez la réponse immédiatement et poursuivez le traitement en arrière-plan
  • Mode worker — workers PHP persistants avec multiplexage par Fibers
  • Streaming SSE — Server-Sent Events en temps réel depuis PHP
  • Promesses asynchrones — exécution en arrière-plan de closures PHP sans bloquer le worker
  • État partagé — primitives concurrentes à l'échelle du processus (Counter, Flag, Once, Mutex, Channel, Map, Pool) pour que les workers se coordonnent sans Redis ni APCu
  • Décorateurs — interception d'appels via les attributs PHP 8
  • Traçage distribué & APM — W3C Trace Context, OpenTelemetry, instrumentation automatique des appels base de données/HTTP/cache/fichier, et un SDK de traçage PHP

Prise en main

  • Démarrage rapide — compilez et lancez votre première application OxPHP en moins de 5 minutes
  • Installation — prérequis système et options d'installation
  • Guide Docker — Dockerfiles, configuration Compose, volumes et schémas de déploiement
  • Interface en ligne de commande — la grammaire de la commande oxphp : serve, run d'un seul script PHP, config et l'abandon de privilèges --user
  • Migration — passer de nginx + PHP-FPM, FrankenPHP ou RoadRunner : modes de routage, correspondance de la configuration, différences de comportement et ce qui ne se transpose pas

Exploitation

Fonctionnalités

  • Routage — trois modes de routage : mappage de fichiers traditionnel, contrôleur frontal de framework et repli SPA. Le mode worker est un mode de routage à part entière qui prend leur place : il exige un ENTRY_FILE .php et reçoit toute requête non servie comme fichier statique
  • Fichiers statiques — cache de fichiers, détection MIME, en-têtes ETag/Last-Modified et streaming
  • Mode worker — workers PHP persistants avec réinitialisation douce automatique entre les requêtes
  • Multiplexage par Fibers — traitez des centaines de requêtes concurrentes par thread worker grâce au multitâche coopératif
  • Compression — Brotli, Zstandard et gzip pour les réponses textuelles, négociés selon chaque client
  • TLS — terminaison TLS intégrée avec configuration du certificat et de la clé
  • Limitation de débit — limitation de débit par IP avec fenêtres et limites configurables
  • Délais d'expiration — délais de lecture des en-têtes et de traitement des requêtes
  • Journalisation des accès — journaux d'accès JSON structurés avec ID de requête, méthode, chemin, statut et durée
  • ID de requête — génération et propagation automatiques de X-Request-ID
  • Pages d'erreur — pages d'erreur HTML personnalisées pour n'importe quel code de statut HTTP
  • SSE — streaming de Server-Sent Events en temps réel depuis PHP
  • Réponse anticipée — envoyez la réponse immédiatement et poursuivez le traitement en arrière-plan
  • Promesses asynchrones — exécutez des closures PHP sur des threads en arrière-plan et attendez les résultats
  • Décorateurs — interceptez les appels de fonctions et de méthodes avec les attributs PHP 8
  • Traçage distribué & APM — W3C Trace Context, OpenTelemetry, auto-instrumentation et SDK de traçage PHP
  • Profilage — profileur intégré par requête : déclencheurs d'activation, le SDK PHP et les attributs, formats d'export et routes internes
  • Serveur interne — port dédié pour les contrôles de santé, les métriques Prometheus et la configuration en direct

Sécurité

  • Blocage des chemins pointés — blocage automatique des fichiers et répertoires cachés (.env, .git/, .htaccess)
  • Proxys de confiance — extraction de l'IP client réelle depuis les en-têtes Forwarded (RFC 7239), X-Forwarded-* et, derrière Cloudflare, CF-Connecting-IP, avec confiance basée sur CIDR
  • Liste de refus d'exécution PHP — bloquez l'exécution de .php sur les chemins publics accessibles en écriture (par exemple /uploads/**, ou des scripts hérités spécifiques) pour contrer les attaques par shell téléversé sur les applications héritées
  • Règles de refus de chemins — un fichier .oxphpdeny de style gitignore dans DOCUMENT_ROOT empêche de servir vendor/, les dumps, les sauvegardes et d'autres fichiers, ou confie leurs requêtes à l'application
  • Chemins autorisés pour les liens symboliques — liste d'autorisation optionnelle pour les cibles de liens symboliques hors de DOCUMENT_ROOT ; prend en charge le storage:link façon Laravel et les volumes d'assets partagés sans affaiblir la protection par défaut contre l'évasion par lien symbolique

PHP

  • API de requête HTTP — accès orienté objet à la requête via oxphp_http_request() : paramètres de requête, corps analysé, en-têtes, cookies, fichiers téléversés, et plus encore
  • Fonctions — fonctions PHP intégrées fournies par OxPHP (oxphp_worker(), oxphp_request_id(), oxphp_server_info(), et plus encore)
  • Superglobales — comment $_SERVER, $_GET, $_POST, $_COOKIE, $_FILES et php://input sont peuplés
  • Classe Worker — le handle d'exécution OxPHP\Server\Worker : introspection du worker, point d'entrée du worker et métriques par thread
  • OPcache et JIT — configuration d'OPcache et paramètres de compilation JIT

État partagé

Des primitives concurrentes à l'échelle du processus pour que les workers coordonnent un état mutable sans Redis, Memcached ni APCu — tout réside en mémoire, si bien que le coût par opération se compte en microsecondes plutôt qu'en allers-retours réseau.

  • Vue d'ensemble — modèle de registre, cycle de vie des handles, et quand recourir à l'état partagé
  • Registre — le registre à l'échelle du processus, cycle de vie des entrées et introspection
  • Counter — accumulateur atomique int64 (get, set, add, compareAndSet)
  • Atomic — int64 atomique avec contrôle explicite de l'ordonnancement mémoire
  • Flag — booléen atomique pour les transitions à usage unique
  • Once — conteneur à exécution unique avec fabrique réentrante
  • Mutex — mutex sur une valeur stockée, avec détection d'interblocage
  • Channel — file MPMC bornée et compatible avec les Fibers
  • Map — store concurrent à clés chaîne avec accès par lots
  • Pool — pool d'objets borné avec affinité par thread
  • Conventions de nommage — aide-mémoire du nommage des méthodes dans la famille Shared\*
  • Observabilité — compteurs Prometheus et endpoints d'introspection JSON
  • Migration vers un store externe — quand et comment passer à Redis ou APCu

Architecture

Intégrations

  • Serveur MCP — connecter la documentation OxPHP à votre agent de codage via le Model Context Protocol

Exemples

Des recettes de bout en bout pour faire tourner des applications PHP populaires sur OxPHP — chacune un projet Docker Compose complet avec un Dockerfile, un docker-compose.yml, les étapes d'installation et les notes propres à OxPHP que la documentation standard (nginx + PHP-FPM) ne couvre pas.

Une erreur ? Signalez-la →