إنشاء الامتدادات: نظرة عامة على واجهة SPI العامة

لمحة سريعة

توفّر ⁨NextPDF⁩ مجموعة صغيرة ومدروسة من العقود العامة في فضاءَي الأسماء NextPDF\Contracts وNextPDF\Event. نفِّذ هذه العقود لإضافة الخطوط، أو اعتراض النص، أو مراقبة دورة حياة المستند، أو توفير واجهة توقيع خلفية خاصة بك من دون تفريع المحرّك.

التثبيت

composer require nextpdf/core:^3

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

تفصل ⁨NextPDF⁩ واجهة موفِّر الخدمة (⁨SPI⁩) العامة الخاصة بها عن كودها الداخلي. واجهة ⁨SPI⁩ هي مجموعة الأنواع التي يمكنك تنفيذها أو مراقبتها. أما ما عدا ذلك فهو خاص وقد يتغيّر من دون إشعار.

تتخذ واجهة ⁨SPI⁩ العامة ثلاثة أشكال:

• عقود السجل. خدمات تمتد طوال عمر العملية وتملؤها قبل إنشاء المستندات؛ FontRegistryInterface وImageRegistryInterface هما المثالان الرئيسيان. سجِّل الأصول، فيقرؤها المحرّك.
• عقود الاستراتيجية. خطافات لمهمة واحدة يستدعيها المحرّك أثناء التصيير. يتولّى TextPreprocessorInterface اعتراض النص في وقت التخطيط، ويضبط HtmlSecurityPolicyInterface بوابة ميزات لغة ترميز النص التشعبي (⁨HTML⁩). أنت توفّر السلوك، والمحرّك يستدعيه.
• عقود التوقيع. واجهات تشفير خلفية. تتيح لك SignerInterface، وHsmSignerInterface، وDeferredSignerInterface توفير حفظ المفتاح وإنتاج التوقيع. يبني المحرّك بنية بناء جملة رسائل التشفير (⁨CMS⁩)، بينما يحتفظ كودك بالمفتاح.

يتولّى المراقبةَ نظامُ أحداث منفصل في NextPDF\Event، وهو متوافق مع توصية ⁨PHP⁩ المعيارية رقم 14 (⁨PSR-14⁩). تتيح لك أحداث دورة الحياة التفاعل مع إنشاء المستند، والصفحات الجديدة، وتحميل الخطوط، والتوقيع، والكتابة النهائية. لكنها لا تغيّر سلوك المحرّك.

يحمل كل عقد وسم @stability في تعليق ⁨PHPDoc⁩ المصدري الخاص به: stable، أو experimental، أو deprecated. يوضح لك هذا الوسم، مع وعد التوافق الخلفي لكل عقد، مقدار التغيير المتوقّع. راجِع قواعد استقرار واجهة ⁨SPI⁩ للاطلاع على السياسة الكاملة.

ما الذي يمكن توسعته

القدرة	العقد العام	الاستقرار
تسجيل الخطوط والبحث عنها	NextPDF\Contracts\FontRegistryInterface	مستقر (منذ 1.7.0)
تخزين الصور مؤقتًا وفك ترميزها	NextPDF\Contracts\ImageRegistryInterface	مستقر (منذ 2.0.0)
اعتراض النص في وقت التخطيط	NextPDF\Contracts\TextPreprocessorInterface	مستقر (منذ 1.9.0)
ضبط بوابة ميزات ⁨HTML⁩	NextPDF\Contracts\HtmlSecurityPolicyInterface	مستقر (منذ 3.1.0)
ربط مصنع المستندات	NextPDF\Contracts\DocumentFactoryInterface	مستقر (منذ 1.7.0)
التوقيع المتزامن	NextPDF\Contracts\SignerInterface	مستقر (منذ 1.0.0)
التوقيع المدعوم بالعتاد	NextPDF\Contracts\HsmSignerInterface	مستقر (منذ 1.0.0)
التوقيع المؤجَّل والمجمَّع	NextPDF\Contracts\DeferredSignerInterface	تجريبي (منذ 3.0.0)
الختم الزمني وفق ⁨RFC 3161⁩	NextPDF\Contracts\TimestampProviderInterface	تجريبي (منذ 3.0.0)
مراقبة دورة الحياة	NextPDF\Event\* (متوافق مع ⁨PSR-14⁩)	موزِّع مستقر؛ حمولات تجريبية

ما الذي ليس عامًا

الأنواع التالية داخلية. لا تستوردها، ولا تشتقّ منها، ولا تعتمد عليها:

• أي صنف خارج فضاءَي الأسماء NextPDF\Contracts وNextPDF\Event، ما لم يحمل تعليق ⁨PHPDoc⁩ الخاص به وسم @stability.
• كود المحرّك الفعلي، بما في ذلك محلل ⁨HTML⁩، والكاتب، وخط أنابيب التخطيط، ومجزِّئ الخطوط.
• حزمتا ⁨NextPDF Pro⁩ و⁨NextPDF Enterprise.⁩ أصنافهما الداخلية ليست جزءًا من السطح مفتوح المصدر. عندما تشحن إصدارة مدفوعة تنفيذًا لواجهة ⁨SPI⁩، استهلك العقد العام، لا نوعه الداخلي.

سطح واجهة ⁨API⁩

