Каждая настройка — одна переменная окружения
Каждая настройка — это переменная окружения (плюс один необязательный файл, .oxphpdeny, для правил запрета путей), и у каждой переменной есть значение по умолчанию, рассчитанное на production. Начните с пустого окружения, а затем переопределяйте только те переменные, которые действительно важны для вашего приложения.
Всё, что не входит в этот набор — например, опечатки вроде «ture», — сразу приводит к ошибке при запуске с указанием переменной. Пустое значение равносильно незаданному: подстановки FOO=${FOO}, дающие FOO=, используют значение по умолчанию, а не прерывают запуск.
Сервер и воркеры
15 переменныхАдрес и порт основного HTTP-сервера.
Корневой каталог для отдачи файлов и PHP-скриптов.
Единый канонический входной скрипт. Не задан = прямое сопоставление файлов, *.php = фронт-контроллер, не-.php = SPA-фолбэк; в режиме воркеров — бутстрап воркера. Разрешается относительно DOCUMENT_ROOT.
Включает постоянный режим воркеров. Требует, чтобы ENTRY_FILE указывал на .php-скрипт.
Максимальное число одновременных TCP-соединений. Также потолок для QUEUE_MAX_WAITING по умолчанию (его половина); некорректное значение — ошибка при запуске. Держите его выше PHP_WORKERS + QUEUE_CAPACITY + QUEUE_MAX_WAITING.
Потоки асинхронного ввода-вывода. 1 = однопоточный режим, N = фиксированное количество, не задано = авто. Делит ядра с PHP_WORKERS — поднятие до полного числа ядер обычно снижает пропускную способность. CPU — это число ядер, на которых может выполняться процесс (маска привязки к CPU, урезанная до квоты cgroup), а не вес CPU и не лимит, который платформа применяет вне контейнера; что именно было посчитано, показывает строка запуска CPU count for default sizing.
Бэкенд исполнения PHP: sapi — настоящий PHP, stub — для бенчмаркинга без PHP.
Размер пула воркеров. N = фиксированный пул, MIN:MAX = динамическое масштабирование, 0 = авто. Авторазмер считает CPU так же, как TOKIO_WORKERS, — на тарифе, чей лимит CPU контейнер не видит (cpu_source: host в логе запуска), задайте обе переменные явно.
Сколько секунд динамический воркер простаивает перед выводом из пула. Вывод ждёт момента, когда в обработке ничего нет, поэтому выполняющиеся запросы никогда не обрываются.
Максимум ожидающих запросов в очереди PHP; пришедшие в заполненную очередь ждут до QUEUE_WAIT_TIMEOUT_MS. 0 = авто. Для пулов MIN:MAX начальное число воркеров равно минимуму.
Верхний предел того, сколько запрос может ждать PHP-воркера до 529 — один дедлайн, покрывающий ожидание слота очереди и ожидание в самой очереди. При перегрузке сервер сам сокращает его (до 1/64, минимум 10 мс); действующее значение показывает oxphp_admission_wait_budget_us. 0 = отклонять сразу, как только очередь заполнена.
Максимум запросов, припаркованных в ожидании слота очереди; сверх него — немедленный 529. Каждый ожидающий удерживает соединение и своё буферизованное тело. 0 = авто.
Максимум байтов тел запросов у множества ожидающих; тело, которое превысило бы предел, получает немедленный 529, запросы без тела продолжают ждать. 0 = авто.
Потолок памяти на воркер в МиБ перед его пересозданием. 0 = без ограничений. Воркеры также пересоздаются после трёх подряд запросов, завершившихся сбоем, или по требованию через Worker::scheduleExit().
Строит $_SERVER и $_GET перед каждым скриптом. Ложное значение пропускает эту работу; $_POST, $_FILES, $_COOKIE и php://input не затрагиваются.
Трафик и доставка
18 переменныхМаксимум секунд на получение HTTP-заголовков после установки соединения (защита от Slowloris).
Максимум секунд на незавершённые запросы при корректном завершении работы; оставшиеся затем отменяются. Запрос, застрявший в блокирующем вызове, может удержать процесс дольше.
Максимум запросов с одного IP за окно. 0 = выключено; при заполненной очереди PHP возвращается 529.
Длительность окна ограничения частоты запросов в секундах.
Путь к PEM-сертификату. Для включения TLS должны быть заданы и TLS_CERT, и TLS_KEY.
Путь к приватному ключу в формате PEM.
Минимальная версия TLS: 1.2 или 1.3. Проверяется при запуске, даже если TLS выключен.
Максимум одновременно открытых потоков на соединение.
Максимум фреймов RST_STREAM в очереди до закрытия соединения (защита от Rapid Reset).
Максимальный суммарный размер декодированных заголовков (в байтах) на запрос.
Интервал между PING-фреймами в секундах; 0 отключает.
Сколько секунд ждать ответа на PING перед закрытием соединения.
Cache-Control: max-age для статических файлов. Принимает 30s, 5m, 2h, 30d, 1w, 1y, число секунд или off. Заменяет STATIC_CACHE_TTL.
Ревалидация по mtime для кэша в памяти — проверяется не чаще одного раза в 3 с на файл. Заменяет STATIC_CACHE.
Предлагаемые кодировки сжатия: br, zstd, gzip. off/none отключает сжатие. Порядок не учитывается — кэшированные статические файлы предпочитают Brotli, всё остальное — zstd.
Качество Brotli 0–11; 0 отключает Brotli. Заменяет COMPRESSION_LEVEL (его 0 по-прежнему отключает все кодировки).
Уровень Zstandard 0–19; 0 отключает zstd. Значения вне диапазона прерывают запуск.
Уровень gzip 0–9; 0 отключает gzip. Значения вне диапазона прерывают запуск.
Безопасность
5 переменныхЗащита от кликджекинга: SAMEORIGIN, DENY или off. Устанавливает X-Frame-Options + CSP frame-ancestors на каждом ответе; заголовки, заданные приложением, всегда имеют приоритет. Недопустимые значения откатываются к SAMEORIGIN с предупреждением при запуске.
Доверенные прокси: список через запятую из CIDR, одиночных IP и ключевых слов private и cloudflare. Реальный IP клиента берётся из Forwarded / X-Forwarded-* по правилу «крайний справа недоверенный»; с cloudflare — из CF-Connecting-IP, если запрос пришёл через edge-узел Cloudflare.
Glob-шаблоны, чьи .php-файлы никогда не исполняются по прямому URI (/uploads/**). Сопоставляются до обращения к диску — не раскрывают факт существования файла.
Ответ при совпадении с PHP_DENY_PATHS или с запрещающим правилом .oxphpdeny: HTTP-статус 400–599 или PHP-скрипт-фолбэк с префиксом / внутри DOCUMENT_ROOT. В режиме воркеров запрещающие правила .oxphpdeny принимают только код статуса.
Абсолютные пути, внутри которых символические ссылки могут выходить за пределы DOCUMENT_ROOT. Не задано = выход запрещён.
Логи, трассировки и профили
39 переменныхДетализация собственной диагностики сервера: trace, debug, info, warn, error. Не фильтрует лог доступа; разрывы соединения клиентом пишутся на уровне debug.
Лог доступа по каждому запросу: all = каждый запрос, error = только 4xx/5xx, не задано = выключено.
Внутренний сервер (/health, /metrics, /config). Значения только с портом привязываются к 127.0.0.1; не задано = не запускается.
Список разрешений в формате CIDR для внутреннего сервера; посторонние получают 403, проверки работоспособности остаются доступны. Loopback не подразумевается по умолчанию.
Каталог с пользовательскими страницами ошибок {status}.html.
Максимальный размер тела запроса (в байтах) для внутренних эндпоинтов запросов (512 КиБ).
Распространение W3C Trace Context: читает traceparent/tracestate и передаёт их в PHP через $_SERVER.
Включает экспорт спанов OpenTelemetry. Подразумевает TRACE_CONTEXT=true.
Протокол экспорта: grpc или http/protobuf.
Эндпоинт OTLP-коллектора. При http/protobuf это базовый URL: спаны отправляются на /v1/traces под ним.
Таймаут экспорта в миллисекундах. По gRPC он также ограничивает подключение к коллектору, включая TLS-рукопожатие, а в Linux задаёт, как скоро закрывается соединение, переставшее принимать данные.
Заголовки аутентификации: key=value,key2=value2.
Имя сервиса в экспортируемых спанах.
Атрибут версии сервиса.
Дополнительные атрибуты ресурса: env=prod,region=us-east-1.
Стратегия сэмплирования: always_on, always_off, traceidratio и варианты parentbased_*.
Доля сэмплирования 0.0–1.0 для сэмплеров на основе доли; значения вне диапазона усекаются до границ.
APM: автоматическое инструментирование 34 функций PHP (PDO, mysqli, cURL, Redis…), захват ошибок, SDK трассировки. Требует OTEL_ENABLED. Когда выключено, oxphp_apm_trace() всё равно выполняет свой колбэк.
Порог медленного запроса в мс; более медленные запросы к БД получают oxphp.db.slow=true.
Записывает привязанные параметры в спаны db.params. Записываются как есть (без обфускации), поэтому в трассировки могут попасть персональные данные — включайте только там, где это приемлемо.
Лимит атрибута exception.stacktrace; усекается с конца. 0 = без усечения.
Лимит атрибута exception.message (предел New Relic на атрибут); усекается с конца. 0 = без усечения.
Главный переключатель. Остальные переменные PROFILER_* всё равно разбираются, поэтому опечатки проявляются при запуске.
Вероятность 0.0–1.0 того, что запрос попадёт в выборку.
Также сэмплировать запросы к внутреннему серверу.
Секрет, который должны нести явные триггеры (заголовок X-OxPHP-Profile, cookie OXPROF, параметр запроса __oxprof), и bearer-токен для /__profiler/*. Не задано = без токена. Сэмплирование и функции OxPHP\Profile\* его никогда не проверяют.
Лимит спанов на запрос; более длинные профили усекаются.
Максимальная глубина вложенности записываемых вызовов; время более глубоких вызовов сворачивается в вызов на пределе. Ограничивается значением 32.
Каталог для профилей на диске.
Форматы, записываемые на диск: xhprof, speedscope, pprof, flamegraph.
Ограничение частоты записи файлов профилей в секунду.
Максимум хранимых файлов профилей; более старые удаляются.
Удалённый эндпоинт, куда профили отправляются методом POST.
Формат передачи для экспорта.
Bearer-токен, отправляемый с каждым экспортом.
XHGui-совместимая упаковка; не задано = автоопределение по URL.
Конверт Buggregator (всегда xhprof); не задано = автоопределение по URL. Взаимоисключается с PROFILER_EXPORT_XHGUI.
app_name Buggregator для группировки по проектам.
Теги Buggregator: key=value,key2=value2. Некорректные токены — ошибка при запуске.
Асинхронность и разделяемое состояние
18 переменныхВключаемые по желанию замены блокирующих встроенных функций, приостанавливающие файбер. Категории: sleep (нативные sleep/usleep), streams (блокирующие чтения tcp:// и stream_select), net (установка соединений, TLS-рукопожатия и чтения по TLS, записи в ожидании места в буфере, чтения unix:// / udp:// / udg:// — требует streams, только Linux). 1/true/all = все категории. Установленный набор показывается как runtime_hooks в /config.
Выделенные потоки асинхронных воркеров. 0 = функции зарегистрированы, но при вызове бросают AsyncException.
Максимум ожидающих задач в асинхронной очереди. 0 = авто.
Лимит одновременных файберов задач на воркер; глобальный лимит выполняемых = файберы × воркеры.
Главный переключатель всей подсистемы OxPHP\Shared\*. Выключено = её классы вообще не регистрируются; проверяйте через class_exists().
Глобальный лимит на живые объекты Shared (ключи Map не учитываются); создание объекта сверх него бросает CapacityException.
Глобальный лимит на оценочный объём памяти по объектам Shared; проверяется только при создании объекта.
Включает/отключает экспозицию Prometheus oxphp_shared_*.
Включает/отключает API интроспекции /__ox_shared/*.
Предпросмотр значений в ответах интроспекции; отключите, если предпросмотр может раскрыть данные.
Глубина BFS при проверке циклов; увеличьте для глубоких графов.
Число рёбер, обходимых при проверке циклов; увеличьте для плотных графов.
Лимит размера одного значения; вставки большего размера сразу отклоняются.
Лимит суммарной полезной нагрузки на канал.
Детектор взаимоблокировок для Shared\Mutex: off, warn (логировать и считать циклы) или strict (разрывать их через DeadlockException). В отладочных сборках по умолчанию strict.
Как часто детектор взаимоблокировок выполняет сканирование, в мс.
Усечение строк в предпросмотрах, в байтах, по границе символа.
Число элементов, выбираемых в предпросмотрах /entry.
Примеры конфигураций
Отправные точки прямо из документации — скопируйте одну и подстройте под себя.
Когда внутренний сервер запущен, /config возвращает итоговую конфигурацию в формате JSON. Пути к TLS, INTERNAL_ADDR и ERROR_PAGES_DIR в ответе скрыты.
Нулевая конфигурация — тоже конфигурация
Все значения по умолчанию выше подобраны так, чтобы пустое окружение просто работало.