Extensies schrijven: overzicht van de publieke SPI

In een oogopslag

NextPDF biedt een kleine, doelbewuste set publieke contracten in de namespaces NextPDF\Contracts en NextPDF\Event. Implementeer deze contracten om lettertypen toe te voegen, tekst te onderscheppen, de documentlevenscyclus te observeren of uw eigen ondertekeningsback-end te leveren zonder een fork van de engine te maken.

Installeren

composer require nextpdf/core:^3

Conceptueel overzicht

NextPDF scheidt zijn publieke service provider interface (SPI) van zijn interne code. De SPI is de verzameling typen die u kunt implementeren of observeren. Al het andere is privé en kan zonder kennisgeving wijzigen.

De publieke SPI kent drie vormen:

• Registrycontracten. Services die gedurende het hele proces bestaan en die u vult voordat u documenten aanmaakt; FontRegistryInterface en ImageRegistryInterface zijn de belangrijkste voorbeelden. U registreert de assets; de engine leest ze uit.
• Strategiecontracten. Hooks voor een enkele taak die de engine tijdens het renderen aanroept. TextPreprocessorInterface verzorgt het onderscheppen van tekst tijdens de lay-out, en HtmlSecurityPolicyInterface reguleert Hypertext Markup Language (HTML)-functies. U levert het gedrag; de engine roept het aan.
• Ondertekeningscontracten. Cryptografische back-ends. SignerInterface, HsmSignerInterface en DeferredSignerInterface stellen u in staat om sleutelbeheer en het produceren van handtekeningen te verzorgen. De engine bouwt de Cryptographic Message Syntax (CMS)-structuur, en uw code beheert de sleutel.

Voor observatie is er een afzonderlijk event-systeem in NextPDF\Event, compatibel met PHP Standard Recommendation 14 (PSR-14). Levenscyclus-events stellen u in staat te reageren op het aanmaken van documenten, nieuwe pagina’s, het laden van lettertypen, ondertekening en het wegschrijven. Ze wijzigen het gedrag van de engine niet.

Elk contract heeft een @stability-tag in de PHPDoc-broncode: stable, experimental of deprecated. De tag en de belofte van achterwaartse compatibiliteit per contract geven aan hoeveel verandering u kunt verwachten. Zie SPI-stabiliteitsregels voor het volledige beleid.

Wat uitbreidbaar is

Mogelijkheid	Publiek contract	Stabiliteit
Lettertype registreren en opzoeken	NextPDF\Contracts\FontRegistryInterface	stable (sinds 1.7.0)
Afbeelding cachen en decoderen	NextPDF\Contracts\ImageRegistryInterface	stable (sinds 2.0.0)
Tekst onderscheppen tijdens de lay-out	NextPDF\Contracts\TextPreprocessorInterface	stable (sinds 1.9.0)
HTML-functies reguleren	NextPDF\Contracts\HtmlSecurityPolicyInterface	stable (sinds 3.1.0)
Documentfactory bedraden	NextPDF\Contracts\DocumentFactoryInterface	stable (sinds 1.7.0)
Synchrone ondertekening	NextPDF\Contracts\SignerInterface	stable (sinds 1.0.0)
Hardwareondersteunde ondertekening	NextPDF\Contracts\HsmSignerInterface	stable (sinds 1.0.0)
Uitgestelde ondertekening en batchondertekening	NextPDF\Contracts\DeferredSignerInterface	experimental (sinds 3.0.0)
RFC 3161-tijdstempeling	NextPDF\Contracts\TimestampProviderInterface	experimental (sinds 3.0.0)
Observatie van de levenscyclus	NextPDF\Event\* (PSR-14-compatibel)	stable dispatcher; experimental payloads

Wat NIET publiek is

De volgende typen zijn intern. Importeer ze niet, maak er geen subklasse van en vertrouw er niet op:

