Quan sát sự kiện vòng đời PDF khi nhúng NextPDF Connect

Tổng quan nhanh

Bạn có thể quan sát và phản ứng với các sự kiện vòng đời PDF — tài liệu được tạo, trang được thêm, phông chữ được nạp, chữ ký được áp dụng, kết quả được tạo ra — mà không cần kế thừa lớp tài liệu. Đây là khả năng nhúng thư viện, không phải một công cụ Connect. Bề mặt transport Connect từ xa (Model Context Protocol (MCP) / REST / gRPC) không cung cấp công cụ lắng nghe sự kiện nào. Bạn chỉ quan sát được sự kiện khi lưu trữ engine trong cùng tiến trình và kết nối bộ điều phối. Trang này xác định ranh giới đó và trình bày rõ mẫu thiết kế trong cùng tiến trình, để bên gọi không kỳ vọng vào một hook từ xa.

Cài đặt

composer require nextpdf/server

Hãy dùng mẫu này khi ứng dụng của bạn nhúng engine và gọi trực tiếp trong PHP, chẳng hạn từ một server host tùy chỉnh. Với một transport từ xa, thay vào đó hãy quan sát hệ thống tại ranh giới transport bằng telemetry.

Tổng quan khái niệm

Engine phát ra sự kiện thông qua một bộ điều phối theo mô hình PSR-14. Bạn tạo listener provider và bộ điều phối, đăng ký listener theo lớp sự kiện, rồi gắn bộ điều phối vào tài liệu. Từ đó, sự kiện tự động phát ra khi tài liệu được dựng lên. Khi không có bộ điều phối nào được gắn, hệ thống sự kiện không phát sinh chi phí vì mỗi điểm điều phối chỉ là một phép kiểm tra null. Các lớp được phân giải qua ánh xạ autoload class→file (PSR-4 §3), và toàn bộ mã mẫu đều khai báo strict type cũng như tuân theo chuẩn lập trình (PSR-12 §2.1).

Bề mặt API

Không có công cụ Connect nào dành cho event hook. Danh mục công cụ là danh mục chính thức và không liệt kê công cụ nào như vậy. Bề mặt trong cùng tiến trình chính là các lớp sự kiện của engine (DocumentCreatedEvent, PageAddedEvent, FontLoadedEvent, SignatureAppliedEvent, EncryptionAppliedEvent, DocumentOutputEvent) cùng với listener provider và bộ điều phối. Các công cụ khả dụng qua một transport phụ thuộc vào tier đã cài đặt, và event hook không bao giờ nằm trong số đó.

Mã ví dụ — bắt đầu nhanh

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

Mã ví dụ — sản xuất

Hãy dùng các mẫu thiết kế trong cùng tiến trình thường gặp sau:

Ghi nhật ký kiểm toán. Đăng ký listener trên lớp sự kiện cơ sở với độ ưu tiên thấp để listener luôn chạy sau cùng, rồi ghi lại tên sự kiện cùng ngữ cảnh.
Thực thi giấy phép/giới hạn. Lắng nghe trên PageAddedEvent với độ ưu tiên cao. Khi vượt quá giới hạn số trang, hãy dừng lan truyền và ném exception có kiểu.
Hậu xử lý. Lắng nghe trên DocumentOutputEvent, rồi biến đổi các byte PDF trước khi chúng được trả về.
Giám sát bảo mật. Lắng nghe trên SignatureAppliedEvent / EncryptionAppliedEvent, rồi ghi lại level/algorithm cùng các cờ quyền vào nhật ký kiểm toán.

Hướng dẫn độ ưu tiên: ≥1000 cho các phép kiểm tra security/limit, 0 cho listener thông thường, và ≤−1000 cho audit/telemetry.

Trường hợp biên & điểm cần lưu ý

Không khả dụng qua một transport từ xa. Một client MCP/REST/gRPC từ xa không thể đăng ký listener, vì vậy đừng tài liệu hóa hay kỳ vọng có một hook từ xa.
Chỉ không phát sinh chi phí khi không có bộ điều phối. Gắn một bộ điều phối sẽ thêm chi phí từ các listener của nó, vì vậy hãy giữ listener trên đường dẫn nóng thật nhẹ.
Kiểm soát lan truyền. Dừng lan truyền sẽ ngăn các listener phía sau chạy, vì vậy hãy sắp xếp thứ tự theo độ ưu tiên một cách có chủ ý.

Hiệu năng

Khi không có bộ điều phối, chi phí bằng không. Khi có listener, chi phí bằng tổng khối lượng công việc của chúng. Hồ sơ áp dụng là structural đối với các tài liệu được tạo ra.

Ghi chú bảo mật

Listener có thể thấy các sự kiện ký và mã hóa, vì vậy hãy coi mọi điểm thu thập nhật ký kiểm toán là nhạy cảm. Một listener hậu xử lý làm thay đổi các byte kết quả là một điểm tin cậy, vì vậy hãy giữ nó tối giản và được rà soát.

Tuân thủ

Phát biểu	Đặc tả	Điều khoản	reference_id
Các lớp sự kiện được phân giải qua ánh xạ autoload.	PSR-4	§3
Mã mẫu khai báo strict type theo chuẩn.	PSR-12	§2.1

Bối cảnh thương mại

Không áp dụng — hệ thống sự kiện thuộc Core và không phải là một phần của bề mặt công cụ Connect từ xa.

Tính khả dụng theo transport

Transport	Khả dụng	Ghi chú
MCP (stdio)	Không	Không cung cấp công cụ lắng nghe sự kiện nào.
REST	Không	Không có endpoint lắng nghe sự kiện.
gRPC	Không	Không có RPC để lắng nghe sự kiện.
Trong cùng tiến trình (nhúng thư viện)	Có	Mẫu bộ điều phối PSR-14 ở trên.

Với các triển khai từ xa, hãy quan sát tại ranh giới transport bằng telemetry thay vì kỳ vọng có event hook của engine.

Tier rủi ro HITL

Không áp dụng — ở đây không có công cụ Connect nào nên cổng xác nhận không liên quan. Host phải bảo vệ mọi tác vụ hậu xử lý trong cùng tiến trình có ghi tệp.

Gói JSON của cổng xác nhận

Không áp dụng — không thực hiện lời gọi công cụ nào. (Về kiểm soát lời gọi công cụ, xem output-approval.)