Interface en ligne de commande

Le binaire oxphp a trois rôles : servir un serveur HTTP, exécuter un unique script PHP jusqu'à son terme, et fournir des utilitaires de configuration. Un oxphp nu, sans argument, équivaut à un serve implicite, si bien que le CMD ["oxphp"] de l'image publiée continue de démarrer le serveur sans changement.

text
USAGE: oxphp [OPTIONS] oxphp <COMMAND> [OPTIONS] oxphp serve [--user=<name|uid[:gid]>] oxphp run [-d key=value]... [--user=<spec>] <script.php> [args]... oxphp [-d key=value]... [--user=<spec>] <script.php> [args]... OPTIONS: -h, --help Print this help and exit -v, --version Print version information and exit COMMANDS: serve Start the HTTP server (default; same as bare 'oxphp') run Execute a single PHP script under CLI semantics and exit config Configuration utilities (see 'oxphp config --help')

Le rôle est déterminé par un mot-clé. Les jetons exacts serve, run et config sélectionnent une sous-commande ; tout autre premier argument positionnel est traité comme un chemin de script, si bien que oxphp ./bin/migrate.php est un raccourci pour oxphp run ./bin/migrate.php. Il n'y a aucune heuristique sur l'extension : PHP s'exécute d'après le contenu du fichier, donc un script sans extension s'exécute lui aussi. Un fichier absent est signalé par le système de fichiers, exactement comme avec php.

oxphp serve

Démarre le serveur d'applications HTTP, le rôle par défaut. oxphp et oxphp serve sont équivalents. La configuration se fait via des variables d'environnement ; serve lui-même n'accepte que --user.

bash
oxphp # implicit serve — best-effort drop to www-data oxphp serve # explicit — same default oxphp serve --user=appuser # drop to a specific user (fail-fast) oxphp serve --user=root # opt out: keep running as root

