ArtisanPack UI
DocsVisual EditorFont Providers

Font Providers

Visual Editor v1.21.0

Status: v1.7.0 — Issue #629 A font provider is a source the Font Library can browse and install fonts from — Google Fonts, Bunny Fonts, custom...

Status: v1.7.0 — Issue #629

A font provider is a source the Font Library can browse and install fonts from — Google Fonts, Bunny Fonts, custom uploads, or any third-party catalog. Providers implement the FontProvider contract and are collected in the FontSourceRegistry. A package registers its own source through the ap.visualEditor.registerFontSources filter with no core changes.

This page documents the extensibility layer only (the contract, the registry, and the filter). Installation, storage, fonts.css generation, self-hosting/GDPR behavior, and the Font Library modal are covered in Fonts.


The FontProvider contract

ArtisanPackUI\VisualEditor\Fonts\Contracts\FontProvider

Method Returns Purpose
key() string Stable registry slug — persisted as a font's provider column. Must match /^[a-z][a-z0-9_-]*$/ (e.g. google, bunny, custom).
label() string Human-readable name shown in the modal. Wrap with __() so it localizes.
isSelfHostable() bool Whether faces can be fetched and served locally. Remote-only sources return false and the installer refuses them in v1.
searchCatalog(string $query, int $page = 1) array A page of catalog results. An empty $query browses the default listing.
getFamily(string $slug) ?array One family and its installable faces, or null when the slug is unknown.
fetchFace(string $slug, string $weight, string $style) string Raw font-file bytes (typically WOFF2) for a single face, written to the configured disk by the installer.

Payload shapes

searchCatalog() returns a page of family summaries:

[
    'families' => [
        ['slug' => 'inter', 'family' => 'Inter', 'category' => 'sans-serif'],
        // …
    ],
    'page'     => 1,
    'has_more' => true,
]

getFamily() returns a single family with its faces:

[
    'slug'        => 'inter',
    'family'      => 'Inter',
    'is_variable' => false,
    'faces'       => [
        ['weight' => '400', 'style' => 'normal'],
        ['weight' => '700', 'style' => 'normal'],
    ],
    // Variable fonts may add an 'axes' map.
]

The FontSourceRegistry

ArtisanPackUI\VisualEditor\Fonts\Registries\FontSourceRegistry

An in-memory store of providers keyed by FontProvider::key(), following the same conventions as BlockTypeRegistry.

Method Signature Notes
register register(FontProvider $provider): void Keys by $provider->key(). Re-registering a key replaces the previous provider (last write wins). Throws InvalidArgumentException on an empty or malformed key.
get get(string $key): ?FontProvider null when nothing is registered.
has has(string $key): bool
unregister unregister(string $key): void No-op when the key is absent.
all all(): array<string, FontProvider> Every provider, keyed by key.

The registry is bound as a singleton in the package service provider.


Registering a custom source

Implement FontProvider, then register it from your service provider's boot() by hooking the filter. The filter receives the registry and must return it:

use ArtisanPackUI\VisualEditor\Fonts\Registries\FontSourceRegistry;

addFilter(
    'ap.visualEditor.registerFontSources',
    function ( FontSourceRegistry $registry ): FontSourceRegistry {
        $registry->register( new FontshareProvider() );

        return $registry;
    }
);

The filter is layered over the registry with extend(), so it fires the first time the registry is resolved — after every provider has booted. Provider order does not matter: a source registered from any package's boot() is visible.

A non-FontSourceRegistry return value is ignored, so a misbehaving hook cannot break font sources.

Hook naming. The canonical hook name is camelCase (ap.visualEditor.registerFontSources), matching the ecosystem convention adopted in v1.5.0 (#664). See Hooks and Events for the full hook reference.


Worked example: a self-hosted catalog provider

A complete provider for a hosted catalog. It browses and resolves families over the provider's API and returns raw WOFF2 bytes from fetchFace() so the installer can self-host every face.

<?php

declare( strict_types=1 );

namespace App\Fonts;

use ArtisanPackUI\VisualEditor\Fonts\Contracts\FontProvider;
use Illuminate\Support\Facades\Http;

class FontshareProvider implements FontProvider
{
    public function key(): string
    {
        return 'fontshare';
    }

    public function label(): string
    {
        return __( 'Fontshare' );
    }

    public function isSelfHostable(): bool
    {
        return true;
    }

    public function searchCatalog( string $query, int $page = 1 ): array
    {
        $response = Http::get( 'https://api.fontshare.example/catalog', [
            'q'    => $query,
            'page' => $page,
        ] )->json();

        return [
            'families' => array_map( static fn ( array $family ): array => [
                'slug'     => $family['id'],
                'family'   => $family['name'],
                'category' => $family['category'],
            ], $response['results'] ),
            'page'     => $page,
            'has_more' => $response['has_next'] ?? false,
        ];
    }

    public function getFamily( string $slug ): ?array
    {
        $family = Http::get( "https://api.fontshare.example/families/{$slug}" )->json();

        if ( null === $family ) {
            return null;
        }

        return [
            'slug'        => $slug,
            'family'      => $family['name'],
            'is_variable' => $family['variable'] ?? false,
            'faces'       => array_map( static fn ( array $face ): array => [
                'weight' => (string) $face['weight'],
                'style'  => $face['italic'] ? 'italic' : 'normal',
            ], $family['faces'] ),
        ];
    }

    public function fetchFace( string $slug, string $weight, string $style ): string
    {
        return Http::get( "https://cdn.fontshare.example/{$slug}/{$weight}-{$style}.woff2" )->body();
    }
}

Register it from a service provider's boot() exactly as shown above:

use App\Fonts\FontshareProvider;
use ArtisanPackUI\VisualEditor\Fonts\Registries\FontSourceRegistry;

addFilter( 'ap.visualEditor.registerFontSources', function ( FontSourceRegistry $registry ): FontSourceRegistry {
    $registry->register( new FontshareProvider() );

    return $registry;
} );

Because the provider reports isSelfHostable() === true, the installer calls fetchFace() for each selected face, verifies the returned bytes, and writes them to the configured disk — so visitors are served the fonts from your own domain. See Fonts for the self-hosting and GDPR behavior end to end.

Stay in the Loop

Monthly tips, tutorials and package updates — plus a free Quick Start cheat sheet.

Subscribe
Edit this page on GitHub