NextPDF Connect'i gömülü kullanırken PDF yaşam döngüsü olaylarını gözlemleme

Bir bakışta

Belgeyi alt sınıflandırmadan PDF yaşam döngüsü olaylarını — belge oluşturuldu, sayfa eklendi, yazı tipi yüklendi, imza uygulandı, çıktı üretildi — gözlemleyebilir ve bunlara tepki verebilirsiniz. Bu, bir Connect aracı değil, bir kitaplık gömme yeteneğidir. Uzak Connect taşıma yüzeyi (Model Context Protocol (MCP) / REST / gRPC) hiçbir olay dinleyici aracı sunmaz. Olayları yalnızca motoru süreç içinde barındırıp bir sevk birimi bağladığınızda gözlemleyebilirsiniz. Bu sayfa söz konusu sınırı netleştirir ve süreç içi deseni açıkça gösterir; böylece çağıranlar uzak bir kanca beklemez.

Kurulum

composer require nextpdf/server

Uygulamanız motoru gömüp doğrudan PHP içinden, örneğin özel bir sunucu ana makinesinden çağırdığında bu deseni kullanın. Uzak bir taşıma katmanı üzerindeyseniz bunun yerine sistemi taşıma sınırında telemetri ile gözlemleyin.

Kavramsal genel bakış

Motor, olayları PSR-14 tarzı bir sevk birimi aracılığıyla tetikler. Bir dinleyici sağlayıcısı ve sevk birimi oluşturur, dinleyicileri olay sınıfına göre kaydeder ve ardından sevk birimini belgeye eklersiniz. Bundan sonra, belge oluşturuldukça olaylar otomatik olarak tetiklenir. Hiçbir sevk birimi eklenmediğinde, her sevk noktası bir null denetimi olduğundan olay sistemi ek maliyet getirmez. Sınıflar, otomatik yükleme sınıf→dosya eşlemesi (PSR-4 §3) aracılığıyla çözümlenir; tüm örnek kod katı tipleri bildirir ve kodlama standardını (PSR-12 §2.1) izler.

API yüzeyi

Olay kancaları için hiçbir Connect aracı yoktur. Araç kataloğu resmî kayıt kataloğudur ve bu katalogda böyle bir araç listelenmez. Süreç içi yüzey, dinleyici sağlayıcısı ve sevk birimiyle birlikte motorun olay sınıflarından oluşur (DocumentCreatedEvent, PageAddedEvent, FontLoadedEvent, SignatureAppliedEvent, EncryptionAppliedEvent, DocumentOutputEvent). Bir taşıma katmanı üzerinden kullanılabilen araçlar, kurulu katmana bağlıdır ve olay kancaları asla bunların arasında yer almaz.

Kod örneği — hızlı başlangıç

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

Kod örneği — üretim

Şu yaygın süreç içi desenleri kullanın:

Denetim günlüğü kaydı. Temel olay sınıfına, her zaman en son çalışacak düşük öncelikli bir dinleyici kaydedin; olay adını ve bağlamını günlüğe yazın.
Lisans/sınır uygulaması. PageAddedEvent olayını yüksek öncelikte dinleyin. Bir sayfa üst sınırı aşıldığında, yayılmayı durdurun ve tipli bir istisna fırlatın.
Son işleme. DocumentOutputEvent olayını dinleyin ve ardından PDF baytları döndürülmeden önce bunları dönüştürün.
Güvenlik izleme. SignatureAppliedEvent / EncryptionAppliedEvent olayını dinleyin ve level/algorithm ile izin bayraklarını bir denetim günlüğüne kaydedin.

Öncelik kılavuzu: security/limit denetimleri için ≥1000, normal dinleyiciler için 0 ve audit/telemetry için ≤−1000.

Uç durumlar ve dikkat edilecek noktalar

Uzak bir taşıma katmanı üzerinden kullanılamaz. Uzak bir MCP/REST/gRPC istemcisi bir dinleyici kaydedemez; bu nedenle uzak bir kancayı belgelemeyin veya beklemeyin.
Sıfır ek yük yalnızca sevk birimi olmadan geçerlidir. Bir sevk birimi eklemek, dinleyicilerinin maliyetini de getirir; bu nedenle sıcak yoldaki dinleyicileri düşük maliyetli tutun.
Yayılma denetimi. Yayılmayı durdurmak, sonraki dinleyicilerin çalışmasını engeller; bu nedenle öncelik sıralamasını bilinçli olarak yapın.

Performans

Sevk birimi olmadan maliyet sıfırdır. Dinleyiciler varken maliyet, onların yaptığı işin toplamıdır. Üretilen belgelerde profil structural biçimindedir.

Güvenlik notları

Dinleyiciler imzalama ve şifreleme olaylarını görebilir; bu nedenle her denetim alıcısını hassas bir bileşen olarak ele alın. Çıktı baytlarını değiştiren bir son işleme dinleyicisi bir güven noktasıdır; bu nedenle kapsamını en aza indirin ve gözden geçirilmiş halde tutun.

Uygunluk

İfade	Belirtim	Madde	reference_id
Olay sınıfları, otomatik yükleme eşlemesi aracılığıyla çözümlenir.	PSR-4	§3
Örnek kod, standarda uygun olarak katı tipleri bildirir.	PSR-12	§2.1

Ticari bağlam

Geçerli değil — olay sistemi Core’un parçasıdır ve uzak Connect araç yüzeyinin bir parçası değildir.

Taşıma katmanı kullanılabilirliği

Taşıma katmanı	Kullanılabilir	Notlar
MCP (stdio)	Hayır	Hiçbir olay dinleyici aracı sunulmaz.
REST	Hayır	Olay dinleyici uç noktası yoktur.
gRPC	Hayır	Olay dinleyici RPC’si yoktur.
Süreç içi (kitaplık gömme)	Evet	Yukarıdaki PSR-14 sevk birimi deseni.

Uzak dağıtımlarda, motor olay kancalarını beklemek yerine sistemi taşıma sınırında telemetriyle gözlemleyin.

HITL risk katmanı

Geçerli değil — burada hiçbir Connect aracı yoktur; bu nedenle onay kapısı devreye girmez. Ana makine, dosya yazan her türlü süreç içi son işlemeyi güvenceye almalıdır.

Onay kapısı JSON zarfı

Geçerli değil — hiçbir araç çağrısı yapılmaz. (Araç çağrısı denetimi için bkz. output-approval.)