مراقبة أحداث دورة حياة PDF أثناء تضمين NextPDF Connect

نظرة سريعة

يمكنك مراقبة أحداث دورة حياة ⁨PDF⁩ والتفاعل معها — إنشاء المستند، وإضافة صفحة، وتحميل خط، وتطبيق توقيع، وإنتاج المخرجات — من دون اشتقاق فئة فرعية من المستند. هذه إمكانة لتضمين المكتبة، وليست أداة ⁨Connect.⁩ لا يوفّر سطح نقل ⁨Connect⁩ البعيد (⁨Model Context Protocol⁩ (⁨MCP⁩) / ⁨REST⁩ / ⁨gRPC⁩) أي أداة لمستمع الأحداث. لا يمكنك مراقبة الأحداث إلا عند استضافة المحرك داخل العملية وربط موزّع. توضّح هذه الصفحة ذلك الحد وتعرض نمط العمل داخل العملية بوضوح، كي لا تتوقع الجهات المستدعية وجود خطاف بعيد.

التثبيت

composer require nextpdf/server

استخدم هذا النمط عندما يضمّن تطبيقك المحرك ويستدعيه مباشرةً في ⁨PHP⁩، مثلًا من مضيف خادم مخصص. أما عند استخدام نقل بعيد، فراقب النظام عند حد النقل باستخدام القياس عن بُعد بدلًا من ذلك.

نظرة مفاهيمية عامة

يُطلق المحرك الأحداث عبر موزّع وفق نمط ⁨PSR-14.⁩ أنشئ موفّر مستمعين وموزّعًا، وسجّل المستمعين حسب فئة الحدث، ثم اربط الموزّع بمستند. ومن تلك النقطة، تُطلَق الأحداث تلقائيًا أثناء بناء المستند. عند عدم ربط أي موزّع، لا يضيف نظام الأحداث أي تكلفة لأن كل نقطة توزيع لا تتجاوز فحص null. تُحلّ الفئات عبر تعيين التحميل التلقائي من فئة←ملف (⁨PSR-4⁩ §3)، وتعلن جميع الأمثلة البرمجية أنواعًا صارمة وتتبع معيار الترميز (⁨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⁩ وأعلام الصلاحيات في سجل تدقيق.

دليل الأولوية: ‏≥1000 لفحوص ⁨security/limit⁩، و0 للمستمعين العاديين، و≤−1000 لـ⁨audit/telemetry.⁩

الحالات الحدية والمزالق

غير متاح عبر نقل بعيد. لا يستطيع عميل ⁨MCP/REST/gRPC⁩ بعيد أن يسجّل مستمعًا، لذا لا توثّق خطافًا بعيدًا ولا تتوقعه.
انعدام الحمل الزائد يقتصر على غياب الموزّع. يضيف ربط الموزّع تكلفة مستمعيه، لذا أبقِ مستمعي المسار الساخن منخفضي التكلفة.
التحكم في الانتشار. يمنع إيقاف الانتشار المستمعين اللاحقين من العمل، لذا رتّب حسب الأولوية بتعمُّد.

الأداء

من دون موزّع، تكون التكلفة صفرًا. مع المستمعين، تساوي التكلفة مجموع عملهم. السمة التشغيلية structural للمستندات المنتَجة.

ملاحظات الأمان

يمكن للمستمعين رؤية أحداث التوقيع والتشفير، لذا تعامل مع كل وجهة تدقيق على أنها حساسة. مستمع المعالجة اللاحقة الذي يغيّر بايتات المخرجات هو نقطة ثقة، لذا أبقِه في أضيق نطاق ممكن وخاضعًا للمراجعة.

المطابقة

العبارة	المواصفة	البند	⁨reference_id⁩
تُحلّ فئات الأحداث عبر تعيين التحميل التلقائي.	⁨PSR-4⁩	§3
يعلن المثال البرمجي أنواعًا صارمة وفق المعيار.	⁨PSR-12⁩	§2.1

السياق التجاري

غير قابل للتطبيق — نظام الأحداث جزء من ⁨Core⁩، وهو ليس جزءًا من سطح أدوات ⁨Connect⁩ البعيد.

توفر النقل

النقل	متاح	ملاحظات
⁨MCP⁩ (⁨stdio⁩)	لا	لا تُكشف أي أداة لمستمع الأحداث.
⁨REST⁩	لا	لا توجد نقطة نهاية لمستمع الأحداث.
⁨gRPC⁩	لا	لا يوجد ⁨RPC⁩ لمستمع الأحداث.
داخل العملية (تضمين المكتبة)	نعم	نمط موزّع ⁨PSR-14⁩ الموضّح أعلاه.

في عمليات النشر البعيدة، راقب عند حد النقل باستخدام القياس عن بُعد بدلًا من توقع خطافات أحداث المحرك.

طبقة مخاطر ⁨HITL⁩

غير قابل للتطبيق — لا توجد أداة ⁨Connect⁩ هنا، لذا لا تتدخل بوابة التأكيد. يجب على المضيف حماية أي معالجة لاحقة داخل العملية عند كتابتها للملفات.

غلاف ⁨JSON⁩ لبوابة التأكيد

غير قابل للتطبيق — لا يُجرى أي استدعاء أداة. (لبوابة استدعاء الأدوات، انظر ⁨output-approval⁩.)