Aangepaste lettertypen: het uitbreidingscontract voor FontRegistry

In een oogopslag

FontRegistryInterface definieert het procesbrede contract waarmee je lettertypen registreert en opzoekt. Registreer lettertypen vanuit een bestandspad, een directory of ruwe binaire gegevens en vergrendel het register daarna, zodat productieworkers het niet kunnen wijzigen.

Installeren

composer require nextpdf/core:^3

Conceptueel overzicht

Het lettertyperegister is een singleton die langer bestaat dan afzonderlijke Document-instanties. Het bewaart alleen pure PHP-gegevens, zonder resourcehandles of extensieobjecten, zodat je het in een langlopende worker tussen verzoeken kunt delen.

Gebruik een van de drie registratieroutes:

Vanuit een bestand. register() verwerkt een .ttf-, .otf-, .ttc- of .pfb-bestand en geeft metadata terug. Geef voor een TrueType Collection de subfont-index op.
Vanuit een directory. addFontDirectory() voegt een zoekpad toe dat de engine doorzoekt wanneer die een familie op naam moet oplossen.
Vanuit binaire gegevens. registerFromBinary() verwerkt ruwe TrueType- of OpenType-bytes. Gebruik deze route voor de @font-face-brug als lettertypen afkomstig zijn uit een data: Uniform Resource Identifier (URI) of van een externe bron.

Roep warmup() aan wanneer de worker opstart om een batch lettertypen vooraf te verwerken en zo de latentie van het eerste verzoek te verlagen. Roep daarna lock() aan. Na lock() werpt elke wijzigingsmethode LogicException: register(), addFontDirectory(), warmup(), registerBase14() en registerFromBinary(). Opzoekmethoden blijven beschikbaar: get(), has(), all() en getSearchDirectories(). Deze vergrendeling beschermt productieworkers doordat geen enkel verzoek de gedeelde lettertypeset kan wijzigen.

In de meeste gevallen implementeer je FontRegistryInterface niet zelf. De engine levert de implementatie; jij roept die alleen aan. Implementeer de interface alleen wanneer je een aangepaste strategie voor lettertyperesolutie nodig hebt, zoals een strategie die wordt ondersteund door een content-addressed store. In beide gevallen blijft het contract de grens.

API-oppervlak

NextPDF\Contracts\FontRegistryInterface (stabiel, sinds 1.7.0):

Methode	Retourneert	Doel
`register(string $fontFile, string $alias, int $fontIndex)`	`FontInfo`	Verwerkt en registreert een lettertypebestand. Werpt een uitzondering bij een vergrendeld register of een bestand dat niet kan worden verwerkt.
`registerFromBinary(string $fontData, string $alias)`	`FontInfo`	Registreer een lettertype op basis van ruwe TrueType- of OpenType-bytes.
`registerBase14(string $key, FontInfo $font)`	`void`	Registreer een vooraf opgebouwd Base 14-standaardlettertype.
`addFontDirectory(string $directory)`	`void`	Voegt een zoekdirectory voor lettertypen toe.
`warmup(array $fontFiles)`	`void`	Verwerkt een batch lettertypen vooraf bij het opstarten van de worker.
`lock()`	`void`	Bevriest het register om verdere wijzigingen te voorkomen.
`isLocked()`	`bool`	Geeft aan of het register is vergrendeld.
`get(string $family, string $style)`	`FontInfo \| null`	Zoek een lettertype op familie en stijl.
`has(string $key)`	`bool`	Controleer of een registratiesleutel bestaat.
`all()`	`array<string, FontInfo>`	Geeft alle geregistreerde lettertypen terug.
`getSearchDirectories()`	`list<string>`	Geeft de zoekdirectory’s in volgorde terug.
`memoryUsage()`	`MemoryReport`	Rapporteer het huidige geheugengebruik van het register.

Codevoorbeeld — Snel aan de slag

