Документация OxPHP

OxPHP — это высокопроизводительный сервер приложений PHP, который заменяет связку nginx + PHP-FPM одним бинарным файлом: встроенные TLS, сжатие Brotli, ограничение частоты запросов, проверки работоспособности, метрики Prometheus, потоковая передача SSE и постоянный режим воркеров уже включены.

Почему OxPHP

Типичное PHP-приложение в продакшене — это несколько контейнеров: nginx, PHP-FPM, иногда отдельный TLS-прокси и экспортёр метрик. Конфигурация размазана по ним, и чтобы всё работало вместе, приходится держать в согласованности настройки сокетов, таймауты и пути. OxPHP заменяет весь стек одним контейнером. Внутри — один процесс, который принимает HTTP-соединения, выполняет PHP и раздаёт статические файлы.

Сервер работает «из коробки» с разумными значениями по умолчанию. Тонкая настройка выполняется через переменные окружения: TLS включается двумя переменными (TLS_CERT, TLS_KEY), ограничение частоты запросов — одной (RATE_LIMIT), а сжатие Brotli включено по умолчанию. Не нужно править конфиги nginx или собирать отдельные модули.

На выделенном внутреннем порту доступны проверки работоспособности (/health), метрики Prometheus (/metrics) и снимок конфигурации (/config). Этого достаточно для liveness/readiness-проб Kubernetes и подключения Grafana — без дополнительных sidecar-контейнеров.

Логи — это структурированный JSON: метод, путь, статус, время ответа и идентификатор запроса в каждой строке. Их легко разбирать в Loki, Elasticsearch или любом другом инструменте без дополнительных grok-паттернов.

Чтобы попробовать режим воркеров, в котором процесс PHP не пересоздаётся на каждый запрос, задайте WORKER_MODE_ENABLED=true и ENTRY_FILE=worker.php. Фреймворк инициализируется один раз, а затем обрабатывает тысячи запросов без перезагрузки. Чтобы вернуться к классическому режиму, удалите эту переменную.

OxPHP также включает возможности, для которых обычно требуются отдельные инструменты или сторонние библиотеки:

Начало работы

Эксплуатация

Возможности

  • Маршрутизация — три режима маршрутизации: традиционное отображение по файлам, фронт-контроллер фреймворка и SPA-фолбэк. Режим воркеров — это ортогональный переключатель модели выполнения, который применяется поверх любого режима маршрутизации
  • Статические файлы — кэш файлов, определение MIME, заголовки ETag/Last-Modified и потоковая передача
  • Режим воркеров — постоянные процессы PHP с автоматическим мягким сбросом состояния между запросами
  • Мультиплексирование файберов — обработка сотен конкурентных запросов на один поток воркера за счёт кооперативной многозадачности
  • Сжатие — сжатие Brotli для текстовых ответов
  • TLS — встроенная терминация TLS с настройкой сертификата и ключа
  • Ограничение частоты запросов — ограничение частоты запросов по IP с настраиваемыми окнами и лимитами
  • Таймауты — таймауты чтения заголовков и запроса
  • Логирование доступа — структурированные JSON-логи доступа с идентификатором запроса, методом, путём, статусом и длительностью
  • Идентификаторы запросов — автоматическая генерация и проброс X-Request-ID
  • Страницы ошибок — пользовательские HTML-страницы ошибок для любого HTTP-кода состояния
  • SSE — потоковая передача Server-Sent Events в реальном времени из PHP
  • Ранний ответ — отправьте ответ немедленно и продолжайте фоновую обработку
  • Асинхронные промисы — выполнение замыканий PHP в фоновых потоках с ожиданием результатов
  • Декораторы — перехват вызовов функций и методов с помощью атрибутов PHP 8
  • Распределённая трассировка и APM — W3C Trace Context, OpenTelemetry, автоматическая инструментация и SDK трассировки для PHP
  • Внутренний сервер — выделенный порт для проверок работоспособности, метрик Prometheus и актуальной конфигурации

Безопасность

  • Блокировка dot-путей — автоматическая блокировка скрытых файлов и каталогов (.env, .git/, .htaccess)
  • Доверенные прокси — извлечение реального IP клиента из заголовков Forwarded (RFC 7239) и X-Forwarded-* с доверием на основе CIDR
  • Дени-лист выполнения PHP — запрет выполнения .php по доступным для записи публичным путям (например, /uploads/** или конкретные legacy-скрипты), чтобы пресечь атаки через загруженные веб-шеллы на старых приложениях
  • Разрешённые пути для симлинков — опциональный список разрешений для целей симлинков за пределами DOCUMENT_ROOT; поддерживает storage:link в стиле Laravel и общие тома с ассетами, не ослабляя стандартную защиту от выхода за пределы через симлинки

PHP

  • HTTP Request API — объектно-ориентированный доступ к запросу через oxphp_http_request(): параметры строки запроса, разобранное тело, заголовки, куки, загруженные файлы и не только
  • Функции — встроенные PHP-функции, предоставляемые OxPHP (oxphp_worker(), oxphp_request_id(), oxphp_server_info() и другие)
  • Суперглобальные переменные — как заполняются $_SERVER, $_GET, $_POST, $_COOKIE, $_FILES и php://input
  • OPcache и JIT — настройка OPcache и параметры JIT-компиляции

Разделяемое состояние

Конкурентные примитивы на уровне всего процесса, позволяющие воркерам координировать изменяемое состояние без Redis, Memcached или APCu — всё живёт внутри процесса, поэтому стоимость одной операции измеряется микросекундами, а не сетевыми обращениями туда-обратно.

  • Обзор — модель реестра, жизненный цикл дескрипторов и когда стоит прибегать к разделяемому состоянию
  • Реестр — реестр на уровне всего процесса, жизненный цикл записей и интроспекция
  • Counter — атомарный аккумулятор int64 (get, set, add, compareAndSet)
  • Atomic — атомарный int64 с явным управлением порядком доступа к памяти
  • Flag — атомарный булев флаг для одноразовых переходов
  • Once — контейнер однократного выполнения с безопасной при повторном входе фабрикой
  • Mutex — отравляемый мьютекс над хранимым значением с обнаружением взаимоблокировок
  • Channel — ограниченная MPMC-очередь с поддержкой файберов
  • Map — конкурентное хранилище со строковыми ключами и пакетным доступом
  • Pool — ограниченный пул объектов с привязкой к потокам
  • Соглашения об именовании — шпаргалка по именованию методов во всём семействе Shared\*
  • Наблюдаемость — счётчики Prometheus и JSON-эндпоинты интроспекции
  • Переход на внешнее хранилище — когда и как перейти на Redis или APCu

Архитектура

  • Обзор архитектуры — как устроен OxPHP: асинхронная обработка HTTP, пул воркеров PHP, поток обработки запроса и гарантии безопасности

Примеры

Сквозные рецепты запуска популярных PHP-приложений на OxPHP — каждый представляет собой полноценный проект Docker Compose с Dockerfile, docker-compose.yml, шагами установки и специфичными для OxPHP замечаниями, которых нет в стандартной документации (nginx + PHP-FPM).

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