Memantau peristiwa siklus hidup PDF saat menyematkan NextPDF Connect

Sekilas pandang

Anda dapat memantau dan merespons peristiwa siklus hidup PDF — dokumen dibuat, halaman ditambahkan, font dimuat, tanda tangan diterapkan, keluaran dihasilkan — tanpa membuat subkelas dokumen. Ini adalah kemampuan penyematan pustaka, bukan alat Connect. Permukaan transport Connect jarak jauh (Model Context Protocol (MCP) / REST / gRPC) tidak mengekspos alat pendengar peristiwa apa pun. Anda hanya dapat memantau peristiwa saat meng-host mesin secara in-process dan menyambungkan dispatcher. Halaman ini menjelaskan batas tersebut dan memperlihatkan pola in-process secara jelas, sehingga pemanggil tidak mengharapkan hook jarak jauh.

Pemasangan

composer require nextpdf/server

Gunakan pola ini saat aplikasi Anda menyematkan mesin dan memanggilnya langsung di PHP, misalnya dari host server khusus. Untuk transport jarak jauh, pantau sistem pada batas transport menggunakan telemetri sebagai gantinya.

Gambaran konseptual

Mesin memicu peristiwa melalui dispatcher bergaya PSR-14. Anda membuat penyedia pendengar dan dispatcher, mendaftarkan pendengar menurut kelas peristiwa, lalu melampirkan dispatcher ke dokumen. Setelah itu, peristiwa terpicu otomatis saat dokumen dibangun. Ketika tidak ada dispatcher yang dilampirkan, sistem peristiwa menambahkan biaya nol karena setiap titik dispatch hanya pemeriksaan null. Kelas-kelas diselesaikan melalui pemetaan autoload kelas→berkas (PSR-4 §3), dan semua kode contoh mendeklarasikan tipe ketat serta mengikuti standar pengodean (PSR-12 §2.1).

Permukaan API

Tidak ada alat Connect untuk hook peristiwa. Katalog alat adalah acuan, dan tidak mencantumkan alat semacam itu. Permukaan in-process terdiri dari kelas-kelas peristiwa milik mesin (DocumentCreatedEvent, PageAddedEvent, FontLoadedEvent, SignatureAppliedEvent, EncryptionAppliedEvent, DocumentOutputEvent) bersama penyedia pendengar dan dispatcher. Alat yang tersedia melalui suatu transport bergantung pada tingkatan yang terpasang, dan hook peristiwa tidak pernah termasuk di antaranya.

Contoh kode — Memulai cepat

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

Contoh kode — Produksi

Gunakan pola umum in-process berikut:

Pencatatan audit. Daftarkan pendengar untuk kelas peristiwa dasar dengan prioritas rendah agar selalu dijalankan terakhir, lalu catat nama peristiwa dan konteksnya.
Penegakan lisensi/batas. Dengarkan PageAddedEvent dengan prioritas tinggi. Jika jumlah halaman melewati batas, hentikan propagasi dan lemparkan eksepsi bertipe.
Pascapemrosesan. Dengarkan DocumentOutputEvent, lalu transformasikan byte PDF sebelum byte tersebut dikembalikan.
Pemantauan keamanan. Dengarkan SignatureAppliedEvent / EncryptionAppliedEvent, lalu catat level/algorithm dan flag izin ke dalam log audit.

Panduan prioritas: ≥1000 untuk pemeriksaan security/limit, 0 untuk pendengar biasa, dan ≤−1000 untuk audit/telemetry.

Kasus tepi & jebakan

Tidak tersedia melalui transport jarak jauh. Klien MCP/REST/gRPC jarak jauh tidak dapat mendaftarkan pendengar, jadi jangan mendokumentasikan atau mengharapkan hook jarak jauh.
Tanpa overhead hanya jika tidak ada dispatcher. Melampirkan dispatcher menambah biaya pendengarnya, jadi pastikan pendengar pada jalur yang sering dilalui tetap murah.
Kontrol propagasi. Menghentikan propagasi mencegah pendengar berikutnya berjalan, jadi atur urutannya berdasarkan prioritas secara cermat.

Kinerja

Tanpa dispatcher, biayanya nol. Dengan pendengar, biayanya merupakan akumulasi pekerjaan para pendengar. Profilnya adalah structural untuk dokumen yang dihasilkan.

Catatan keamanan

Pendengar dapat melihat peristiwa penandatanganan dan enkripsi, jadi perlakukan setiap sink audit sebagai data sensitif. Pendengar pascapemrosesan yang mengubah byte keluaran merupakan titik kepercayaan, jadi jaga cakupannya tetap minimal dan pastikan ditinjau.

Kesesuaian

Pernyataan	Spesifikasi	Klausa	reference_id
Kelas peristiwa diselesaikan melalui pemetaan autoload.	PSR-4	§3
Kode contoh mendeklarasikan tipe ketat sesuai standar.	PSR-12	§2.1

Konteks komersial

Tidak berlaku — sistem peristiwa ini merupakan bagian dari Core, bukan bagian dari permukaan alat Connect jarak jauh.

Ketersediaan transport

Transport	Tersedia	Catatan
MCP (stdio)	Tidak	Tidak ada alat pendengar peristiwa yang diekspos.
REST	Tidak	Tidak ada endpoint untuk pendengar peristiwa.
gRPC	Tidak	Tidak ada RPC untuk pendengar peristiwa.
In-process (penyematan pustaka)	Ya	Pola dispatcher PSR-14 di atas.

Untuk penyebaran jarak jauh, pantau pada batas transport menggunakan telemetri alih-alih mengharapkan hook peristiwa mesin.

Tingkat risiko HITL

Tidak berlaku — tidak ada alat Connect di sini, jadi gerbang konfirmasi tidak terlibat. Host harus mengamankan setiap pascapemrosesan in-process yang menulis berkas.

Amplop JSON gerbang konfirmasi

Tidak berlaku — tidak ada panggilan alat yang dilakukan. (Untuk gerbang panggilan alat, lihat output-approval.)