<?php

declare(strict_types=1);

use NextPDF\Contracts\FontRegistryInterface;

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

if (!$fonts->has('inter')) {
    throw new RuntimeException('Inter failed to register');
}

Codevoorbeeld — Productie

Warm de lettertypeset op wanneer de worker start, vergrendel het register en volg elke laadactie voor licentietracering. Dit voorbeeld gebruikt 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;
use Psr\Log\LoggerInterface;

final class FontWarmup
{
    /** @param list<string> $fontFiles */
    public function __construct(
        private readonly FontRegistryInterface $fonts,
        private readonly LoggerInterface $logger,
        private readonly array $fontFiles,
    ) {}

    public function boot(): EventDispatcher
    {
        $listeners = new ListenerProvider();
        $listeners->addListener(
            FontLoadedEvent::class,
            function (FontLoadedEvent $event): void {
                $this->logger->info('font.loaded', [
                    'family' => $event->family,
                    'style'  => $event->style,
                    'type'   => $event->fontType->name,
                ]);
            },
        );

        if (!$this->fonts->isLocked()) {
            $this->fonts->warmup($this->fontFiles);
            $this->fonts->lock();
        }

        return new EventDispatcher($listeners);
    }
}

Randgevallen en valkuilen

Vergrendeld register. Na lock() werpt elke wijziging LogicException. Controleer isLocked() voordat je een voorwaardelijke warmup uitvoert in een hergebruikte worker.
Binaire registratie wordt niet per sleutel gecachet. registerFromBinary() schrijft naar een tijdelijk bestand en verwerkt dat. Gebruik de teruggegeven FontInfo als handle.
TrueType Collection (TTC)-index. Voor een TrueType Collection selecteert het derde argument van register() het subfont. De standaardwaarde 0 selecteert de eerste face.
Familieresolutie. get() geeft null terug voor een onbekende combinatie van familie en stijl. Ga er nooit van uit dat het resultaat een waarde bevat.

Prestaties

warmup() verplaatst de verwerkingskosten van het eerste verzoek naar het opstarten van de worker. Registermethoden gebruiken pure PHP-gegevens en opzoekingen zijn lookups met constante tijd in een map. Roep memoryUsage() aan om de residente lettertypeset van een worker af te stemmen op je geheugenbudget.

Beveiligingsnotities

Een geregistreerd lettertype kan worden ingesloten in Portable Document Format (PDF)-inhoud. Valideer de herkomst van het lettertype vóór registratie. Registreer geen door een aanvaller beheerde binaire gegevens zonder controles op grootte en formaat. Gebruik de FontLoadedEvent-hook om naleving van lettertypelicenties af te dwingen en vast te leggen welke faces een document insluit.

Conformiteit

Er gelden geen normatieve claims voor ondertekening of archivering. Het insluiten en subsetten van lettertypen voldoet aan het lettertypemodel van PDF 2.0. De interne subsetter is verantwoordelijk voor die conformiteit; dit contract niet.

Commerciële context

NextPDF Enterprise voegt attestatie van lettertypelicenties en een geaudit subsetbeleid toe bovenop dezelfde FontRegistryInterface. Je registratiecode werkt in alle edities hetzelfde, omdat het contract de grens vormt.

Zie ook

Gerelateerde contracten en modules

Referentie van de Font-module — de implementatie van het register, de verwerking en de interne werking van subsetting.
Referentie van typografiecontracten — het catalogusitem voor FontRegistryInterface.
Actietriggers en event listeners — FontLoadedEvent en de dispatcher.
Aangepaste lay-out en tekstonderschepping — het verwante strategiecontract dat tijdens het renderen werkt.
Stabiliteitsregels voor de SPI — de interfacebelofte achter FontRegistryInterface.

De woordenlijst definieert font registry, image registry en event listener; raadpleeg de gepubliceerde woordenlijst voor de gezaghebbende definities.