Démarrage rapide

L'image officielle OxPHP regroupe le serveur, PHP, l'extension OxPHP et l'ensemble des dépendances d'exécution, si bien que vous pouvez passer d'un répertoire vide à une application qui tourne en quelques commandes.

Une seule commande

Si vous disposez déjà d'un projet PHP avec un répertoire public/ :

bash
docker run -p 80:80 -v .:/var/www/html ghcr.io/oxphp/oxphp:0.10.0

Ouvrez http://localhost/. Votre application tourne.

Pour activer le serveur interne (santé, métriques, configuration) :

bash
docker run -p 80:80 -p 9090:9090 -e INTERNAL_ADDR=0.0.0.0:9090 -v .:/var/www/html ghcr.io/oxphp/oxphp:0.10.0

Installation pas à pas avec Docker Compose

Un guide plus détaillé, d'un répertoire vide jusqu'à une application PHP fonctionnelle avec contrôles de santé et journalisation structurée.

  1. Créez le répertoire du projet.

    bash
    mkdir my-oxphp-app && cd my-oxphp-app

  2. Créez un Dockerfile.

    Dockerfile
    FROM ghcr.io/oxphp/oxphp:0.10.0 COPY --chown=www-data:www-data . /var/www/html

    L'image officielle inclut le binaire du serveur, PHP 8.4 ou 8.5 ZTS (8.5 par défaut ; récupérez la 8.4 avec :0.10.0-php8.4 ou n'importe quel tag *-php8.4*), l'extension PHP OxPHP et toutes les dépendances d'exécution.

  3. Ajoutez un compose.yaml.

    compose.yaml
    services: oxphp: build: . ports: - "80:80" - "9090:9090" environment: - LISTEN_ADDR=0.0.0.0:80 - DOCUMENT_ROOT=/var/www/html/public - INTERNAL_ADDR=0.0.0.0:9090 - LOG_LEVEL=info - ACCESS_LOG=all

    Le port 80 sert votre application. Le port 9090 expose le serveur interne pour les contrôles de santé, les métriques Prometheus et l'instantané de la configuration active.

  4. Créez une application PHP.

    bash
    mkdir -p public

    Créez public/index.php :

    public/index.php
    <?php $requestId = oxphp_request_id(); $info = oxphp_server_info(); echo "<h1>OxPHP</h1>\n"; echo "<p>Request ID: {$requestId}</p>\n"; echo "<p>Worker: {$info['worker_id']}</p>\n"; echo "<p>SAPI: " . php_sapi_name() . "</p>\n"; echo "<p>Version: {$info['version']}</p>\n"; echo "<p>Time: " . date('c') . "</p>\n";

    oxphp_request_id() renvoie l'ID unique attribué à chaque requête. oxphp_server_info() renvoie des détails sur le serveur en cours d'exécution, notamment version, worker_id, request_time et worker_mode.

  5. Construisez et démarrez.

    bash
    docker compose up -d --build

  6. Testez votre application.

    bash
    curl http://localhost/

    Sortie attendue :

    html
    <h1>OxPHP</h1> <p>Request ID: 67a4b3c11a2b00000001</p> <p>Worker: 0</p> <p>SAPI: cli-server</p> <p>Version: 0.10.0</p> <p>Time: 2026-03-23T12:00:00+00:00</p>

    Chaque requête reçoit un ID unique. L'ID du worker indique quel thread worker PHP l'a traitée.

  7. Vérifiez les endpoints internes.

    bash
    # Health check — 200 when healthy, 503 when degraded curl http://localhost:9090/health # Prometheus-compatible metrics curl http://localhost:9090/metrics # Active configuration (TLS paths redacted) curl http://localhost:9090/config

  8. Consultez les journaux.

    bash
    docker compose logs -f oxphp

    Comme ACCESS_LOG=all est défini, chaque requête apparaît sous forme d'une ligne de journal JSON structurée avec la méthode, le chemin, le statut, le temps de réponse et l'ID de requête.

Tip

Si votre application a besoin d'extensions PHP personnalisées (pdo_pgsql, intl, xdebug, etc.), consultez examples/dockerfile/Dockerfile dans le dépôt. C'est un Dockerfile multi-étapes prêt à l'emploi avec des cibles dev et prod distinctes.

Pourquoi `php_sapi_name()` renvoie-t-il `cli-server` au lieu de `oxphp` ?

OxPHP s'enregistre délibérément sous l'un des noms de SAPI que reconnaît OPcache. OPcache se désactive pour les SAPI inconnus ; sans ce renommage, l'exécution de PHP contournerait entièrement la couche OPcache et s'exécuterait plusieurs fois plus lentement. En contrepartie, php_sapi_name() ne peut pas servir à détecter OxPHP — utilisez plutôt function_exists('oxphp_request_id') ou OxPHP\Http\Request::current().

Et ensuite

  • Guide Docker — Dockerfiles de développement et de production, configuration de Compose, montages d'ini PHP et mise en place des contrôles de santé
  • Configuration — référence complète des variables d'environnement
  • Routage — modes de routage Traditional, Framework, SPA et Worker
  • Mode worker — processus PHP persistants qui s'initialisent une fois et traitent plusieurs requêtes
  • Fonctions PHP — toutes les fonctions PHP intégrées d'OxPHP
Une erreur ? Signalez-la →