Жизненный цикл сессии NextPDF Connect, безопасный для воркеров

Краткий обзор

Используйте жизненный цикл сессии, ограниченный одним запросом, в долгоживущем PHP-воркере (RoadRunner, Swoole, Laravel Octane). Каждый запрос создаёт собственную сессию документа и уничтожает её после output_pdf. Состояние шрифта, страницы и дескриптора остаётся в границах запроса воркера. Используемые инструменты — create_pdf, set_font, add_text и output_pdf; все они из Core.

Установка

composer require nextpdf/server

Привяжите транспорт. Этот шаблон одинаково работает с любым транспортом.

Концептуальный обзор

Идентификатор document_id — это непрозрачный дескриптор, ограниченный одним запросом. Следуйте одному правилу: создавайте для каждого запроса, уничтожайте после каждого запроса, никогда не кэшируйте и не используйте совместно. При значении destroy: true по умолчанию вызов output_pdf отрисовывает документ и освобождает сессию за один атомарный шаг. Следующий запрос на том же воркере получает новую, независимую сессию. Шрифт и содержимое предыдущей сессии не сохраняются. Результат каждого инструмента — обычный ответ транспорта (PSR-18 §p2). Код сервера изолирован границей автозагрузки (PSR-4 §3). Единственное состояние, общее для запросов, — хранилище сессий; оно индексируется по id.

Поверхность API

Инструмент	Роль	Уровень риска
`create_pdf`	Открывает сессию на один запрос	Безопасный
`set_font`	Задаёт активный шрифт (на сессию)	С осторожностью
`add_text`	Записывает содержимое	С осторожностью
`output_pdf`	Отрисовывает и уничтожает сессию	Требуется подтверждение / Проверка (base64)

Источником истины является Каталог инструментов. Набор доступных вам инструментов зависит от установленного уровня.

Пример кода — быстрый старт

Запрос 1: create_pdf → set_font → add_text → output_pdf (destroy: true). Запрос 2 на том же воркере начинает новую сессию create_pdf. Предыдущий id теперь недействителен. Задайте шрифт снова, поскольку он не переносится.

Пример кода — продакшен

Организуйте жизненный цикл так, чтобы очистка выполнялась всегда:

Получайте сессию в начале запроса.
Формируйте содержимое.
В блоке, эквивалентном finally, вызовите output_pdf: он уничтожает сессию. Если вы использовали destroy: false для проверки после вывода, уничтожьте сессию явно.

Никогда не храните document_id в глобальном для воркера, статическом или общем контейнере. Никогда не передавайте его между корутинами, файберами или обработчиками запросов.

Граничные случаи и подводные камни

Повторное использование id после уничтожения. Вернётся ошибка неизвестного документа. Создавайте новую сессию для каждого запроса.
Забытый output_pdf. Память растёт незаметно, пока не истечёт TTL сессии или не перезапустится процесс. Всегда завершайте сессию.
Лимит сессий под нагрузкой. Хранилище ограничивает число одновременных сессий. Своевременное уничтожение помогает не выходить за этот предел.
destroy: false без очистки. Память растёт постепенно. Используйте этот режим только для явной проверки после вывода, а затем уничтожьте сессию.
Общий id для одновременных запросов. Возникает гонка, повреждающая вывод. Каждый запрос владеет собственной сессией.

Производительность

Вывод для одного запроса занимает несколько КБ. Преимущество — ограниченное потребление памяти воркером в течение всего срока его жизни. Профиль — structural.

Замечания по безопасности

Изоляция сессий также обеспечивает конфиденциальность. Содержимое одного запроса никогда не попадает в другой запрос, поскольку дескрипторы не используются совместно, а сессия уничтожается при выводе.

Соответствие

Утверждение	Спецификация	Пункт	reference_id (идентификатор источника)
Результат каждого инструмента — это обычный ответ транспорта.	PSR-18	§p2
Код изолирован сопоставлением класс→файл при автозагрузке.	PSR-4	§3

Коммерческий контекст

Не применимо — все инструменты из Core.

Доступность транспортов

Транспорт	Доступен	Примечания
MCP (stdio, стандартный ввод-вывод)	Да	Обычно один процесс stdio на воркер.
REST	Да	Граница HTTP-запроса соответствует границе сессии.
gRPC	Да	Одна сессия на последовательность RPC.

Уровень риска HITL

create_pdf — Безопасный. set_font и add_text — С осторожностью. output_pdf — Требуется подтверждение, в режиме base64 понижается до Проверки. В воркере вывод base64 — типичный путь, и он не добавляет шлюз (Уровни риска HITL).

JSON-обёртка шлюза подтверждения

Вывод воркера в формате base64:

{ "allowed": true }