Uzantı yazımı: genel SPI'ye bakış

Bir bakışta

NextPDF, NextPDF\Contracts ve NextPDF\Event ad alanlarında küçük ve bilinçli olarak seçilmiş bir genel sözleşme kümesi sunar. Yazı tipi eklemek, metni yakalamak, belge yaşam döngüsünü gözlemlemek veya motoru çatallamadan kendi imzalama arka ucunuzu sağlamak için bu sözleşmeleri uygulayın.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

NextPDF, genel hizmet sağlayıcı arabirimini (SPI) dahili kodundan ayırır. SPI, uygulayabileceğiniz veya gözlemleyebileceğiniz türlerin kümesidir. Bunun dışındaki her şey özeldir ve önceden haber verilmeden değişebilir.

Genel SPI üç biçimde karşınıza çıkar:

Kayıt defteri sözleşmeleri. Bunlar, belge oluşturmadan önce doldurduğunuz ve işlem ömrü boyunca yaşayan hizmetlerdir; FontRegistryInterface ve ImageRegistryInterface arabirimleri başlıca örneklerdir. Varlıkları siz kaydedersiniz; motor bunları okur.
Strateji sözleşmeleri. Bunlar, motorun işleme sırasında çağırdığı tek görevli kancalardır. TextPreprocessorInterface yerleşim zamanındaki metin yakalamayı yönetir, HtmlSecurityPolicyInterface ise Hypertext Markup Language (HTML) özelliklerini denetler. Davranışı siz sağlarsınız; motor onu çağırır.
İmzalama sözleşmeleri. Bunlar kriptografik arka uçlardır. SignerInterface, HsmSignerInterface ve DeferredSignerInterface, anahtar koruyuculuğunu ve imza üretimini sağlamanıza olanak tanır. Motor, Cryptographic Message Syntax (CMS) yapısını oluşturur; anahtarı sizin kodunuz tutar.

Gözlem, NextPDF\Event içinde yer alan ve PHP Standard Recommendation 14 (PSR-14) ile uyumlu ayrı bir olay sistemiyle yönetilir. Yaşam döngüsü olayları; belge oluşturma, yeni sayfalar, yazı tipi yükleme, imzalama ve yazma işlemlerine tepki vermenize olanak tanır. Bunlar motorun davranışını değiştirmez.

Her sözleşmenin kaynak PHPDoc’unda bir @stability etiketi bulunur: stable, experimental veya deprecated. Etiket ile sözleşmeye özgü geriye dönük uyumluluk taahhüdü, ne kadar değişiklik beklemeniz gerektiğini belirtir. İlkenin tamamı için SPI kararlılık kuralları sayfasına bakın.

Neler genişletilebilir

Yetenek	Genel sözleşme	Kararlılık
Yazı tipi kaydı ve arama	`NextPDF\Contracts\FontRegistryInterface`	stable (1.7.0 sürümünden beri)
Görüntü önbelleğe alma ve kod çözme	`NextPDF\Contracts\ImageRegistryInterface`	stable (2.0.0 sürümünden beri)
Yerleşim zamanında metin yakalama	`NextPDF\Contracts\TextPreprocessorInterface`	stable (1.9.0 sürümünden beri)
HTML özellik denetimi	`NextPDF\Contracts\HtmlSecurityPolicyInterface`	stable (3.1.0 sürümünden beri)
Belge fabrikası bağlantısı	`NextPDF\Contracts\DocumentFactoryInterface`	stable (1.7.0 sürümünden beri)
Eşzamanlı imzalama	`NextPDF\Contracts\SignerInterface`	stable (1.0.0 sürümünden beri)
Donanım destekli imzalama	`NextPDF\Contracts\HsmSignerInterface`	stable (1.0.0 sürümünden beri)
Ertelenmiş ve toplu imzalama	`NextPDF\Contracts\DeferredSignerInterface`	experimental (3.0.0 sürümünden beri)
RFC 3161 zaman damgalama	`NextPDF\Contracts\TimestampProviderInterface`	experimental (3.0.0 sürümünden beri)
Yaşam döngüsü gözlemi	`NextPDF\Event\*` (PSR-14 uyumlu)	stable gönderici; experimental yükler

Neler genel değildir

Aşağıdaki türler dahili kabul edilir. Bunları içe aktarmayın, alt sınıflarını oluşturmayın veya bunlara bağımlı olmayın:

