Отслеживание событий жизненного цикла PDF при встраивании NextPDF Connect

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

Вы можете отслеживать события жизненного цикла PDF — создание документа, добавление страницы, загрузка шрифта, применение подписи, формирование вывода — и реагировать на них без создания подкласса документа. Это возможность, доступная при встраивании библиотеки, а не инструмент Connect. В удалённой транспортной поверхности Connect (Model Context Protocol (MCP) / REST / gRPC) нет инструмента для прослушивания событий. Отслеживать события можно только тогда, когда вы размещаете движок внутри процесса и подключаете диспетчер. На этой странице показана эта граница и приведён внутрипроцессный шаблон, чтобы вызывающая сторона не ожидала удалённого перехватчика.

Установка

composer require nextpdf/server

Используйте этот шаблон, когда ваше приложение встраивает движок и вызывает его напрямую из PHP, например из собственного серверного хоста. При работе через удалённый транспорт отслеживайте систему на границе транспорта с помощью телеметрии.

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

Движок генерирует события через диспетчер в стиле PSR-14. Вы создаёте провайдер слушателей и диспетчер, регистрируете слушателей по классу события, а затем подключаете диспетчер к документу. После этого события генерируются автоматически по мере построения документа. Когда диспетчер не подключён, система событий не добавляет накладных расходов: каждая точка отправки — это проверка на null. Классы разрешаются через сопоставление автозагрузки класс→файл (PSR-4 §3), и во всём примере кода объявлены строгие типы и соблюдается стандарт кодирования (PSR-12 §2.1).

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

Для перехватчиков событий не существует инструмента Connect. Каталог инструментов — это эталонный каталог, и таких инструментов в нём нет. Внутрипроцессную поверхность образуют классы событий движка (DocumentCreatedEvent, PageAddedEvent, FontLoadedEvent, SignatureAppliedEvent, EncryptionAppliedEvent, DocumentOutputEvent) вместе с провайдером слушателей и диспетчером. Инструменты, доступные через транспорт, зависят от установленного уровня, и перехватчики событий никогда не входят в их число.

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

<?php

declare(strict_types=1);

use NextPDF\Core\Document;
use NextPDF\Event\EventDispatcher;
use NextPDF\Event\ListenerProvider;
use NextPDF\Event\Document\DocumentCreatedEvent;
use NextPDF\Event\Document\PageAddedEvent;

$provider = new ListenerProvider();
$dispatcher = new EventDispatcher($provider);

$provider->addListener(
    DocumentCreatedEvent::class,
    static function (DocumentCreatedEvent $event): void {
        // react to creation
    },
);

$provider->addListener(
    PageAddedEvent::class,
    static function (PageAddedEvent $event): void {
        // react to a new page: $event->pageIndex
    },
);

$pdf = Document::createStandalone();
$pdf->setEventDispatcher($dispatcher);
$pdf->addPage()->setFont('Helvetica', '', 12)->cell(0, 10, 'Hello')->save('/tmp/out.pdf');

Пример кода — рабочая среда

Используйте эти распространённые внутрипроцессные шаблоны:

Ведение журнала аудита. Зарегистрируйте слушателя для базового класса события с низким приоритетом, чтобы он всегда выполнялся последним, и записывайте имя события и контекст.
Контроль лицензий и лимитов. Слушайте PageAddedEvent с высоким приоритетом. При превышении лимита страниц остановите распространение и выбросите типизированное исключение.
Постобработка. Слушайте DocumentOutputEvent, а затем преобразуйте байты PDF перед их возвратом.
Мониторинг безопасности. Слушайте SignatureAppliedEvent / EncryptionAppliedEvent и записывайте level/algorithm и флаги разрешений в журнал аудита.

Рекомендации по приоритетам: ≥1000 для проверок security/limit, 0 для обычных слушателей и ≤−1000 для audit/telemetry.

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

Недоступно через удалённый транспорт. Удалённый клиент MCP/REST/gRPC не может зарегистрировать слушателя, поэтому не описывайте удалённый перехватчик и не рассчитывайте на него.
Нулевые накладные расходы только без диспетчера. Подключение диспетчера добавляет затраты на его слушателей, поэтому делайте слушателей на горячем пути экономичными.
Управление распространением. Остановка распространения не даёт запуститься последующим слушателям, поэтому продуманно упорядочивайте их по приоритету.

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

Без диспетчера затраты равны нулю. При наличии слушателей затраты равны сумме их работы. Профиль создаваемых документов — structural.

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

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

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

Утверждение	Спецификация	Пункт	Идентификатор ссылки (reference_id)
Классы событий разрешаются через сопоставление автозагрузки.	PSR-4	§3
В примере кода объявлены строгие типы согласно стандарту.	PSR-12	§2.1

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

Неприменимо — система событий относится к Core и не входит в удалённую поверхность инструментов Connect.

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

Транспорт	Доступно	Примечания
MCP (stdio) — стандартный ввод-вывод	Нет	Инструмент для прослушивания событий не предоставляется.
REST	Нет	Конечной точки для прослушивания событий нет.
gRPC	Нет	RPC для прослушивания событий нет.
Внутрипроцессный (встраивание библиотеки)	Да	Шаблон диспетчера PSR-14, приведённый выше.

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

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

Неприменимо — здесь нет инструмента Connect, поэтому шлюз подтверждения не задействован. Хост обязан защищать любую внутрипроцессную постобработку, которая записывает файлы.

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

Неприменимо — вызова инструмента нет. (О шлюзе подтверждения для вызовов инструментов см. output-approval.)