خريطة العقود المولَّدة هي المرجع الموثوق، ويُعاد بناؤها من المصدر مع كل إصدارة. تعامَل مع وسم ⁨PHPDoc⁩ @stability في كل ملف واجهة على أنه المصدر الوحيد للحقيقة. استخدم الجدول أعلاه كوسيلة مساعدة على القراءة.

نموذج كود — بداية سريعة

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

<?php

declare(strict_types=1);

use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Event\Content\FontLoadedEvent;
use NextPDF\Event\EventDispatcher;
use NextPDF\Event\ListenerProvider;

/** @var FontRegistryInterface $fonts */
$fonts->register('/srv/fonts/Inter-Regular.ttf', 'Inter');

$listeners = new ListenerProvider();
$listeners->addListener(
    FontLoadedEvent::class,
    static function (FontLoadedEvent $event): void {
        \error_log("Font loaded: {$event->family} {$event->style}");
    },
);

$dispatcher = new EventDispatcher($listeners);

نموذج كود — الإنتاج

في عامل طويل التشغيل، ابنِ السجلات مرة واحدة عند الإقلاع، واقفلها، واحقن موزِّعًا مشتركًا عبر مصنع المستندات.

<?php

declare(strict_types=1);

use NextPDF\Contracts\DocumentFactoryInterface;
use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Event\EventDispatcher;
use NextPDF\Event\ListenerProvider;
use Psr\Log\LoggerInterface;

final class DocumentBootstrap
{
    public function __construct(
        private readonly FontRegistryInterface $fonts,
        private readonly DocumentFactoryInterface $factory,
        private readonly LoggerInterface $logger,
    ) {}

    public function warmup(): EventDispatcher
    {
        $this->fonts->warmup([
            '/srv/fonts/Inter-Regular.ttf',
            '/srv/fonts/Inter-Bold.ttf',
        ]);
        $this->fonts->lock();

        $listeners = new ListenerProvider();
        $listeners->addListener(
            \NextPDF\Event\Security\SignatureAppliedEvent::class,
            fn (object $event): mixed => $this->logger->info('Signature applied'),
        );

        return new EventDispatcher($listeners);
    }
}

حالات الحافة والمزالق

• قفل السجل. بعد FontRegistryInterface::lock()، تطرح طرق التغيير LogicException. اقفل السجل فقط بعد انتهاء التسخين.
• عدم تطابق الاستقرار. قد يتغيّر العقد experimental في إصدارة ثانوية. تحقّق من الاستقرار المعلن قبل أن تعتمد على العقد في الإنتاج.
• انضباط فضاء الأسماء. أي نوع خارج NextPDF\Contracts أو NextPDF\Event دون وسم @stability هو داخلي، حتى لو كان من الناحية التقنية public.

الأداء

تكلفة واجهة ⁨SPI⁩ معدومة عند عدم استخدامها. إذا لم يكن أي مستمع مرتبطًا بصنف حدث، يعود موزِّع الأحداث فورًا بعد فحص hasListeners() واحد. تحتفظ السجلات ببيانات ⁨PHP⁩ صرفة، وتدعم التسخين وقت الإقلاع لتوزيع زمن استجابة الطلب الأول.

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

عقود التوقيع هي السطح الحساس أمنيًا. يقتضي HsmSignerInterface ألّا يغادر المفتاح الخاص حدود العتاد أبدًا. يجب أن يحترم تنفيذك هذا المتطلب. راجِع عقد موفِّر نظام إدارة المفاتيح (⁨KMS⁩) للاطلاع على عقد واجهة التوقيع الخلفية الخاصة بطرف ثالث ونموذج تهديدها.

المطابقة

لا تُقدَّم أي ادعاءات معيارية في صفحة النظرة العامة هذه. مطابقة كل عقد، بما في ذلك التوقيعات الإلكترونية المتقدمة لـ ⁨PDF⁩ (⁨PAdES⁩) وإدارة المفاتيح، موثَّقة في صفحات واجهة ⁨SPI⁩ ذات الصلة.

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

توفّر ⁨NextPDF Pro⁩ و⁨NextPDF Enterprise⁩ تنفيذات إنتاجية لعدة عقود توقيع وتحقق، بما في ذلك التوقيع المدعوم بنظام إدارة المفاتيح. اعتمد على العقد العام بينما توفّر الإصدارة التنفيذ، ليبقى كودك قابلًا للنقل عبر الإصدارات.

انظر أيضًا

• قواعد استقرار واجهة ⁨SPI⁩
• الخطوط المخصّصة
• التخطيط المخصّص واعتراض النص
• مشغّلات الإجراءات ومستمعو الأحداث
• عقد موفِّر ⁨KMS⁩

العقود والوحدات ذات الصلة

• مرجع وحدة العقود — خريطة العقود المولَّدة الكاملة.
• مرجع عقود التوقيع — SignerInterface، وHsmSignerInterface، وDeferredSignerInterface.
• مرجع عقد سياسة الأمان — تفاصيل HtmlSecurityPolicyInterface.
• مرجع وحدة الأحداث — سطح مراقبة دورة الحياة.
• قواعد استقرار واجهة ⁨SPI⁩ — سياسة التغيير وراء كل وسم @stability.
• عقد موفِّر ⁨KMS⁩ — عقد واجهة التوقيع الخلفية ونموذج التهديد.

يعرّف المسرد ⁨SPI⁩، ونقطة الامتداد، ووسم الاستقرار، ووعد التوافق الخلفي؛ راجِع المسرد المنشور للحصول على كل تعريف قانوني.