Installation

OxPHP est distribué sous forme d'image Docker, la manière la plus rapide et recommandée pour commencer à servir des applications PHP. L'image regroupe le binaire du serveur, PHP 8.4 ou 8.5 ZTS, l'extension OxPHP et toutes les dépendances d'exécution sur Alpine Linux. Les tags par défaut :0.10.0 et :latest embarquent PHP 8.5 ; récupérez PHP 8.4 avec les tags :0.10.0-php8.4, :php8.4 ou n'importe quelle variante de tag *-php8.4*.

Docker (recommandé)

Récupérez l'image officielle depuis le GitHub Container Registry :

bash
docker pull ghcr.io/oxphp/oxphp:0.10.0

L'image inclut :

  • Binaire du serveur OxPHP — le serveur HTTP asynchrone
  • Runtime PHP ZTS — 8.4 ou 8.5, selon le tag récupéré ; PHP thread-safe pour l'exécution multi-worker
  • Extension PHP OxPHP (oxphp_sapi.so) — fournit oxphp_request_id(), oxphp_server_info(), oxphp_worker() et d'autres fonctions intégrées
  • Bibliothèque passerelle (liboxphp_bridge.so) — connecte le serveur Rust au runtime PHP
  • Base Alpine Linux — empreinte d'exécution minimale
  • Aucune directive USER — l'image démarre en tant que root (comme nginx:alpine / php-fpm:alpine / frankenphp:alpine) afin de pouvoir se lier aux ports privilégiés, mais oxphp serve/run abandonne ensuite ces privilèges pour www-data par défaut avant de servir, de sorte que le trafic n'est pas traité en tant que root d'entrée de jeu. L'utilisateur www-data (UID 82, GID 82) est pré-créé et /var/www/html lui est attribué (chown) au moment de la construction. Fixez explicitement l'identité d'exécution au niveau de l'orchestrateur pour un uid spécifique ou une défense en profondeur supplémentaire :
    • docker run --user www-data ghcr.io/oxphp/oxphp:0.10.0
    • Compose : services.app.user: www-data
    • Kubernetes : securityContext.runAsUser: 82

Structure de l'image

Organisation des fichiers de l'image d'exécution :

text
/usr/local/ ├── bin/ │ └── oxphp # server binary ├── lib/ │ ├── libphp.so # PHP ZTS runtime (8.4 or 8.5, matches the image tag) │ ├── liboxphp_bridge.so # C bridge library │ └── php/extensions/no-debug-zts-<ABI>/ │ └── oxphp_sapi.so # OxPHP PHP extension ├── etc/php/ │ └── conf.d/ │ ├── custom.ini # PHP settings for OxPHP │ └── oxphp.ini # extension=oxphp_sapi.so
Note

La valeur <ABI> dépend de la version mineure de PHP. PHP 8.4 utilise 20240924, PHP 8.5 utilise un horodatage différent. Les exemples ci-dessous fixent 20240924 parce que leur ligne FROM cible php:8.4-zts-alpine3.23 — changez le FROM et vous devez aussi changer la date. Pour la dériver de façon portable au sein de la construction :

bash
php -r 'echo ini_get("extension_dir");' # /usr/local/lib/php/extensions/no-debug-zts-20240924

Utilisez $(php -r 'echo ini_get("extension_dir");') dans les commandes shell pour éviter de coder la valeur en dur.

Les trois composants d'OxPHP et leur rôle :

Composant Taille Rôle
oxphp ~8 MB Serveur HTTP, routage, plugins, métriques
liboxphp_bridge.so ~50 KB Bibliothèque passerelle partagée qui relie le serveur au runtime PHP
oxphp_sapi.so ~200 KB Fonctions PHP (oxphp_request_id(), OxPHP\Http\Request, etc.)

Chaîne de dépendances :

graph LR
  oxphp["oxphp"] --> libphp["libphp.so"]
  libphp --> deps["libxml2, libcurl, libsqlite3, libonig, ..."]
  oxphp --> bridge["liboxphp_bridge.so"]
  sapi["oxphp_sapi.so"] --> bridge

Le binaire oxphp est lié à libphp.so et liboxphp_bridge.so. L'extension PHP oxphp_sapi.so est elle aussi liée à la bibliothèque passerelle afin que l'état propre à chaque requête soit accessible depuis votre code PHP.

Dockerfile minimal

L'image de base php:8.4-zts-alpine3.23 (ou php:8.5-zts-alpine3.23) contient déjà libphp.so et toutes ses dépendances. Faites correspondre la version mineure de PHP dans votre FROM au tag OxPHP depuis lequel vous copiez. Il vous suffit de copier les trois artefacts OxPHP :

Dockerfile
FROM php:8.4-zts-alpine3.23 COPY --from=ghcr.io/oxphp/oxphp:0.10.0 /usr/local/bin/oxphp /usr/local/bin/oxphp COPY --from=ghcr.io/oxphp/oxphp:0.10.0 /usr/local/lib/liboxphp_bridge.so /usr/local/lib/ COPY --from=ghcr.io/oxphp/oxphp:0.10.0 /usr/local/lib/php/extensions/no-debug-zts-20240924/oxphp_sapi.so /usr/local/lib/php/extensions/no-debug-zts-20240924/ RUN echo "extension=oxphp_sapi.so" > /usr/local/etc/php/conf.d/oxphp.ini COPY --chown=www-data:www-data . /var/www/html/public EXPOSE 80 443 CMD ["oxphp"]

