Інтерфейс командного рядка
Бінарник oxphp має три ролі: serve запускає HTTP-сервер, run виконує окремий PHP-скрипт до завершення, а config надає утиліти для конфігурації. Виклик oxphp без аргументів неявно означає serve, тож CMD ["oxphp"] в опублікованому образі й надалі запускає сервер без жодних змін.
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')Роль визначається ключовим словом. Точні токени serve, run і config обирають підкоманду; будь-який інший перший позиційний аргумент вважається шляхом до скрипта, тож oxphp ./bin/migrate.php є скороченням для oxphp run ./bin/migrate.php. Жодної евристики за розширенням немає: PHP виконує файл за його вмістом, тому скрипт без розширення теж запуститься. Про відсутній файл повідомляє файлова система — точнісінько як у php.
oxphp serve
Запускає HTTP-сервер застосунків; це роль за замовчуванням. oxphp і oxphp serve рівнозначні. Конфігурація задається через змінні середовища; сама команда serve приймає лише --user.
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За замовчуванням, без --user, serve за можливості (best-effort) скидає привілеї до www-data. Якщо сервер запущено від root і обліковий запис www-data існує (як в офіційному образі), він привʼязує слухачі від root, а потім остаточно переходить до www-data, перш ніж обслужити будь-який трафік. Запущений не від root, він залишається під поточним користувачем; запущений від root на хості без облікового запису www-data, він записує попередження в журнал і продовжує працювати від root. Поведінка за замовчуванням ніколи не перериває запуск.
--user=<spec> перевизначає цільового користувача й працює за принципом fail-fast: привʼязка виконується від root, потім привілеї остаточно скидаються до вказаного користувача, а якщо процес запущено не від root, він завершується з помилкою. Передайте --user=root, щоб свідомо залишитися під root. Повний сценарій, граматику <spec> і контрольний список прав доступу до файлів див. у розділі Запуск не від root на порту 80.
oxphp run
oxphp run <script.php> [args…] виконує окремий PHP-файл до завершення й виходить із кодом завершення самого скрипта. Він працює в головному потоці: немає ні слухача, ні пулу воркерів, ні черги запитів. PHP_SAPI === 'cli', а phpinfo() виводить текст, а не HTML, як і стандартний php CLI.
oxphp run migrate.php
oxphp run bin/console.php cache:clear
oxphp run -d memory_limit=512M import.php data.csvСаме цю роль варто використовувати для міграцій, cron-завдань, споживачів черг і команд у стилі artisan/console — у тому самому образі, що обслуговує ваш застосунок, без другої інсталяції PHP.
Під скриптом доступний повноцінний рушій OxPHP: файбери (oxphp_sleep()) і спільний стан (OxPHP\Shared\*) працюють одразу. Асинхронні проміси (oxphp_async()) працюють, коли ASYNC_WORKERS більше за 0; виклик за замовчуванням не запускає асинхронного пулу, а отже, й фонового рантайму.
$argv і $argc заповнені ($argv[0] — шлях до скрипта), а STDIN / STDOUT / STDERR визначені, тож точки входу в стилі Composer і Symfony Console запускаються без змін.
Кожен токен після шляху до скрипта передається в PHP дослівно, включно з тими, що починаються з --, тож для звичайних аргументів явний -- не потрібен. Прапорці, призначені самому oxphp (-d, --user), мають стояти перед шляхом до скрипта; усе, що після нього, належить скрипту.
oxphp run console.php migrate --force --pretend
# ▲ script └──────────────┬──────────┘
# $argv[1..], passed to PHP verbatim (oxphp parses nothing here)Отже, oxphp run console.php --force передає скрипту --force у $argv, тоді як oxphp run --force console.php є помилкою: --force стоїть перед шляхом до скрипта, де oxphp приймає лише -d / --user / --help.
Маркер кінця опцій --
oxphp підтримує стандартний маркер кінця опцій --, і він важить рівно в одному місці: перед шляхом до скрипта, коли сам шлях починається з дефіса. -- зупиняє розбір опцій, тож наступний токен сприймається як шлях до скрипта, а сам маркер oxphp поглинає: у PHP він не передається.
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"Після шляху до скрипта завершувати вже нічого, тож -- там є звичайними даними й передається в PHP буквально, точнісінько як у php:
oxphp run app.php -- --raw # $argv = ["app.php", "--", "--raw"]Скрипти із shebang
Початковий рядок #! пропускається перед компіляцією, тож виконуваний скрипт без розширення із shebang oxphp запускається напряму:
#!/usr/bin/env oxphp
<?php
echo "hello from a shebang script\n";chmod +x ./greet
./greetПеревизначення ini через -d
-d key[=value] задає директиву php.ini для цього запуску. Прапорець можна повторювати, а голий -d key встановлює значення "1". Ці перевизначення застосовуються до запуску модулів, тож вони мають пріоритет над php.ini для директив будь-якого типу, включно з директивами PHP_INI_SYSTEM / PHP_INI_PERDIR (opcache.*, register_argc_argv, …), які не можна змінити через ini_set() під час виконання.
oxphp run -d memory_limit=1G -d display_errors=1 report.phpТипові значення ini для run
Роль run застосовує орієнтовані на CLI типові значення перед вашими перевизначеннями -d і php.ini:
| Директива | Типове значення | Навіщо |
|---|---|---|
max_execution_time |
0 |
Одноразове завдання (міграція, імпортер, демон) не повинен вбивати таймер виконання PHP. |
max_input_time |
-1 |
Для CLI немає крайнього терміну на розбір вхідних даних. |
display_errors |
stderr |
Помилки йдуть у стандартний потік помилок, а не у стандартний вивід. |
html_errors |
0 |
Помилки звичайним текстом для термінала. |
output_buffering |
0 |
Вивід записується одразу, щойно зʼявляється. |
implicit_flush |
1 |
Кожен запис негайно скидається. |
register_argc_argv |
1 |
$argv / $argc доступні. |
run враховує SUPERGLOBALS_ENABLED. На цьому шляху єдиний її вплив на суперглобальні змінні — чи потрапляє середовище процесу до $_SERVER: зі значенням за замовчуванням (true) середовище, разом із секретами, копіюється туди; із false — ні. В обох випадках $_SERVER зберігає власні ключі скрипта (PHP_SELF, SCRIPT_NAME, SCRIPT_FILENAME, PATH_TRANSLATED і порожній DOCUMENT_ROOT), а $argv / $argc не змінюються. oxphp_superglobals_enabled() повідомляє це налаштування тут так само, як і під serve. $_ENV від цього налаштування не залежить: PHP заповнює його із середовища, коли variables_order містить E, а інакше залишає порожнім.
Коди завершення
| Код | Значення |
|---|---|
| власний код скрипта | exit($code) / die($code) або 0 у разі чистого завершення. |
255 |
Фатальна помилка, неперехоплений виняток або помилка синтаксичного розбору. |
1 |
Не вдалося відкрити шлях до скрипта (oxphp: Could not open input file: <path>). |
2 |
Некоректний аргумент -d. |
Випадок із файлом, який не вдається відкрити, перевіряється до запуску рушія, тож відсутній чи недоступний для читання скрипт швидко завершується з повідомленням у стилі php, замість того щоб запускати рушій лише для того, щоб той упав із помилкою компіляції.
--user на шляху run
run дотримується тієї ж поведінки за замовчуванням, що й serve: без --user він за можливості (best-effort) скидає привілеї до www-data перед виконанням скрипта (і мовчки пропускає цей крок, якщо запуск уже не від root). oxphp run --user=<spec> <script.php> перевизначає цільового користувача, щоб одноразове завдання, запущене від root, могло виконатися від конкретного непривілейованого користувача; --user=root зберігає root. Граматика <spec> і механіка скидання привілеїв ідентичні serve --user; явний --user під час запуску не від root є критичною помилкою.
oxphp config
Утиліти для конфігурації. --check перевіряє конфігурацію зі змінних середовища й повідомляє про проблеми, не запускаючи сервер.
oxphp config --checkconfig: OKПеревірка охоплює лише коректність файлової системи: наявність шляхів і їхній тип — файл чи каталог (DOCUMENT_ROOT, ENTRY_FILE, TLS_CERT, TLS_KEY, ERROR_PAGES_DIR, …). Рантайм PHP, TLS-рукостискання та привʼязка до мережі не перевіряються. У разі збою команда завершується з ненульовим кодом і виводить config: INVALID, по одному рядку на кожну проблему.
Після вердикту може йти рекомендація щодо розмірів у рядку ! — наразі одна, для черги PHP, розмір якої дозволяє вмістити кожне зʼєднання, що його серверу дозволено прийняти:
config: OK
! PHP_WORKERS (7) + QUEUE_CAPACITY (896) + QUEUE_MAX_WAITING (500) = 1403 >= MAX_CONNECTIONS (1000): …Це не збій перевірки: конфігурація допустима, а код завершення не змінюється, тож такий рядок може йти після будь-якого вердикту. Тому перевірка має спиратися на код завершення, а не на точний збіг виводу.
Оскільки oxphp config --check завершується з ненульовим кодом у разі некоректної конфігурації, його можна використовувати як перевірку перед запуском у entrypoint або CI-завданні.
--help і --version
oxphp --help # full usage
oxphp config --help # config subcommand usage
oxphp --version # version and the feature flags compiled into this binaryoxphp --version показує функції, увімкнені в цій збірці (наприклад, php, plugin-apm, plugin-async), — це найшвидший спосіб переконатися, чи зібрано образ з APM, async або іншими необовʼязковими плагінами.
Що далі
- Довідник із конфігурації: усі змінні середовища, які читає сервер.
- Запуск не від root на порту 80: повний сценарій
--user, граматика<spec>і контрольний список прав доступу до файлів. - Суперглобальні змінні: що
runзаповнює для одноразового скрипта і якSUPERGLOBALS_ENABLEDзмінює$_SERVER.