Laravel
Пакет rapira/laravel подключает Laravel к Rapira. Один входной скрипт обслуживает все три режима выполнения. Ключ mode в rapira.toml выбирает режим. Код приложения не изменяется.
В режимах Worker и Dispatcher приложение инициализируется один раз и остаётся в памяти. Мост использует воркер Laravel Octane, чтобы сбрасывать состояние приложения между запросами. Octane является зависимостью пакета. Команда octane:start не нужна, потому что Rapira заменяет сервер Octane.
Проверено на
- rapira/laravel 0.1.1
- laravel/framework v13.34.0 и laravel/octane v2.20.0
- PHP 8.5: embed SAPI
Тесты моста отправляют реальные HTTP-запросы приложению Laravel в каждом из трёх режимов. Тесты покрывают маршрутизацию, страницу 404, исключения в маршрутах, изоляцию конфигурации между запросами, сессии, cookie, данные форм, потоковые ответы и скачивание файлов.
Требования
- PHP 8.4 или новее.
- Laravel 11, 12 или 13.
- Rapira 0.9 или новее. См. Установка.
Rapira предоставляет PHP как библиотеку, а не как команду php. Установите PHP CLI для Composer и artisan. Rapira не использует и не изменяет этот CLI.
Новый проект laravel/laravel использует SQLite и драйверы сессий, кеша и очередей на основе базы данных. Поэтому требуется pdo_sqlite. Релизные сборки Rapira включают pdo_sqlite. Полный список расширений см. в разделе Установка. Если вы собираете PHP, включите расширения, которые нужны вашим драйверам. См. раздел Сборка из исходников.
Установка
Установите пакет:
composer require rapira/laravelLaravel автоматически находит сервис-провайдер пакета. Опубликуйте входной скрипт и начальную конфигурацию сервера в корень проекта:
php artisan vendor:publish --tag=rapiraКоманда создаёт два файла. worker.php является входным скриптом для всех режимов:
<?php
declare(strict_types=1);
use Rapira\Laravel\Runner;
require __DIR__ . '/vendor/autoload.php';
(new Runner(__DIR__))->run();Аргумент Runner - это корень приложения, каталог, который содержит bootstrap/app.php. rapira.toml настраивает сервер:
[http]
listen = "127.0.0.1:8000"
middleware = ["static"]
[http.static]
root = "public"
[http.pool]
entrypoint = "worker.php"
# "dispatcher", "worker" или "classic": один и тот же worker.php обслуживает все три.
mode = "dispatcher"Запустите сервер:
rapira serve rapira.tomlСервер работает на переднем плане, приложение доступно по адресу http://127.0.0.1:8000/. Чтобы остановить сервер, нажмите Ctrl-C.
Относительный entrypoint использует каталог файла конфигурации как базовый. Все ключи и значения по умолчанию см. в разделе Конфигурация.
Режимы выполнения
Runner читает режим при запуске воркера и выполняет соответствующий цикл. Чтобы сменить режим, измените http.pool.mode. Оставьте тот же worker.php.
| Режим | Время жизни приложения | Источник запроса |
|---|---|---|
classic | Один запрос | Суперглобальные переменные, которые заполняет Rapira |
worker | Процесс воркера | Суперглобальные переменные, которые заполняет Rapira |
dispatcher | Процесс воркера | Объекты Rapira\Http\Exchange |
Режим Classic выполняет тот же жизненный цикл, что и public/index.php Laravel. Мост загружает bootstrap/app.php, обрабатывает запрос, отправляет ответ и вызывает terminate(). Файл режима обслуживания storage/framework/maintenance.php работает так же, как в public/index.php. После запроса состояние не сохраняется. См. Режим Classic.
Режим Worker хранит одно приложение в каждом процессе воркера. Rapira заполняет суперглобальные переменные для каждого запроса, и мост создаёт запрос через Request::capture(). Ответ отправляется через header() и вывод, как в режиме Classic. См. Режим Worker.
Режим Dispatcher хранит одно приложение в каждом процессе воркера. Мост получает каждый запрос как exchange от HTTP-диспетчера. Он создаёт Illuminate\Http\Request из exchange и записывает ответ обратно в exchange. Этот режим используется по умолчанию.
Во всех режимах каждый воркер обрабатывает один запрос за раз. Octane сбрасывает приложение для каждого запроса, поэтому два запроса не могут одновременно использовать одно приложение.
Суперглобальные переменные в режиме Dispatcher
В режиме Dispatcher Rapira не заполняет $_GET, $_POST, $_COOKIE, $_FILES и значения запроса в $_SERVER. Мост их тоже не заполняет. Коду Laravel, который читает объект Request, эти переменные не нужны. Сессии и cookie Laravel также работают через объекты Request и Response.
Используйте режим Worker, если приложение или пакет выполняет одну из этих операций:
- Читает суперглобальные переменные напрямую.
- Отправляет заголовки через
header()илиsetcookie(). - Использует встроенные сессии PHP (
session_start()).
Мост заполняет серверные значения объекта Request так, как если бы запрос обработал public/index.php. SCRIPT_NAME равен /index.php, а DOCUMENT_ROOT - каталог public/. Имена заголовков преобразуются в ключи HTTP_* по тем же правилам, что и в режиме Worker.
Состояние между запросами
В режимах Worker и Dispatcher воркер Octane инициализирует приложение один раз для каждого экземпляра приложения. Для каждого запроса Octane клонирует приложение в песочницу. Затем он запускает свои слушатели, которые сбрасывают известное состояние запроса. Например, изменение конфигурации в одном запросе не появляется в следующем запросе. Тесты моста подтверждают это поведение в обоих режимах.
Конфигурация Octane управляет этими слушателями. Ключ warm перечисляет сервисы, которые нужно инициализировать до первого запроса. Ключ flush перечисляет сервисы, которые нужно удалять после каждого запроса. Если у приложения нет config/octane.php, Octane использует конфигурацию по умолчанию. Чтобы изменить конфигурацию, опубликуйте файл:
php artisan vendor:publish --tag=octane-configКлюч server и серверные настройки этого файла не применяются к Rapira. Настраивайте сервер в rapira.toml.
Octane не сбрасывает статические свойства, глобальные переменные и синглтоны, которые хранят ссылку на запрос или контейнер. Код приложения и пакеты должны быть безопасны для постоянного воркера. См. Dependency injection and Octane в документации Laravel. Состояние, которое остаётся в воркере, описано на странице Интеграция с фреймворками.
Octane::concurrently() выполняет свои задачи последовательно. Хранилище кеша Octane и Octane::table() требуют Swoole. На Rapira они недоступны.
Маршрутизация и URL
Rapira не сопоставляет URL со скриптами PHP. Каждый запрос запускает входной скрипт, и Laravel выполняет маршрутизацию по пути запроса. Созданные URL являются абсолютными и не содержат ни worker.php, ни index.php. Им не нужны переопределения $_SERVER и изменения конфигурации маршрутов или URL.
Начальный rapira.toml включает middleware статических файлов для public/. Middleware отвечает на запросы, которые соответствуют файлам в public/. Все остальные запросы передаются в Laravel. Вместо этого ресурсы может отдавать CDN или обратный прокси.
Встроенный маршрут /up возвращает 200. Балансировщик нагрузки или контейнер может использовать его для проверок состояния. Rapira также может отдавать /livez и /readyz на отдельном адресе. См. Метрики и проверки работоспособности.
Rapira принимает только открытый HTTP, поэтому Laravel видит каждый запрос как http, также когда запрос содержит X-Forwarded-Proto. Если прокси завершает TLS, настройте в Laravel доверенные прокси. Без этой настройки url() создаёт ссылки http://.
Сессии, CSRF и формы
Сессии Laravel используют cookie сессии и настроенный драйвер сессий. Каждый клиент получает отдельную сессию. CSRF не требует настройки Rapira, потому что токен находится в сессии.
Тесты моста покрывают данные форм с вложенными полями и загрузку файлов. В режиме Dispatcher мост разбирает тела форм для POST, PUT, PATCH и DELETE, как это делает Request::createFromGlobals().
http.max_body_size_mb ограничивает тело запроса до запуска PHP. Значение по умолчанию: 8 МиБ. Для тела большего размера Rapira возвращает 413, и Laravel не получает запрос. Чтобы принимать загрузки большего размера, увеличьте это значение. Также увеличьте post_max_size и upload_max_filesize в php.ini. См. раздел Тела запросов.
Ответы
Мост отправляет все типы ответов Laravel:
- Буферизованные ответы отправляются со своими заголовками и cookie.
- Потоковые ответы (
response()->stream()) отправляются частями. Обратный вызов может вызватьob_flush()илиflush(), чтобы отправить текущую часть. - Файловые ответы (
response()->download()иresponse()->file()) отправляются со своими заголовками. В режиме Dispatcher мост передаёт путь к файлу в Rapira, и Rapira читает файл. Если Rapira не может отправить файл, PHP передаёт его потоком.
Вывод, который контроллер печатает через echo, отправляется перед телом ответа.
В режимах Classic и Worker мост вызывает rapira_finish_request() после ответа. Клиент получает ответ до запуска terminable middleware и очистки Octane.
Ошибки
Laravel обрабатывает исключение в маршруте и возвращает свой обычный ответ 500. Тот же воркер обрабатывает следующий запрос.
Исключение может выйти за пределы HTTP-ядра Laravel, например из обратного вызова потокового ответа. Тогда Octane передаёт исключение обработчику исключений Laravel. Если заголовки ответа ещё не отправлены, клиент получает текстовый ответ 500. Ответ содержит подробности исключения, только когда app.debug равен true.
После такого исключения состояние приложения может быть некорректным. Octane останавливает воркер, и мост завершает свой цикл. Затем Rapira снова запускает входной скрипт, и новый воркер заново инициализирует приложение.
Продакшен
Создайте кеши фреймворка перед запуском сервера:
php artisan config:cache
php artisan route:cacheВоркер может со временем увеличивать использование памяти. Задайте лимит запросов для приложения:
[http.pool]
entrypoint = "worker.php"
mode = "dispatcher"
processes = 4
max_requests = 500max_requests перезапускает приложение после случайного числа запросов больше этого значения, но не больше 1,5 этого значения. Он ограничивает влияние утечки памяти, но не исправляет её. См. Модель процессов.
В режимах Worker и Dispatcher код приложения остаётся в памяти. После развёртывания отправьте SIGUSR2 мастер-процессу, чтобы перезапустить приложения. Эта перезагрузка очищает OPcache, поэтому она загружает новый код и при opcache.validate_timestamps = 0. Перезапустите Rapira после изменения файла, который загружает opcache.preload. См. Запуск в продакшене.
Разработка
В режимах Worker и Dispatcher каждый воркер инициализирует приложение один раз. Перезапускайте Rapira после каждого изменения кода, чтобы загрузить новый код PHP.
Также можно использовать режим Classic при разработке. Задайте mode = "classic" в rapira.toml и оставьте entrypoint = "worker.php". Режим Classic инициализирует приложение для каждого запроса, поэтому сохранённые изменения действуют сразу.
Можно ли запустить Laravel в режиме Classic без моста?
Да. Задайте entrypoint = "public/index.php" и mode = "classic". Тогда каждый запрос выполняет стандартный public/index.php, как в php-fpm. Режимы Worker и Dispatcher требуют мост.