Cette approche est pratique pour le développement : PHP CLI, composer, docker-php-ext-install et xdebug sont tous disponibles. Consultez le Guide Docker pour plus de détails.

Dockerfile de production

L'image officielle OxPHP est minimale : elle n'inclut ni PHP CLI ni les outils de compilation d'extensions. Le besoin ou non d'extensions PHP supplémentaires détermine laquelle de ces deux constructions choisir.

Si votre application a besoin d'extensions supplémentaires (pdo_mysql, intl, etc.), compilez-les dans une étape distincte et copiez-les dans l'image finale :

Dockerfile
# Extension build stage FROM php:8.4-zts-alpine3.23 AS extensions RUN apk add --no-cache icu-dev postgresql-dev \ && docker-php-ext-install pdo pdo_mysql pdo_pgsql intl # Production FROM ghcr.io/oxphp/oxphp:0.10.0 # Runtime dependencies for extensions USER root RUN apk add --no-cache icu-libs libpq # Copy compiled extensions COPY --from=extensions /usr/local/lib/php/extensions/no-debug-zts-20240924/*.so /usr/local/lib/php/extensions/no-debug-zts-20240924/ # Enable extensions RUN { \ echo "extension=pdo.so"; \ echo "extension=pdo_mysql.so"; \ echo "extension=pdo_pgsql.so"; \ echo "extension=intl.so"; \ } > /usr/local/etc/php/conf.d/app-extensions.ini USER www-data COPY --chown=www-data:www-data . /var/www/html/public

Construire et exécuter :

bash
docker build -t my-app . docker run -p 80:80 my-app

Le serveur écoute sur le port 80 par défaut. La racine du document est /var/www/html/public, et les extraits ci-dessus y copient le projet directement. Pour Laravel, Symfony ou d'autres frameworks qui embarquent déjà un sous-répertoire public/, utilisez plutôt COPY --chown=www-data:www-data . /var/www/html afin que le public/ propre au framework s'aligne sur la valeur par défaut. Si votre structure diffère davantage, remplacez la racine du document par la variable d'environnement DOCUMENT_ROOT.

Compilation depuis les sources (sans PHP)

Compilez OxPHP depuis les sources avec la fonctionnalité PHP désactivée pour servir uniquement des fichiers statiques :

bash
cargo build --release --no-default-features

Le binaire se trouve dans target/release/oxphp. Il utilise un exécuteur factice qui renvoie une réponse générique pour les requêtes PHP tout en servant normalement les fichiers statiques. Ce mode est utile pour tester le serveur sans qu'un runtime PHP soit présent.

Compilation depuis les sources (avec PHP)

Compiler OxPHP avec la prise en charge complète de PHP requiert que la bibliothèque passerelle et l'extension PHP soient d'abord compilées et installées.

Prérequis

  • Chaîne d'outils Rust (1.91.1 ou ultérieure)
  • PHP 8.4 ou 8.5 avec ZTS (Zend Thread Safety) activé
  • Compilateur C (gcc ou clang)
  • phpize et les en-têtes de développement de PHP

Étapes de compilation

  1. Compilez et installez la bibliothèque passerelle.

    bash
    cd ext/bridge make && sudo make install

  2. Compilez et installez l'extension PHP.

    bash
    cd ../ phpize && ./configure --enable-oxphp-sapi && make && sudo make install

  3. Compilez OxPHP. Les fonctionnalités par défaut incluent php.

    bash
    cargo build --release

Le binaire a besoin des bibliothèques partagées dans le chemin de recherche des bibliothèques à l'exécution :

bash
export LD_LIBRARY_PATH=/usr/local/lib ./target/release/oxphp
Note

Lors d'un déploiement sur Alpine Linux, compilez à l'intérieur de la même image php:{8.4,8.5}-zts-alpine que celle utilisée pour le runtime PHP — faites correspondre la version mineure de l'image OxPHP que vous livrez. Mélanger des constructions glibc et musl provoque des erreurs à l'exécution. L'image Docker officielle gère cela correctement.

Vérification de l'installation

Après le démarrage d'OxPHP, une sortie de log JSON structurée confirme que le serveur fonctionne :

text
{"timestamp":"...","level":"INFO","message":"OxPHP HTTP server starting","listen_addr":"0.0.0.0:80",...} {"timestamp":"...","level":"INFO","message":"Server listening","addr":"0.0.0.0:80"}

Testez que le serveur répond :

bash
curl http://localhost/

Si vous avez activé le serveur interne avec INTERNAL_ADDR, vérifiez l'endpoint de contrôle de santé :

bash
curl http://localhost:9090/health

Un serveur en bonne santé renvoie 200 avec un statut JSON. Un serveur dégradé renvoie 503.

Et ensuite

  • Démarrage rapide — créez un projet, exécutez OxPHP avec Docker Compose et effectuez votre première requête
  • Guide Docker — Dockerfiles pour le développement et la production, configuration de Compose et montages de volumes
  • Configuration — référence complète des variables d'environnement
Une erreur ? Signalez-la →