• Elke klasse buiten de namespaces NextPDF\Contracts en NextPDF\Event, tenzij de PHPDoc ervan een @stability-tag bevat.
• Concrete enginecode, waaronder de HTML-parser, de writer, de lay-outpijplijn en de font-subsetter.
• De pakketten NextPDF Pro en NextPDF Enterprise. Hun interne klassen maken geen deel uit van het opensource-oppervlak. Wanneer een betaalde editie een SPI-implementatie levert, gebruikt u het publieke contract, niet het interne type ervan.

API-oppervlak

De gegenereerde contractenkaart is gezaghebbend en wordt voor elke release opnieuw uit de broncode opgebouwd. Beschouw de @stability-PHPDoc-tag in elk interfacebestand als de enige bron van waarheid. Gebruik de tabel hierboven als leeshulp.

Codevoorbeeld — Snelstart

Registreer een lettertype en observeer vervolgens wanneer het wordt geladen. Beide stappen gebruiken uitsluitend publieke 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);

Codevoorbeeld — Productie

Bouw in een langlopende worker de registries eenmalig op bij het opstarten, vergrendel ze en injecteer een gedeelde dispatcher via de documentfactory.

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

Randgevallen en valkuilen

• Registryvergrendeling. Na FontRegistryInterface::lock() gooien wijzigingsmethoden een LogicException. Vergrendel pas nadat de warmup is voltooid.
• Stabiliteitsmismatch. Een experimental contract kan in een minor release wijzigen. Controleer de vermelde stabiliteit voordat u in productie afhankelijk wordt van het contract.
• Namespace-discipline. Een type buiten NextPDF\Contracts of NextPDF\Event zonder @stability-tag is intern, ook al is het technisch gezien public.

Prestaties

De SPI brengt geen kosten met zich mee wanneer deze niet wordt gebruikt. Als er voor een event-klasse geen listener is gebonden, keert de event-dispatcher onmiddellijk terug na een enkele hasListeners()-controle. Registries bevatten pure PHP-gegevens en ondersteunen warmup bij het opstarten, zodat de latentie niet pas bij het eerste verzoek ontstaat.

Beveiligingsopmerkingen

De ondertekeningscontracten vormen het beveiligingsgevoelige oppervlak. HsmSignerInterface vereist dat de privésleutel de hardwaregrens nooit verlaat. Uw implementatie moet aan die eis voldoen. Zie het provider-contract voor het key management system (KMS) voor het contract van de externe ondertekenings-back-end en het bijbehorende dreigingsmodel.

Conformiteit

Op deze overzichtspagina worden geen normatieve uitspraken gedaan. De conformiteit per contract, waaronder PDF Advanced Electronic Signatures (PAdES) en sleutelbeheer, is gedocumenteerd op de betreffende SPI-pagina’s.

Commerciële context

NextPDF Pro en NextPDF Enterprise bieden productie-implementaties van diverse ondertekenings- en validatiecontracten, waaronder door een key management system ondersteunde ondertekening. Uw code leunt op het publieke contract; de editie levert de implementatie, zodat uw code portabel blijft tussen edities.

Zie ook

• SPI-stabiliteitsregels
• Aangepaste lettertypen
• Aangepaste lay-out en tekstonderschepping
• Actietriggers en event listeners
• KMS-providercontract

Gerelateerde contracten en modules

• Referentie van de Contracts-module — de volledige gegenereerde contractenkaart.
• Referentie van de ondertekeningscontracten — SignerInterface, HsmSignerInterface en DeferredSignerInterface.
• Referentie van het contract voor beveiligingsbeleid — detail van HtmlSecurityPolicyInterface.
• Referentie van de Event-module — het oppervlak waarmee u de levenscyclus observeert.
• SPI-stabiliteitsregels — het wijzigingsbeleid achter elke @stability-tag.
• KMS-providercontract — het contract van de ondertekenings-back-end en het dreigingsmodel.

De woordenlijst definieert SPI, uitbreidingspunt, stabiliteitstag en belofte van achterwaartse compatibiliteit; raadpleeg de gepubliceerde woordenlijst voor de canonieke definitie van elk begrip.