Şu NextPDF\Contracts ve NextPDF\Event ad alanlarının dışında kalan ve PHPDoc’unda bir @stability etiketi taşımayan herhangi bir sınıf.
HTML ayrıştırıcısı, yazıcı, yerleşim hattı ve yazı tipi alt küme oluşturucusu dahil olmak üzere somut motor kodu.
NextPDF Pro ve NextPDF Enterprise paketleri. Bunların dahili sınıfları açık kaynak yüzeyinin parçası değildir. Ücretli bir sürüm bir SPI uygulaması sunduğunda, o sürümün dahili türünü değil genel sözleşmeyi kullanın.

API yüzeyi

Üretilen sözleşmeler haritası yetkili kaynaktır ve her sürüm için kaynaktan yeniden oluşturulur. Her arabirim dosyasındaki @stability PHPDoc etiketini tek doğru kaynak olarak ele alın. Yukarıdaki tabloyu yalnızca okuma kılavuzu olarak kullanın.

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

Bir yazı tipi kaydedin, ardından yüklenmesini izleyin. Her iki adımda da yalnızca genel türler kullanılır.

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

Kod örneği — üretim

Uzun süre çalışan bir işçide, kayıt defterlerini önyükleme sırasında bir kez oluşturup kilitleyin ve belge fabrikası aracılığıyla paylaşılan bir gönderici enjekte edin.

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

Sınır durumları ve dikkat edilecek noktalar

Kayıt defteri kilidi. FontRegistryInterface::lock() çağrıldıktan sonra değiştirme yöntemleri LogicException oluşturur. Yalnızca ön ısıtma tamamlandıktan sonra kilitleyin.
Kararlılık uyuşmazlığı. Bir experimental sözleşme, bir küçük sürümde değişebilir. Üretimde bu sözleşmeye bağımlı olmadan önce belirtilen kararlılığı denetleyin.
Ad alanı disiplini. NextPDF\Contracts veya NextPDF\Event dışındaki ve @stability etiketi olmayan bir tür, teknik olarak public olsa bile dahilidir.

Performans

SPI, kullanılmadığında sıfır maliyetlidir. Bir olay sınıfı için hiçbir dinleyici bağlanmamışsa, olay göndericisi tek bir hasListeners() denetiminden hemen sonra geri döner. Kayıt defterleri yalın PHP verileri tutar ve ilk istekte oluşacak gecikmeyi dağıtmak için önyükleme sırasında ön ısıtmayı destekler.

Güvenlik notları

İmzalama sözleşmeleri, güvenlik açısından hassas bir yüzeydir. HsmSignerInterface, özel anahtarın donanım sınırından asla çıkmamasını gerektirir. Uygulamanız bu gereksinimi karşılamalıdır. Üçüncü taraf imzalama arka ucu sözleşmesi ve tehdit modeli için anahtar yönetim sistemi (KMS) sağlayıcı sözleşmesi sayfasına bakın.

Uygunluk

Bu genel bakış sayfasında hiçbir normatif iddiada bulunulmamıştır. PDF Advanced Electronic Signatures (PAdES) ve anahtar yönetimi dahil olmak üzere her sözleşmeye ilişkin uygunluk, ilgili SPI sayfalarında belgelenmiştir.

Ticari bağlam

NextPDF Pro ve NextPDF Enterprise, anahtar yönetim sistemi destekli imzalama dahil olmak üzere çeşitli imzalama ve doğrulama sözleşmelerinin üretim uygulamalarını sağlar. Siz genel sözleşmeye bağımlı kalırsınız; uygulamayı ilgili sürüm sağlar, böylece kodunuz sürümler arasında taşınabilir kalır.

Ayrıca bkz.

İlgili sözleşmeler ve modüller

Contracts modülü başvurusu — üretilen sözleşmeler haritasının tamamı.
İmzalama sözleşmeleri başvurusu — SignerInterface, HsmSignerInterface ve DeferredSignerInterface.
Güvenlik ilkesi sözleşmesi başvurusu — HtmlSecurityPolicyInterface ayrıntıları.
Event modülü başvurusu — yaşam döngüsü gözlem yüzeyi.
SPI kararlılık kuralları — her @stability etiketinin ardındaki değişiklik ilkesi.
KMS sağlayıcı sözleşmesi — imzalama arka ucu sözleşmesi ve tehdit modeli.

Sözlük, SPI, uzantı noktası, kararlılık etiketi ve geriye dönük uyumluluk taahhüdü terimlerini tanımlar; her kanonik tanım için yayımlanmış sözlüğe bakın.