Interfejs wiersza poleceń

Binarka oxphp pełni trzy role: serwuje serwer HTTP (serve), uruchamia pojedynczy skrypt PHP do końca (run) oraz udostępnia narzędzia konfiguracyjne (config). Samo oxphp bez argumentów to niejawne serve, więc CMD ["oxphp"] w opublikowanym obrazie bez zmian nadal uruchamia serwer.

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

Rola jest wybierana za pomocą słowa kluczowego. Dokładne tokeny serve, run i config wybierają podpolecenie; każdy inny pierwszy argument pozycyjny jest traktowany jako ścieżka skryptu, więc oxphp ./bin/migrate.php to skrót od oxphp run ./bin/migrate.php. Nie ma tu heurystyki rozszerzeń: PHP wykonuje kod na podstawie zawartości pliku, więc skrypt bez rozszerzenia również się uruchomi. O brakującym pliku informuje system plików, dokładnie tak jak w php.

oxphp serve

Uruchamia serwer aplikacji HTTP — rola domyślna. oxphp i oxphp serve są równoważne. Konfiguracja odbywa się za pomocą zmiennych środowiskowych; samo serve przyjmuje jedynie --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

Domyślnie, bez --user, serve wykonuje próbę zrzucenia uprawnień do www-data w miarę możliwości (best-effort). Uruchomiony jako root przy obecnym koncie www-data (jak w oficjalnym obrazie), wiąże listenery jako root, a następnie trwale zrzuca uprawnienia do www-data, zanim obsłuży jakikolwiek ruch. Uruchomiony jako użytkownik inny niż root zachowuje bieżącego użytkownika; uruchomiony jako root na hoście bez konta www-data zapisuje ostrzeżenie w logu i kontynuuje działanie jako root. Wariant domyślny nigdy nie przerywa startu.

--user=<spec> nadpisuje cel i działa w trybie fail-fast: wiąże listenery jako root, następnie trwale zrzuca uprawnienia do wskazanego użytkownika i kończy działanie z błędem, jeśli nie został uruchomiony jako root. Podaj --user=root, aby celowo pozostać przy roocie. Pełny wzorzec, gramatykę <spec> oraz listę kontrolną uprawnień plików znajdziesz w Uruchamianie jako użytkownik inny niż root na porcie 80.

oxphp run

oxphp run <script.php> [args…] wykonuje pojedynczy plik PHP do końca i kończy działanie z kodem wyjścia samego skryptu. Działa na głównym wątku: nie ma listenera, puli workerów ani kolejki żądań. PHP_SAPI === 'cli', a phpinfo() wypisuje tekst zamiast HTML, zgodnie ze standardowym CLI php.

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

To rola przeznaczona do migracji, zadań cron, konsumentów kolejek oraz poleceń w stylu artisan/console, w tym samym obrazie, który serwuje Twoją aplikację, bez drugiej instalacji PHP.

Pod skryptem dostępny jest pełny silnik OxPHP: Fibery (oxphp_sleep()) i stan współdzielony (OxPHP\Shared\*) działają od razu. Asynchroniczne promisy (oxphp_async()) działają, gdy ASYNC_WORKERS jest większe niż 0; domyślne wywołanie nie uruchamia żadnej puli asynchronicznej, a więc również żadnego środowiska działającego w tle.

$argv i $argc są wypełnione ($argv[0] to ścieżka skryptu), a STDIN / STDOUT / STDERR są zdefiniowane, więc punkty wejścia w stylu Composera i Symfony Console działają bez zmian.

Ścieżka skryptu jest separatorem

Każdy token po ścieżce skryptu jest przekazywany do PHP dosłownie, łącznie z tymi zaczynającymi się od --, więc dla zwykłych argumentów nie potrzebujesz jawnego --. Flagi przeznaczone dla samego oxphp (-d, --user) muszą znaleźć się przed ścieżką skryptu; wszystko po niej należy do skryptu.

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

Zatem oxphp run console.php --force przekazuje skryptowi --force w $argv, natomiast oxphp run --force console.php jest błędem: --force poprzedza ścieżkę skryptu, gdzie oxphp akceptuje jedynie -d / --user / --help.

Znacznik końca opcji --

oxphp respektuje standardowy znacznik końca opcji --, a ma on znaczenie w dokładnie jednym miejscu: przed ścieżką skryptu, gdy sama ścieżka skryptu zaczyna się od myślnika. -- zatrzymuje parsowanie opcji, dzięki czemu następny token jest traktowany jako ścieżka skryptu, a oxphp go konsumuje; nie jest on przekazywany do 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"

