GitHub

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

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

Почему OxPHP

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

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

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

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

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

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

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

  • Быстрый старт — соберите и запустите своё первое приложение на OxPHP менее чем за 5 минут
  • Установка — системные требования и варианты установки
  • Руководство по Docker — Dockerfile, конфигурация Compose, тома и паттерны развёртывания
  • Интерфейс командной строки — грамматика команды oxphp: serve, run для одного PHP-скрипта, config и сброс привилегий --user
  • Миграция — переход с nginx + PHP-FPM, FrankenPHP или RoadRunner: режимы маршрутизации, соответствие конфигурации, различия в поведении и то, что не переносится

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

Возможности

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

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

  • Блокировка dot-путей — автоматическая блокировка скрытых файлов и каталогов (.env, .git/, .htaccess)
  • Доверенные прокси — извлечение реального IP клиента из заголовков Forwarded (RFC 7239), X-Forwarded-* и, за Cloudflare, CF-Connecting-IP с доверием на основе CIDR
  • Дени-лист выполнения PHP — запрет выполнения .php по доступным для записи публичным путям (например, /uploads/** или конкретные legacy-скрипты), чтобы пресечь атаки через загруженные веб-шеллы на старых приложениях
  • Правила запрета путей — файл .oxphpdeny в стиле gitignore в DOCUMENT_ROOT не даёт отдавать vendor/, дампы, резервные копии и другие файлы или передаёт запросы к ним приложению
  • Разрешённые пути для симлинков — опциональный список разрешений для целей симлинков за пределами 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
  • Класс Worker — runtime-дескриптор OxPHP\Server\Worker: интроспекция воркера, входная точка воркера и метрики по потокам
  • 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, поток обработки запроса и гарантии безопасности

Интеграции

  • MCP-сервер — подключение документации OxPHP к агенту для разработки по протоколу Model Context Protocol

Примеры

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

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