Erweiterungen entwickeln: Überblick über das öffentliche SPI

Auf einen Blick

NextPDF stellt einen kleinen, bewusst ausgewählten Satz öffentlicher Verträge bereit, die alle in den Namespaces NextPDF\Contracts und NextPDF\Event liegen. Wenn Sie diese Verträge implementieren, können Sie Schriften hinzufügen, Text abfangen, den Dokumentlebenszyklus beobachten oder Ihr eigenes Signatur-Back-End bereitstellen – ganz ohne die Engine zu forken.

Installation

composer require nextpdf/core:^3

Konzeptioneller Überblick

NextPDF trennt sein öffentliches Service-Provider-Interface (SPI) von seinem internen Code. Das SPI umfasst die Typen, die Sie implementieren oder beobachten dürfen. Alles andere ist privat und kann sich ohne Vorankündigung ändern.

Das öffentliche SPI hat drei Ausprägungen:

Registry-Verträge. Prozessweit lebende Dienste, die Sie befüllen, bevor Dokumente erstellt werden; FontRegistryInterface und ImageRegistryInterface sind die wichtigsten Beispiele. Sie registrieren die Assets, und die Engine liest sie.
Strategie-Verträge. Hooks für einen einzelnen Auftrag, die die Engine während eines Renderings aufruft. TextPreprocessorInterface übernimmt das Abfangen von Text zur Layout-Zeit, und HtmlSecurityPolicyInterface steuert den Zugriff auf HTML-Funktionen. Sie liefern das Verhalten, und die Engine führt es aus.
Signatur-Verträge. Kryptografische Back-Ends. Mit SignerInterface, HsmSignerInterface und DeferredSignerInterface können Sie Schlüsselverwahrung und Signaturerzeugung bereitstellen. Die Engine baut die CMS-Struktur auf, und Ihr Code hält den Schlüssel.

Ein separates, PSR-14-kompatibles Event-System in NextPDF\Event übernimmt die Beobachtung. Mit Lebenszyklus-Events können Sie auf Dokumenterstellung, eine neue Seite, das Laden von Schriften, das Signieren und das Schreiben reagieren. Sie ändern das Verhalten der Engine nicht.

Jeder Vertrag trägt im Quellcode in seinem PHPDoc ein @stability-Tag: stable, experimental oder deprecated. Dieses Tag und das vertragsbezogene Abwärtskompatibilitätsversprechen zeigen Ihnen, welche Änderungen Sie erwarten müssen. Die vollständige Richtlinie finden Sie unter SPI-Stabilitätsregeln.

Was erweiterbar ist

Fähigkeit	Öffentlicher Vertrag	Stabilität
Schriftregistrierung und Nachschlagen von Schriften	`NextPDF\Contracts\FontRegistryInterface`	stable (seit 1.7.0)
Bild-Caching und -Decodierung	`NextPDF\Contracts\ImageRegistryInterface`	stable (seit 2.0.0)
Abfangen von Text zur Layout-Zeit	`NextPDF\Contracts\TextPreprocessorInterface`	stable (seit 1.9.0)
Steuerung von HTML-Funktionen	`NextPDF\Contracts\HtmlSecurityPolicyInterface`	stable (seit 3.1.0)
Verdrahtung der Dokument-Factory	`NextPDF\Contracts\DocumentFactoryInterface`	stable (seit 1.7.0)
Synchrones Signieren	`NextPDF\Contracts\SignerInterface`	stable (seit 1.0.0)
Hardwaregestütztes Signieren	`NextPDF\Contracts\HsmSignerInterface`	stable (seit 1.0.0)
Aufgeschobenes und Batch-Signieren	`NextPDF\Contracts\DeferredSignerInterface`	experimental (seit 3.0.0)
RFC 3161-Zeitstempelung	`NextPDF\Contracts\TimestampProviderInterface`	experimental (seit 3.0.0)
Beobachtung des Lebenszyklus	`NextPDF\Event\*` (PSR-14-kompatibel)	stabiler Dispatcher; experimentelle Payloads

Was NICHT öffentlich ist

Folgendes ist intern. Importieren Sie es nicht, leiten Sie nicht davon ab und machen Sie sich nicht davon abhängig:

Jede Klasse außerhalb der Namespaces NextPDF\Contracts und NextPDF\Event, sofern deren PHPDoc kein @stability-Tag trägt.
Konkreter Engine-Code wie der HTML-Parser, der Writer, die Layout-Pipeline und der Schrift-Subsetter.
Die Pakete NextPDF Pro und NextPDF Enterprise. Ihre internen Klassen sind nicht Teil der Open-Source-Oberfläche. Wenn eine kostenpflichtige Edition eine SPI-Implementierung ausliefert, nutzen Sie den öffentlichen Vertrag, nicht ihren internen Typ.

API-Oberfläche

Die maßgebliche Liste ist die generierte Vertragskarte. Sie wird bei jedem Release aus dem Quellcode neu erzeugt. Behandeln Sie das PHPDoc-Tag @stability in jeder Interface-Datei als einzige Quelle der Wahrheit. Die oben stehende Tabelle dient als Lesehilfe.

Codebeispiel – Schnellstart

Registrieren Sie eine Schrift und beobachten Sie anschließend, wann sie geladen wird. Beide Schritte verwenden nur öffentliche Typen.

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

Codebeispiel – Produktion

In einem langlaufenden Worker bauen Sie die Registries einmal beim Start auf, sperren sie und injizieren über die Dokument-Factory einen gemeinsam genutzten Dispatcher.

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

Sonderfälle & Fallstricke

Registry-Sperre. Nach FontRegistryInterface::lock() werfen ändernde Methoden eine LogicException. Sperren Sie erst, wenn das Aufwärmen abgeschlossen ist.
Stabilitätsangabe. Ein Vertrag mit experimental kann sich in einem Minor-Release ändern. Prüfen Sie die angegebene Stabilität eines Vertrags, bevor Sie sich in der Produktion darauf verlassen.
Namespace-Disziplin. Ein Typ außerhalb von NextPDF\Contracts oder NextPDF\Event ohne @stability-Tag ist intern. Das gilt auch dann, wenn er technisch gesehen public ist.

Performance

Das SPI verursacht keinen Overhead, wenn es nicht genutzt wird. Wenn für eine Event-Klasse kein Listener gebunden ist, kehrt der Event-Dispatcher nach einer einzigen hasListeners()-Prüfung sofort zurück. Registries halten ausschließlich PHP-Daten und unterstützen ein Aufwärmen zur Startzeit, um die Latenz der ersten Anfrage zu verteilen.

Sicherheitshinweise

Die Signatur-Verträge sind die sicherheitskritische Oberfläche. HsmSignerInterface verlangt, dass der private Schlüssel die Hardwaregrenze niemals verlässt. Ihre Implementierung muss das einhalten. Den Vertrag für das Signatur-Back-End von Drittanbietern und sein Bedrohungsmodell finden Sie unter KMS-Provider-Vertrag.

Konformität

Auf dieser Überblicksseite werden keine normativen Aussagen getroffen. Die vertragsbezogene Konformität (PAdES, Schlüsselverwaltung) ist auf den jeweiligen SPI-Seiten dokumentiert.

Kommerzieller Kontext

NextPDF Pro und NextPDF Enterprise liefern produktionsreife Implementierungen mehrerer Signatur- und Validierungsverträge, darunter Signieren über ein Key-Management-System. Sie hängen vom öffentlichen Vertrag ab, während die Edition die Implementierung liefert, sodass Ihr Code über alle Editionen hinweg portabel bleibt.