Creazione di estensioni: panoramica dell'SPI pubblica

In breve

NextPDF espone un insieme piccolo e mirato di contratti pubblici, tutti contenuti nei namespace NextPDF\Contracts e NextPDF\Event. Implementando questi contratti, è possibile aggiungere font, intercettare il testo, osservare il ciclo di vita del documento o fornire un proprio back end di firma, il tutto senza creare un fork del motore.

Installazione

composer require nextpdf/core:^3

Panoramica concettuale

NextPDF separa la propria service provider interface (SPI) pubblica dal codice interno. L’SPI è l’insieme dei tipi che possono essere implementati o osservati. Tutto il resto è privato e può cambiare senza preavviso.

L’SPI pubblica ha tre forme:

Contratti di registro. Servizi con durata pari a quella del processo, popolati prima della creazione dei documenti; FontRegistryInterface e ImageRegistryInterface ne sono gli esempi principali. Le risorse vengono registrate e il motore le legge.
Contratti di strategia. Hook con un singolo compito che il motore richiama durante il rendering. TextPreprocessorInterface gestisce l’intercettazione del testo in fase di impaginazione e HtmlSecurityPolicyInterface regola l’accesso alle funzionalità HTML. Si fornisce il comportamento e il motore ne pilota l’esecuzione.
Contratti di firma. Back end crittografici. SignerInterface, HsmSignerInterface e DeferredSignerInterface consentono di fornire la custodia delle chiavi e la produzione della firma. Il motore costruisce la struttura CMS e il codice utente detiene la chiave.

Un sistema di eventi separato, compatibile con PSR-14 e disponibile in NextPDF\Event, gestisce l’osservazione. Gli eventi del ciclo di vita consentono di reagire alla creazione del documento, a una nuova pagina, al caricamento dei font, alla firma e alla scrittura. Non modificano il comportamento del motore.

Ogni contratto include un tag @stability nel proprio PHPDoc di origine: stable, experimental o deprecated. Il tag, insieme alla promessa di compatibilità con le versioni precedenti specifica per ogni contratto, indica quanti cambiamenti aspettarsi. Per i criteri completi, consultare Regole di stabilità dell’SPI.

Cosa è estensibile

Funzionalità	Contratto pubblico	Stabilità
Registrazione e ricerca dei font	`NextPDF\Contracts\FontRegistryInterface`	stabile (da 1.7.0)
Memorizzazione nella cache e decodifica delle immagini	`NextPDF\Contracts\ImageRegistryInterface`	stabile (da 2.0.0)
Intercettazione del testo in fase di impaginazione	`NextPDF\Contracts\TextPreprocessorInterface`	stabile (da 1.9.0)
Controllo dell’accesso alle funzionalità HTML	`NextPDF\Contracts\HtmlSecurityPolicyInterface`	stabile (da 3.1.0)
Cablaggio della factory dei documenti	`NextPDF\Contracts\DocumentFactoryInterface`	stabile (da 1.7.0)
Firma sincrona	`NextPDF\Contracts\SignerInterface`	stabile (da 1.0.0)
Firma supportata da hardware	`NextPDF\Contracts\HsmSignerInterface`	stabile (da 1.0.0)
Firma differita e in batch	`NextPDF\Contracts\DeferredSignerInterface`	sperimentale (da 3.0.0)
Marcatura temporale RFC 3161	`NextPDF\Contracts\TimestampProviderInterface`	sperimentale (da 3.0.0)
Osservazione del ciclo di vita	`NextPDF\Event\*` (compatibile con PSR-14)	dispatcher stabile; payload sperimentali

Cosa NON è pubblico

I seguenti elementi sono interni. Non importarli, non estenderli e non dipendere da essi:

Qualsiasi classe esterna ai namespace NextPDF\Contracts e NextPDF\Event, a meno che il relativo PHPDoc non includa un tag @stability.
Implementazioni concrete del motore, come il parser HTML, il writer, la pipeline di impaginazione e il subsetter dei font.
I pacchetti NextPDF Pro e NextPDF Enterprise. Le loro classi interne non fanno parte della superficie open source. Quando un’edizione a pagamento distribuisce un’implementazione dell’SPI, utilizzare il contratto pubblico, non il tipo interno.

Superficie dell’API

L’elenco autorevole è la mappa dei contratti generata. Viene rigenerata dal codice sorgente a ogni release. Considerare il tag PHPDoc @stability in ogni file di interfaccia come l’unica fonte attendibile. La tabella precedente è un supporto alla lettura.

Esempio di codice — Avvio rapido

Registrare un font e poi osservare quando viene caricato. Entrambi i passaggi utilizzano esclusivamente tipi pubblici.

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

Esempio di codice — Produzione

In un worker a lunga esecuzione, creare i registri una sola volta all’avvio, bloccarli e iniettare un dispatcher condiviso tramite la factory dei documenti.

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

Casi limite e insidie

Blocco del registro. Dopo FontRegistryInterface::lock(), i metodi di modifica lanciano LogicException. Eseguire il blocco solo al termine del warmup.
Discordanza di stabilità. Un contratto experimental può cambiare in una release minore. Verificare la stabilità dichiarata di un contratto prima di dipendere da esso in produzione.
Disciplina dei namespace. Un tipo esterno a NextPDF\Contracts o NextPDF\Event privo di tag @stability è interno. Ciò vale anche se tecnicamente è public.

Prestazioni

L’SPI ha costo zero quando non viene utilizzata. Quando a una classe di evento non è associato alcun listener, il dispatcher di eventi restituisce immediatamente il controllo dopo un singolo controllo hasListeners(). I registri contengono dati PHP puri e supportano il warmup all’avvio, così da distribuire la latenza della prima richiesta.

Note sulla sicurezza

I contratti di firma rappresentano la superficie sensibile dal punto di vista della sicurezza. HsmSignerInterface richiede che la chiave privata non lasci mai il confine hardware. Una propria implementazione deve rispettare tale requisito. Per il contratto del back end di firma di terze parti e il relativo modello delle minacce, consultare il contratto del provider KMS.

Conformità

Questa pagina panoramica non contiene affermazioni normative. La conformità specifica per ogni contratto (PAdES, gestione delle chiavi) è documentata nelle relative pagine dell’SPI.

Contesto commerciale

NextPDF Pro e NextPDF Enterprise forniscono implementazioni di produzione di diversi contratti di firma e validazione, inclusa la firma supportata da un key management system. Il codice dipende dal contratto pubblico mentre l’edizione fornisce l’implementazione, in modo che rimanga portabile tra le edizioni.

Vedere anche

Contratti e moduli correlati

Riferimento del modulo Contracts — la mappa completa dei contratti generata.
Riferimento dei contratti di firma — SignerInterface, HsmSignerInterface e DeferredSignerInterface.
Riferimento del contratto per i criteri di sicurezza — dettagli di HtmlSecurityPolicyInterface.
Riferimento del modulo Event — la superficie di osservazione del ciclo di vita.
Regole di stabilità dell’SPI — i criteri di modifica alla base di ogni tag @stability.
Contratto del provider KMS — il contratto del back end di firma e il modello delle minacce.

Il glossario definisce SPI, extension point, stability tag e backward-compatibility promise; per le definizioni canoniche, consultare il glossario pubblicato.