Obserwowanie zdarzeń cyklu życia PDF przy osadzaniu NextPDF Connect

W skrócie

Możesz obserwować zdarzenia cyklu życia PDF i reagować na nie — takie jak utworzenie dokumentu, dodanie strony, załadowanie czcionki, zastosowanie podpisu czy wytworzenie wyniku — bez tworzenia podklasy dokumentu. To funkcja osadzania biblioteki, a nie narzędzie Connect. Zdalna powierzchnia transportowa Connect (Model Context Protocol (MCP) / REST / gRPC) nie udostępnia żadnego narzędzia do nasłuchiwania zdarzeń. Zdarzenia obserwujesz tylko wtedy, gdy hostujesz silnik w procesie i podłączasz dyspozytora. Ta strona wyznacza tę granicę i jasno pokazuje wzorzec wewnątrzprocesowy, aby wywołujący nie zakładali istnienia zdalnego punktu zaczepienia.

Instalacja

composer require nextpdf/server

Użyj tego wzorca, gdy aplikacja osadza silnik i wywołuje go bezpośrednio w PHP, na przykład z własnego hosta serwerowego. W przypadku transportu zdalnego zamiast tego obserwuj system na granicy transportu za pomocą telemetrii.

Przegląd koncepcyjny

Silnik wyzwala zdarzenia za pośrednictwem dyspozytora w stylu PSR-14. Tworzysz dostawcę słuchaczy oraz dyspozytora, rejestrujesz słuchaczy według klasy zdarzenia, a następnie dołączasz dyspozytora do dokumentu. Od tego momentu zdarzenia są wyzwalane automatycznie w trakcie budowania dokumentu. Gdy nie dołączono dyspozytora, system zdarzeń nie generuje żadnego narzutu, ponieważ każdy punkt wysyłki wykonuje tylko sprawdzenie wartości null. Klasy są rozwiązywane za pomocą mapowania klasa→plik mechanizmu autoload (PSR-4 §3), a cały kod przykładowy deklaruje typy ścisłe i przestrzega standardu kodowania (PSR-12 §2.1).

Powierzchnia API

Nie ma żadnego narzędzia Connect dla punktów zaczepienia zdarzeń. Katalog narzędzi jest wiążącym katalogiem i żadnego takiego narzędzia nie wymienia. Powierzchnię wewnątrzprocesową tworzą klasy zdarzeń silnika (DocumentCreatedEvent, PageAddedEvent, FontLoadedEvent, SignatureAppliedEvent, EncryptionAppliedEvent, DocumentOutputEvent) wraz z dostawcą słuchaczy oraz dyspozytorem. Narzędzia dostępne za pośrednictwem transportu zależą od zainstalowanego poziomu, a punkty zaczepienia zdarzeń nigdy nie należą do tego zestawu.

Przykład kodu — szybki start

<?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');

Przykład kodu — produkcja

Użyj tych typowych wzorców wewnątrzprocesowych:

Rejestrowanie audytu. Zarejestruj słuchacza dla bazowej klasy zdarzeń z niskim priorytetem, aby zawsze uruchamiał się jako ostatni, i zapisuj nazwę oraz kontekst zdarzenia.
Egzekwowanie licencji/limitów. Nasłuchuj zdarzenia PageAddedEvent z wysokim priorytetem. Po przekroczeniu limitu stron zatrzymaj propagację i zgłoś typowany wyjątek.
Przetwarzanie końcowe. Nasłuchuj zdarzenia DocumentOutputEvent, a następnie przekształcaj bajty PDF, zanim zostaną zwrócone.
Monitorowanie bezpieczeństwa. Nasłuchuj zdarzeń SignatureAppliedEvent / EncryptionAppliedEvent i zapisuj w dzienniku audytu level/algorithm oraz flagi uprawnień.

Wytyczne dotyczące priorytetów: ≥1000 dla kontroli security/limit, 0 dla zwykłych słuchaczy oraz ≤−1000 dla audit/telemetry.

Przypadki brzegowe i pułapki

Niedostępne za pośrednictwem transportu zdalnego. Zdalny klient MCP/REST/gRPC nie może zarejestrować słuchacza, więc nie dokumentuj zdalnego punktu zaczepienia ani go nie oczekuj.
Zerowy narzut tylko bez dyspozytora. Dołączenie dyspozytora dodaje koszt jego słuchaczy, więc na ścieżce krytycznej utrzymuj ich koszt na niskim poziomie.
Kontrola propagacji. Zatrzymanie propagacji uniemożliwia uruchomienie późniejszych słuchaczy, więc świadomie porządkuj je według priorytetu.

Wydajność

Bez dyspozytora koszt wynosi zero. Przy słuchaczach koszt odpowiada sumie wykonanej przez nich pracy. Profil dla wytworzonych dokumentów to structural.

Uwagi dotyczące bezpieczeństwa

Słuchacze mogą widzieć zdarzenia podpisywania i szyfrowania, więc traktuj każdy odbiornik audytu jako komponent poufny. Słuchacz przetwarzania końcowego, który modyfikuje bajty wyjściowe, jest punktem zaufania, więc ogranicz go do minimum i poddawaj przeglądom.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula	reference_id
Klasy zdarzeń są rozwiązywane za pomocą mapowania mechanizmu autoload.	PSR-4	§3
Kod przykładowy deklaruje typy ścisłe zgodnie ze standardem.	PSR-12	§2.1

Kontekst komercyjny

Nie dotyczy — system zdarzeń należy do Core i nie jest częścią zdalnej powierzchni narzędziowej Connect.

Dostępność transportu

Transport	Dostępne	Uwagi
MCP (stdio)	Nie	Nie udostępniono żadnego narzędzia do nasłuchiwania zdarzeń.
REST	Nie	Brak punktu końcowego do nasłuchiwania zdarzeń.
gRPC	Nie	Brak RPC do nasłuchiwania zdarzeń.
W procesie (osadzenie biblioteki)	Tak	Powyższy wzorzec dyspozytora PSR-14.

W przypadku wdrożeń zdalnych obserwuj na granicy transportu za pomocą telemetrii zamiast oczekiwać punktów zaczepienia zdarzeń silnika.

Poziom ryzyka HITL

Nie dotyczy — nie ma tu żadnego narzędzia Connect, więc bramka potwierdzenia nie uczestniczy w przepływie. Host musi zabezpieczyć każde wewnątrzprocesowe przetwarzanie końcowe, które zapisuje pliki.

Koperta JSON bramki potwierdzenia

Nie dotyczy — nie jest wykonywane żadne wywołanie narzędzia. (Informacje na temat bramkowania wywołań narzędzi znajdziesz w output-approval.)