Po ścieżce skryptu nie ma już żadnych opcji do zakończenia, więc -- jest w tym miejscu zwykłą daną i jest przekazywane do PHP dosłownie, dokładnie tak jak w php:

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

Skrypty z shebangiem

Wiodąca linia #! jest pomijana przed kompilacją, więc wykonywalny skrypt bez rozszerzenia z shebangiem oxphp uruchamia się bezpośrednio:

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

Nadpisania ini za pomocą -d

-d key[=value] ustawia dyrektywę php.ini dla tego uruchomienia. Można ją powtarzać, a samo -d key ustawia wartość na "1". Te nadpisania są stosowane przed uruchomieniem modułów, więc wygrywają z php.ini dla każdego typu dyrektywy, w tym dla dyrektyw PHP_INI_SYSTEM / PHP_INI_PERDIR (opcache.*, register_argc_argv, …), których ini_set() w czasie działania nie może zmienić.

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

Domyślne ini dla run

Rola run stosuje domyślne ustawienia zorientowane na CLI przed Twoimi nadpisaniami -d oraz php.ini:

Dyrektywa Domyślnie Dlaczego
max_execution_time 0 Zadanie jednorazowe (migracja, importer, demon) nie może zostać zabite przez SIGALRM.
max_input_time -1 Brak limitu czasu na parsowanie wejścia dla CLI.
display_errors stderr Błędy trafiają na standardowe wyjście błędów, a nie na standardowe wyjście.
html_errors 0 Błędy w postaci zwykłego tekstu dla terminala.
output_buffering 0 Dane wyjściowe są zapisywane w miarę ich generowania.
implicit_flush 1 Każdy zapis jest natychmiast opróżniany (flush).
register_argc_argv 1 $argv / $argc są dostępne.
Note

Zmienne superglobalne są zawsze włączone dla run: skrypt jednorazowy potrzebuje $argv, $_SERVER i $_ENV. Obowiązuje to niezależnie od przełącznika SUPERGLOBALS_ENABLED, który dotyczy serwera HTTP.

Kody wyjścia

Kod Znaczenie
własny skryptu exit($code) / die($code) lub 0 przy czystym zakończeniu.
255 Błąd krytyczny, nieprzechwycony wyjątek lub błąd parsowania.
1 Nie udało się otworzyć ścieżki skryptu (oxphp: Could not open input file: <path>).
2 Nieprawidłowy argument -d.

Przypadek niemożliwego do otwarcia pliku jest sprawdzany przed uruchomieniem silnika, więc brakujący lub nieczytelny skrypt zawodzi szybko z komunikatem w stylu php, zamiast uruchamiać silnik tylko po to, by ten zakończył się błędem kompilacji.

--user na ścieżce run

run stosuje tę samą domyślną regułę co serve: bez --user wykonuje próbę zrzucenia uprawnień do www-data w miarę możliwości (best-effort), zanim skrypt się wykona (pomijaną po cichu, gdy użytkownik jest już inny niż root). oxphp run --user=<spec> <script.php> nadpisuje cel, więc zadanie jednorazowe uruchomione jako root może działać jako konkretny nieuprzywilejowany użytkownik; --user=root pozostawia root. Gramatyka <spec> oraz mechanika zrzucania uprawnień są identyczne jak w serve --user; jawne --user uruchomione jako użytkownik inny niż root to twardy błąd.

oxphp config

Narzędzia konfiguracyjne. --check waliduje konfigurację zmiennych środowiskowych i zgłasza problemy bez uruchamiania serwera.

bash
oxphp config --check
text
config: OK

Sprawdzenie obejmuje wyłącznie poprawność systemu plików: istnienie ścieżek oraz rodzaj pliku/katalogu (DOCUMENT_ROOT, ENTRY_FILE, TLS_CERT, TLS_KEY, ERROR_PAGES_DIR, …). Środowisko uruchomieniowe PHP, handshake TLS oraz wiązanie sieciowe pozostają poza zakresem. W razie niepowodzenia kończy działanie z niezerowym kodem i wypisuje config: INVALID, po jednej linii na problem.

Tip

Ponieważ oxphp config --check kończy działanie z niezerowym kodem przy nieprawidłowej konfiguracji, sprawdza się jako bramka przed startem w entrypoincie lub zadaniu CI.

--help i --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 raportuje funkcje włączone w danej wersji (na przykład php, plugin-apm, plugin-async), co jest najszybszym sposobem, aby potwierdzić, czy obraz został zbudowany z APM, async lub innymi opcjonalnymi wtyczkami.

Następne kroki

Znalazłeś błąd? Zgłoś go →