Par défaut, sans --user, serve effectue un abandon de privilèges au mieux vers www-data. Démarré en tant que root avec un compte www-data présent (comme dans l'image officielle), il lie les listeners en tant que root puis abandonne définitivement ses privilèges vers www-data avant qu'aucun trafic ne soit servi. Démarré en tant que non-root, il conserve l'utilisateur courant ; démarré en tant que root sur un hôte dépourvu de compte www-data, il enregistre un avertissement et poursuit en tant que root. Le comportement par défaut n'interrompt jamais le démarrage.

--user=<spec> remplace la cible et fonctionne en fail-fast : il lie les listeners en tant que root, puis abandonne définitivement ses privilèges vers cet utilisateur, et se termine sur une erreur s'il n'a pas été démarré en tant que root. Passez --user=root pour conserver délibérément root. Voir Exécuter en non-root sur le port 80 pour le schéma complet, la grammaire de <spec> et la liste de vérification des permissions de fichiers.

oxphp run

oxphp run <script.php> [args…] exécute un unique fichier PHP jusqu'à son terme et se termine avec le code de sortie du script lui-même. Il s'exécute sur le thread principal : il n'y a pas de listener, pas de pool de workers et pas de file d'attente de requêtes. PHP_SAPI === 'cli', et phpinfo() affiche du texte plutôt que du HTML, à l'image du php CLI standard.

bash
oxphp run migrate.php oxphp run bin/console.php cache:clear oxphp run -d memory_limit=512M import.php data.csv

C'est le rôle à utiliser pour les migrations, les tâches cron, les consommateurs de files d'attente et les commandes de type artisan/console, dans la même image que celle qui sert votre application, sans deuxième installation de PHP.

L'intégralité du moteur OxPHP reste disponible sous le script : les Fibers (oxphp_sleep()) et l'état partagé (OxPHP\Shared\*) fonctionnent d'emblée. Les promesses asynchrones (oxphp_async()) fonctionnent lorsque ASYNC_WORKERS est supérieur à 0 ; l'invocation par défaut ne démarre aucun pool asynchrone, et donc aucun runtime d'arrière-plan.

$argv et $argc sont renseignés ($argv[0] est le chemin du script), et STDIN / STDOUT / STDERR sont définis, si bien que les points d'entrée de style Composer ou Symfony Console s'exécutent sans modification.

Le chemin du script fait office de séparateur

Chaque jeton situé après le chemin du script est transmis à PHP tel quel, y compris ceux préfixés par --, donc pour les arguments ordinaires vous n'avez pas besoin d'un -- explicite. Les options destinées à oxphp lui-même (-d, --user) doivent venir avant le chemin du script ; tout ce qui vient après appartient au script.

bash
oxphp run console.php migrate --force --pretend # ▲ script └──────────────┬──────────┘ # $argv[1..], passed to PHP verbatim (oxphp parses nothing here)

Ainsi, oxphp run console.php --force donne au script --force dans $argv, tandis que oxphp run --force console.php est une erreur : --force précède le chemin du script, là où oxphp n'accepte que -d / --user / --help.

Le marqueur de fin d'options --

oxphp respecte le marqueur standard de fin d'options --, et il n'a d'importance qu'à un seul endroit : avant le chemin du script, lorsque le chemin du script commence lui-même par un tiret. -- arrête l'analyse des options de sorte que le jeton suivant soit pris comme chemin du script, et oxphp le consomme ; il n'est pas transmis à PHP.

bash
oxphp run -- -odd-name.php # runs the script "-odd-name.php" oxphp -- -odd-name.php # same, implicit form oxphp run -odd-name.php # error: parsed as options → "unexpected argument to 'run': -o"

Après le chemin du script, il ne reste plus aucune option à terminer, donc un -- à cet endroit est une donnée ordinaire, transmise à PHP littéralement, exactement comme avec php :

bash
oxphp run app.php -- --raw # $argv = ["app.php", "--", "--raw"]

Scripts avec shebang

Une ligne #! en tête est ignorée avant la compilation, si bien qu'un script exécutable et sans extension muni d'un shebang oxphp s'exécute directement :

greet
#!/usr/bin/env oxphp <?php echo "hello from a shebang script\n";
bash
chmod +x ./greet ./greet

Surcharges d'ini avec -d

-d key[=value] définit une directive php.ini pour cette exécution. Elle est répétable, et un -d key seul fixe la valeur à "1". Ces surcharges sont appliquées avant le démarrage des modules, elles l'emportent donc sur php.ini pour tout type de directive, y compris les directives PHP_INI_SYSTEM / PHP_INI_PERDIR (opcache.*, register_argc_argv, …) qu'un ini_set() à l'exécution ne peut pas modifier.

bash
oxphp run -d memory_limit=1G -d display_errors=1 report.php

Ini par défaut pour run

Le rôle run applique des valeurs par défaut orientées CLI avant vos surcharges -d et php.ini :

Directive Par défaut Pourquoi
max_execution_time 0 Une tâche ponctuelle (migration, importateur, démon) ne doit pas être interrompue par SIGALRM.
max_input_time -1 Aucun délai d'analyse des entrées pour la CLI.
display_errors stderr Les erreurs vont vers la sortie d'erreur standard, pas vers la sortie standard.
html_errors 0 Erreurs en texte brut pour un terminal.
output_buffering 0 La sortie est écrite au fur et à mesure de sa production.
implicit_flush 1 Chaque écriture est vidée immédiatement.
register_argc_argv 1 $argv / $argc sont disponibles.
Note

Les superglobales sont toujours activées pour run : un script ponctuel a besoin de $argv, $_SERVER et $_ENV. Cela reste vrai quel que soit le réglage SUPERGLOBALS_ENABLED qui s'applique au serveur HTTP.

Codes de sortie

Code Signification
propre au script exit($code) / die($code), ou 0 en cas de fin sans incident.
255 Erreur fatale, exception non interceptée ou erreur d'analyse.
1 Le chemin du script n'a pas pu être ouvert (oxphp: Could not open input file: <path>).
2 Un argument -d invalide.

Le cas du fichier impossible à ouvrir est vérifié avant le démarrage du moteur, si bien qu'un script manquant ou illisible échoue immédiatement avec le message de style php au lieu de démarrer le moteur pour qu'il meure sur une erreur de compilation.

--user avec run

run suit le même comportement par défaut que serve : sans --user, il effectue un abandon de privilèges au mieux vers www-data avant l'exécution du script (ignoré silencieusement lorsque le processus est déjà non-root). oxphp run --user=<spec> <script.php> remplace la cible, de sorte qu'une tâche ponctuelle démarrée en tant que root peut s'exécuter sous un utilisateur non privilégié spécifique ; --user=root conserve root. La grammaire de <spec> et les mécanismes d'abandon de privilèges sont identiques à ceux de serve --user ; un --user explicite alors que le processus est démarré en non-root constitue une erreur bloquante.

oxphp config

Utilitaires de configuration. --check valide la configuration par variables d'environnement et signale les problèmes sans démarrer le serveur.

bash
oxphp config --check
text
config: OK

La vérification ne porte que sur la cohérence du système de fichiers : existence des chemins et nature fichier/répertoire (DOCUMENT_ROOT, ENTRY_FILE, TLS_CERT, TLS_KEY, ERROR_PAGES_DIR, …). Le runtime PHP, la poignée de main TLS et la liaison réseau sont hors de son champ. En cas d'échec, il se termine avec un code non nul et affiche config: INVALID, une ligne par problème.

Tip

Comme oxphp config --check se termine avec un code non nul en cas de configuration invalide, il fait office de garde-fou avant démarrage dans un entrypoint ou une tâche CI.

--help et --version

bash
oxphp --help # full usage oxphp config --help # config subcommand usage oxphp --version # version and the feature flags compiled into this binary

oxphp --version indique les fonctionnalités activées de la version compilée (par exemple php, plugin-apm, plugin-async), ce qui est le moyen le plus rapide de confirmer si une image a été construite avec l'APM, l'asynchrone ou d'autres plugins optionnels.

Étapes suivantes

Une erreur ? Signalez-la →