NextPDF Connect를 임베딩할 때 PDF 라이프사이클 이벤트 관찰하기

한눈에 보기

문서를 서브클래싱하지 않아도 PDF 라이프사이클 이벤트(문서 생성, 페이지 추가, 폰트 로드, 서명 적용, 출력 생성)를 관찰하고 이에 반응할 수 있습니다. 이것은 라이브러리 임베딩 기능이며, Connect 도구가 아닙니다. 원격 Connect 전송 표면(MCP / REST / gRPC)은 이벤트 리스너 도구를 노출하지 않으므로, 엔진을 인프로세스로 호스팅하고 디스패처를 연결할 때에만 이벤트를 관찰합니다. 이 페이지는 그 경계와 인프로세스 패턴을 명확히 설명하여 호출자가 원격 훅을 기대하지 않도록 합니다.

설치

composer require nextpdf/server

이 패턴은 애플리케이션이 엔진을 임베딩하고 PHP에서 직접 호출하는 경우, 예를 들어 커스텀 서버 호스트에 적용됩니다. 원격 전송에서는 엔진 이벤트 훅 대신 전송 경계의 텔레메트리와 관찰 가능성을 우선 사용하십시오.

개념 개요

엔진은 PSR-14 스타일 디스패처를 통해 이벤트를 발생시킵니다. 리스너 프로바이더와 디스패처를 생성하고, 이벤트 클래스별로 리스너를 등록한 다음, 디스패처를 문서에 연결합니다. 이후 문서가 빌드되면서 이벤트가 자동으로 발생합니다. 디스패처가 연결되어 있지 않으면 모든 디스패치 지점에서 null 검사를 수행하므로, 이벤트 시스템은 추가 비용을 전혀 발생시키지 않습니다. 클래스는 오토로드 클래스→파일 매핑(PSR-4 §3)을 통해 해석되며, 모든 샘플 코드는 strict types를 선언하고 코딩 표준(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과 권한 플래그를 감사 로그에 기록합니다.

우선순위 기준: security/limit 검사는 ≥1000, 일반 리스너는 0, audit/telemetry는 ≤−1000을 사용합니다.

엣지 케이스 및 함정

원격 전송에서는 사용할 수 없음. 원격 MCP/REST/gRPC 클라이언트는 리스너를 등록할 수 없으므로, 원격 훅을 문서화하거나 기대하지 마십시오.
디스패처가 없을 때만 오버헤드 제로. 디스패처를 연결하면 리스너 비용이 추가되므로, 핫 패스 리스너는 가볍게 유지하십시오.
전파 제어. 전파를 중단하면 그 이후 리스너가 실행되지 않으므로, 우선순위를 신중하게 정렬하십시오.

성능

디스패처가 없으면 비용은 제로입니다. 리스너가 있으면 리스너 작업 비용이 합산됩니다. 생성된 문서의 프로파일은 structural입니다.

보안 참고 사항

리스너는 서명 및 암호화 이벤트를 볼 수 있으므로, 모든 감사 싱크를 민감한 대상으로 취급하십시오. 출력 바이트를 변경하는 후처리 리스너는 신뢰 지점이므로, 최소한으로 유지하고 검토하십시오.

적합성

진술	스펙	조항	reference_id
이벤트 클래스는 오토로드 매핑을 통해 해석됩니다.	PSR-4	§3
샘플 코드는 표준에 따라 strict types를 선언합니다.	PSR-12	§2.1

상업적 맥락

해당 없음 — 이벤트 시스템은 Core이며, 원격 Connect 도구 표면의 일부가 아닙니다.

전송 가용성

전송	사용 가능	참고
MCP (stdio)	아니요	이벤트 리스너 도구가 노출되지 않습니다.
REST	아니요	이벤트 리스너 엔드포인트가 없습니다.
gRPC	아니요	이벤트 리스너 RPC가 없습니다.
인프로세스(라이브러리 임베딩)	예	위의 PSR-14 디스패처 패턴.

원격 배포에서는 엔진 이벤트 훅을 기대하기보다 전송 경계의 텔레메트리로 관찰하십시오.

HITL 위험 등급

해당 없음 — 여기에는 Connect 도구가 없으므로, 확인 게이트가 관여하지 않습니다. 파일을 쓰는 인프로세스 후처리는 호스트가 자체적으로 보호해야 합니다.

확인 게이트 JSON 엔벨로프

해당 없음 — 도구 호출이 이루어지지 않습니다. (도구 호출 게이팅에 대해서는 output-approval을 참조하십시오.)