Özel yazı tipleri: FontRegistry eklenti sözleşmesi

Bir bakışta

FontRegistryInterface, yazı tiplerini kaydetmek ve bulmak için süreç ömrü boyunca geçerli olan sözleşmeyi tanımlar. Yazı tiplerini bir dosya yolundan, bir dizinden veya ham ikili veriden kaydedin; ardından üretim çalışanlarının değiştirememesi için kayıt defterini kilitleyin.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Yazı tipi kayıt defteri, her Document örneğinden daha uzun yaşayan bir singleton’dır. Yalnızca saf PHP verisi saklar; kaynak tutamaçları veya uzantı nesneleri içermez. Bu nedenle onu uzun ömürlü bir çalışanda istekler arasında paylaşabilirsiniz.

Üç kayıt yolundan birini kullanın:

Bir dosyadan. register(), bir .ttf, .otf, .ttc veya .pfb dosyasını ayrıştırır ve meta verileri döndürür. Bir TrueType Collection için alt yazı tipi dizinini geçirin.
Bir dizinden. addFontDirectory(), motorun bir aileyi ada göre çözümlerken tarayacağı bir arama yolu ekler.
İkili veriden. registerFromBinary(), ham TrueType veya OpenType baytlarını ayrıştırır. @font-face köprüsü için bu yolu, yazı tipleri bir data: URI’sinden (Tekdüzen Kaynak Tanımlayıcısı) veya uzak bir kaynaktan geldiğinde kullanın.

İlk istek gecikmesini azaltmak için çalışan açılışında warmup() çağrısıyla bir yazı tipi grubunu önceden ayrıştırın. Ardından lock() çağrısını yapın. lock() çağrısından sonra tüm değiştirme yöntemleri LogicException fırlatır: register(), addFontDirectory(), warmup(), registerBase14() ve registerFromBinary(). Arama yöntemleri kullanılabilir durumda kalır: get(), has(), all() ve getSearchDirectories(). Bu kilit, hiçbir isteğin paylaşılan yazı tipi kümesini değiştiremeyeceğini güvence altına alarak üretim çalışanlarını korur.

Çoğu durumda FontRegistryInterface arabirimini sizin uygulamanız gerekmez. Uygulamayı motor sağlar; siz yalnızca çağırırsınız. Yalnızca içerik adresli bir depo tarafından desteklenen özel bir yazı tipi çözümleme stratejisine ihtiyaç duyduğunuzda uygulayın. Her iki durumda da sınırı sözleşme belirler.

API yüzeyi

NextPDF\Contracts\FontRegistryInterface (kararlı, 1.7.0 sürümünden beri):

Yöntem	Döndürür	Amaç
`register(string $fontFile, string $alias, int $fontIndex)`	`FontInfo`	Bir yazı tipi dosyasını ayrıştırın ve kaydedin. Kayıt defteri kilitliyse veya dosya ayrıştırılamıyorsa fırlatır.
`registerFromBinary(string $fontData, string $alias)`	`FontInfo`	Ham TrueType veya OpenType baytlarından bir yazı tipi kaydedin.
`registerBase14(string $key, FontInfo $font)`	`void`	Önceden oluşturulmuş bir Base 14 standart yazı tipini kaydedin.
`addFontDirectory(string $directory)`	`void`	Bir yazı tipi arama dizini ekleyin.
`warmup(array $fontFiles)`	`void`	Çalışan açılışında bir yazı tipi grubunu önceden ayrıştırın.
`lock()`	`void`	Daha fazla değişikliği önlemek için kayıt defterini dondurun.
`isLocked()`	`bool`	Kayıt defterinin kilitli olup olmadığını bildirin.
`get(string $family, string $style)`	`FontInfo \| null`	Bir yazı tipini aile ve stile göre arayın.
`has(string $key)`	`bool`	Bir kayıt anahtarının var olup olmadığını denetleyin.
`all()`	`array<string, FontInfo>`	Kayıtlı her yazı tipini döndürün.
`getSearchDirectories()`	`list<string>`	Arama dizinlerini sırasıyla döndürün.
`memoryUsage()`	`MemoryReport`	Kayıt defterinin geçerli bellek kullanımını bildirin.

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

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

Kod örneği — üretim

Çalışan açılışında yazı tipi kümesini ısıtın, kayıt defterini kilitleyin ve lisans takibi için her yazı tipi yüklemesini gözlemleyin. Bu örnek yalnızca public türleri kullanır.

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

Sınır durumları ve tuzaklar

Kilitli kayıt defteri. lock() çağrısından sonra her değişiklik girişimi LogicException fırlatır. Yeniden kullanılan bir çalışanda koşullu ısıtma yapmadan önce isLocked() denetimini yapın.
İkili kayıt, anahtara göre önbelleğe alınmaz. registerFromBinary(), veriyi geçici bir dosyaya yazar ve dosyayı ayrıştırır. Döndürülen FontInfo değerini tutamaç olarak kullanın.
TrueType Collection (TTC) dizini. Bir TrueType Collection için register() yöntemine verilen üçüncü argüman alt yazı tipini seçer. Varsayılan 0 değeri ilk yüzü seçer.
Aile çözümlemesi. get(), bilinmeyen bir aile ve stil çifti için null döndürür. Asla null olmayan bir sonuç varsaymayın.

Performans

warmup(), ayrıştırma maliyetini ilk istekten çalışan açılışına taşır. Kayıt defteri yöntemleri saf PHP verisi kullanır ve aramalar sabit zamanlı eşleme okumalarıdır. Bir çalışanın bellekte tutulan yazı tipi kümesini bellek bütçenize göre boyutlandırmak için memoryUsage() çağrısını yapın.

Güvenlik notları

Kayıtlı bir yazı tipi, Taşınabilir Belge Biçimi (PDF) içeriğine gömülebilir. Kayıttan önce yazı tipinin kaynağını doğrulayın. Saldırgan denetimindeki ikili veriyi boyut ve biçim denetimleri olmadan kaydetmeyin. Yazı tipi lisanslama uyumluluğunu zorunlu kılmak ve bir belgede hangi yüzlerin gömüldüğünü kaydetmek için FontLoadedEvent kancasını kullanın.

Uygunluk

Burada imzalama veya arşivleme ile ilgili herhangi bir normatif iddia yoktur. Yazı tipi gömme ve alt küme oluşturma, PDF 2.0 yazı tipi modeliyle uyumludur. Bu uyumluluğun sorumlusu dahili alt küme oluşturucudur; sözleşmenin kendisi değildir.

Ticari bağlam

NextPDF Enterprise, aynı FontRegistryInterface üzerine yazı tipi lisans tasdiki ve denetimli bir alt küme oluşturma politikası ekler. Sınırı sözleşme belirlediği için kayıt kodunuz tüm sürümlerde aynı şekilde çalışır.

Ayrıca bkz.

İlgili sözleşmeler ve modüller

Yazı tipi modülü başvurusu — kayıt defteri uygulaması, ayrıştırma ve alt küme oluşturmanın iç ayrıntıları.
Tipografi sözleşmeleri başvurusu — FontRegistryInterface için katalog girişi.
Eylem tetikleyicileri ve olay dinleyicileri — FontLoadedEvent ve dağıtıcı.
Özel yerleşim ve metin yakalama — kardeş çalışma zamanı strateji sözleşmesi.
SPI kararlılık kuralları — FontRegistryInterface için verilen arabirim taahhüdü.

Sözlük yazı tipi kayıt defteri, görüntü kayıt defteri ve olay dinleyicisi terimlerini tanımlar; kanonik tanımlar için yayımlanmış sözlüğe bakın.