Интерфейс командной строки

Бинарный файл oxphp выполняет три роли: serve — запуск HTTP-сервера, run — выполнение одного PHP-скрипта до завершения и config — служебные утилиты. Вызов oxphp без аргументов — это неявный serve, поэтому директива CMD ["oxphp"] в опубликованном образе по-прежнему запускает сервер без изменений.

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')

Роль выбирается по ключевому слову. Точные токены serve, run и config выбирают подкоманду; любой другой первый позиционный аргумент трактуется как путь к скрипту, поэтому oxphp ./bin/migrate.php — это сокращённая запись для oxphp run ./bin/migrate.php. Эвристики по расширению здесь нет: PHP выполняет скрипт по его содержимому, поэтому скрипт без расширения тоже запустится. Об отсутствующем файле сообщает файловая система — ровно так же, как у php.

oxphp serve

Запускает HTTP-сервер приложения — роль по умолчанию. oxphp и oxphp serve эквивалентны. Настройка выполняется через переменные окружения; сам serve принимает только --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

По умолчанию, без --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.

bash
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; вызов по умолчанию не запускает пул async-воркеров, а значит, и фонового рантайма.

$argv и $argc заполняются ($argv[0] — путь к скрипту), а STDIN / STDOUT / STDERR определены, поэтому входные точки в стиле Composer и Symfony Console работают без изменений.

Путь к скрипту — это разделитель

Каждый токен после пути к скрипту передаётся PHP дословно, включая токены с префиксом --, поэтому для обычных аргументов явный -- не нужен. Флаги, предназначенные самому oxphp (-d, --user), должны идти перед путём к скрипту; всё, что после него, принадлежит скрипту.

bash
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 он не передаётся.

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"

После пути к скрипту опций для завершения уже не остаётся, поэтому -- в этом месте — обычные данные и передаётся PHP буквально, ровно как у php:

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

Скрипты с shebang

Начальная строка #! пропускается перед компиляцией, поэтому исполняемый скрипт без расширения с shebang'ом oxphp запускается напрямую:

greet
#!/usr/bin/env oxphp <?php echo "hello from a shebang script\n";
bash
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() во время выполнения.

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

ini по умолчанию для run

Роль run применяет ориентированные на CLI значения по умолчанию до ваших переопределений -d и php.ini:

Директива По умолчанию Зачем
max_execution_time 0 Разовая задача (миграция, импортёр, демон) не должна убиваться SIGALRM.
max_input_time -1 Для CLI нет крайнего срока на разбор входных данных.
display_errors stderr Ошибки идут в стандартный поток ошибок, а не в стандартный вывод.
html_errors 0 Ошибки в виде простого текста для терминала.
output_buffering 0 Вывод пишется по мере его формирования.
implicit_flush 1 Каждая запись немедленно сбрасывается.
register_argc_argv 1 $argv / $argc доступны.
Note

Суперглобальные переменные всегда включены для run: разовому скрипту нужны $argv, $_SERVER и $_ENV. Это справедливо независимо от переключателя SUPERGLOBALS_ENABLED, который относится к HTTP-серверу.

Коды выхода

Код Значение
собственный код скрипта 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 проверяет конфигурацию из переменных окружения и сообщает о проблемах, не запуская сервер.

bash
oxphp config --check
text
config: OK

Проверка охватывает только корректность файловой системы: существование путей и тип файла/каталога (DOCUMENT_ROOT, ENTRY_FILE, TLS_CERT, TLS_KEY, ERROR_PAGES_DIR, …). PHP-рантайм, TLS-рукопожатие и привязка к сети сюда не входят. При неудаче процесс завершается с ненулевым кодом и выводит config: INVALID, по одной строке на каждую проблему.

Tip

Поскольку oxphp config --check завершается с ненулевым кодом при некорректной конфигурации, его можно использовать как проверку перед запуском в entrypoint или в CI-задаче.

--help и --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 сообщает о функциях, включённых в этой сборке (например, php, plugin-apm, plugin-async) — это самый быстрый способ проверить, собран ли образ с APM, async или другими опциональными плагинами.

Дальнейшие шаги

Нашли ошибку? Сообщите →