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-фолбек. Режим воркерів — це окремий режим маршрутизації, що займає їхнє місце: він потребує ENTRY_FILE із розширенням .php і отримує кожен запит, що не віддається як статичний файл
  • Статичні файли — кеш файлів, визначення 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/** або окремі застарілі скрипти), щоб унеможливити атаки через завантажені веб-шели на застарілих застосунках
  • Правила заборони шляхів — файл .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).

Знайшли помилку? Повідомте →