Documentation OxPHP

OxPHP est un serveur d'applications PHP haute performance qui remplace nginx + PHP-FPM par un binaire unique — TLS, compression Brotli, 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 Brotli 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), 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 le processus PHP n'est pas recréé à 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 :

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

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 basculement orthogonal du modèle d'exécution et s'applique par-dessus n'importe quel mode de routage
  • Fichiers statiques — cache de fichiers, détection MIME, en-têtes ETag/Last-Modified et streaming
  • Mode worker — processus 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 — compression Brotli pour les réponses textuelles
  • 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
  • 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) et X-Forwarded-* 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
  • 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
  • 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 à empoisonnement 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

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 →