Entwicklerschnittstellen

FG Performance stellt eine globale Facade FGPerformance als Alias für FUNCKGROUP\Performance\Facade bereit. Die API registriert Einträge in internen Registries, die von den jeweils aktivierten Modulen verarbeitet werden.

Projekt- und Autoload-Struktur

composer.json registriert den Namespace FUNCKGROUP\Performance\ per PSR-4 auf src/ und verlangt PHP 8.1 oder neuer. Der analysierte Distributionsstand enthält vendor/autoload.php; ein Composer-Lauf auf dem Zielsystem ist daher für diese Distribution nicht erforderlich.

Ein package.json ist im Projekt nicht vorhanden. Die beiden Frontend-Dateien assets/js/navigation-prefetch.js und assets/js/asset-loader.js werden direkt ausgeliefert.

Für die Pflege des eingebetteten FG Core ist das Composer-Script fg-core:sync vorhanden. Es ruft tools/sync-fg-core.php auf und kann die Quelle beziehungsweise das Ziel über FG_CORE_SOURCE, FG_CORE_PROJECT_ROOT und FG_CORE_TARGET beziehen. Diese Funktion ist für die Entwicklung beziehungsweise Paketpflege gedacht, nicht für den normalen Plugin-Betrieb.

Öffentliche Plugin-Konstanten

Die Hauptdatei definiert beim Laden des Plugins folgende Konstanten:

Konstante	Inhalt
FG_PERFORMANCE_VERSION	aktuelle Plugin-Version, in diesem Stand 1.1.1
FG_PERFORMANCE_FILE	absoluter Pfad zur Plugin-Hauptdatei
FG_PERFORMANCE_DIR	absoluter Pfad zum Plugin-Verzeichnis
FG_PERFORMANCE_URL	URL zum Plugin-Verzeichnis

Die eingebettete FG-Core-Laufzeit definiert zusätzlich Core-Konstanten. Diese gehören zur gemeinsamen FUNCKGROUP-Core-Infrastruktur und nicht zur eigentlichen Performance-API.

PHP-Facade

FGPerformance::preconnect()

Registriert einen externen Preconnect.

FGPerformance::preconnect('https://fonts.gstatic.com', true);

Parameter:

string $origin
bool $crossorigin = false

FGPerformance::dnsPrefetch()

FGPerformance::dnsPrefetch('https://images.example.com');

FGPerformance::preload()

FGPerformance::preload(
    get_stylesheet_directory_uri() . '/assets/hero.webp',
    'image',
    ['fetchpriority' => 'high']
);

Zulässige as-Werte sind image, font, style und script.

FGPerformance::preloadAttachment()

FGPerformance::preloadAttachment(123, 'large', [
    'fetchpriority' => 'high',
]);

WordPress liefert URL, srcset und sizes für die angegebene Attachment-ID und Bildgröße.

FGPerformance::scriptStrategy()

FGPerformance::scriptStrategy('theme-slider', 'defer');

Zulässige Strategien sind defer und async.

FGPerformance::registerAsset()

Viewport-Beispiel:

FGPerformance::registerAsset('gallery-assets', [
    'trigger' => 'viewport',
    'selector' => '.gallery',
    'root_margin' => '300px 0px',
    'styles' => [
        get_stylesheet_directory_uri() . '/assets/gallery.css',
    ],
    'scripts' => [
        get_stylesheet_directory_uri() . '/assets/gallery.js',
    ],
]);

Interaction-Beispiel:

FGPerformance::registerAsset('search-assets', [
    'trigger' => 'interaction',
    'selector' => '.site-search',
    'scripts' => [
        [
            'src' => get_stylesheet_directory_uri() . '/assets/search.js',
            'type' => 'module',
        ],
    ],
]);

Gültige Bundle-Eigenschaften:

Feld	Bedeutung
trigger	viewport oder interaction
selector	CSS-Selektor, maximal 500 Zeichen
styles	Liste von URLs oder Arrays mit href, optional media, crossorigin
scripts	Liste von URLs oder Arrays mit src, optional type = module, crossorigin
root_margin / rootMargin	nur bei viewport, Standard 200px 0px

FGPerformance::deferRender()

FGPerformance::deferRender('.long-content-section', 1200);

FGPerformance::exclude()

Registriert einen zusätzlichen Ausschluss für Speculative Navigation.

FGPerformance::exclude('/geschuetzter-bereich/*');

Performance Actions

fg_performance_register_modules

Typ: Action

Wird ausgeführt, nachdem die acht Standardmodule registriert wurden.

Parameter:

FUNCKGROUP\Performance\ModuleManager $module_manager

Beispiel mit einem minimalen zusätzlichen Modul:

add_action('fg_performance_register_modules', function (
    \FUNCKGROUP\Performance\ModuleManager $module_manager
): void {
    $module_manager->register(new class implements \FUNCKGROUP\Performance\Contracts\ModuleInterface {
        public function get_id(): string
        {
            return 'example_preconnect';
        }

        public function get_name(): string
        {
            return 'Example Preconnect';
        }

        public function get_description(): string
        {
            return 'Registriert einen zusätzlichen Preconnect.';
        }

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

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

        public function boot(): void
        {
            \FGPerformance::preconnect('https://cdn.example.com', true);
        }
    });
});

ModuleManager::register() akzeptiert Implementierungen von FUNCKGROUP\Performance\Contracts\ModuleInterface. Das Interface verlangt get_id(), get_name(), get_description(), is_available(), is_enabled() und boot().

Ein externes Modul muss FUNCKGROUP\Performance\Contracts\ModuleInterface implementieren.

fg_performance_loaded

Typ: Action

Wird nach dem Boot der Module und der optionalen Admin-Initialisierung ausgelöst.

Parameter:

FUNCKGROUP\Performance\Plugin $plugin

Speculative-Navigation-Filter

fg_performance_navigation_speculation_mode

Typ: Filter

Wert: auto, prefetch oder prerender.

add_filter('fg_performance_navigation_speculation_mode', function ($mode) {
    return 'prefetch';
});

fg_performance_navigation_prefetch_should_run

Steuert ausschließlich den Legacy-Fallback vor WordPress 6.8.

add_filter('fg_performance_navigation_prefetch_should_run', '__return_false');

fg_performance_navigation_prefetch_hover_delay

Standard: 120 Millisekunden

Begrenzung: 0 bis 1000.

fg_performance_navigation_prefetch_max_urls

Standard: 3

Begrenzung: 1 bis 20.

fg_performance_navigation_prefetch_excluded_paths

Erweitert die Pfade für WordPress-Core-Speculation-Rules.

add_filter('fg_performance_navigation_prefetch_excluded_paths', function (array $paths): array {
    $paths[] = '/intern/*';
    return $paths;
});

fg_performance_navigation_prefetch_fallback_excluded_paths

Erweitert die Wildcard-Pfade des Legacy-JavaScript-Fallbacks.

fg_performance_navigation_prefetch_sensitive_urls

Erweitert dynamisch sensible absolute URLs, die später in Ausschlusspfade umgewandelt werden.

Resource-Hints-Filter

fg_performance_resource_hints_preconnect

Filtert die registrierten Preconnect-Arrays vor Normalisierung.

add_filter('fg_performance_resource_hints_preconnect', function (array $entries): array {
    $entries[] = [
        'href' => 'https://cdn.example.com',
        'crossorigin' => 'anonymous',
    ];
    return $entries;
});

fg_performance_resource_hints_dns_prefetch

Filtert zusätzliche DNS-Prefetch-Arrays.

fg_performance_resource_hints_max_preconnect

Standard: 4, intern auf 1 bis 10 begrenzt.

fg_performance_resource_hints_max_dns_prefetch

Standard: 12, intern auf 1 bis 30 begrenzt.

Critical-Assets-Filter

fg_performance_critical_assets_preloads

Filtert die registrierten Preload-Arrays vor Normalisierung.

fg_performance_critical_assets_max_preloads

Standard: 8, intern auf 1 bis 20 begrenzt.

Asset-Loading-Filter

fg_performance_asset_loading_script_strategies

Filtert ein Array im Format handle => strategy.

add_filter('fg_performance_asset_loading_script_strategies', function (array $strategies): array {
    $strategies['theme-script'] = 'defer';
    return $strategies;
});

fg_performance_asset_loading_bundles

Filtert die registrierten Bundle-Konfigurationen.

fg_performance_asset_loading_max_bundles

Standard: 20, intern auf 1 bis 50 begrenzt.

Render-Optimization-Filter

fg_performance_render_optimization_entries

Filtert registrierte Render-Einträge.

fg_performance_render_optimization_max_entries

Standard: 20, intern auf 1 bis 50 begrenzt.

Service-Worker-Filter

fg_performance_service_worker_max_entries

Standard: 100, intern auf 1 bis 500 begrenzt.

fg_performance_service_worker_max_response_bytes

Standard: 10 * 1024 * 1024, intern auf 1 MiB bis 100 MiB begrenzt.

Browser-Cache- und Serverfilter

fg_performance_browser_cache_ttl

Standard: 2592000 Sekunden.

Der Wert wird intern auf 86400 bis 31536000 Sekunden begrenzt.

fg_performance_server_family

Filtert die erkannte Serverfamilie.

Parameter:

string $family
string $server_software

Zulässige Rückgabewerte:

apache
litespeed
openlitespeed
nginx
unknown

fg_performance_server_supports_htaccess

Parameter:

bool $supported
string $family
string $server_software

Damit kann eine projektspezifische Serverumgebung für die .htaccess-Verwaltung freigeschaltet oder gesperrt werden.

FG-Core-Statusfilter

Das eingebettete FG Core stellt unter anderem folgende Filter bereit:

• fg_core_status_reporting_enabled
• fg_core_status_endpoint
• fg_core_status_payload

Statusreporting kann zusätzlich über eine Konstante deaktiviert werden:

define('FG_CORE_STATUS_REPORTING', false);

Der Standard-Endpunkt kann vor dem Laden des Core ebenfalls per Konstante überschrieben werden:

define('FG_CORE_STATUS_ENDPOINT', 'https://status.example.com/endpoint');

fg_core_status_report_sent

Typ: Action

Wird nach einer erfolgreichen Statusübermittlung ausgelöst.

Parameter:

array $payload
array $response

Der zweite Parameter ist die erfolgreiche Response-Struktur der WordPress HTTP API. Für Integrationen kann sie mit den WordPress-Funktionen wp_remote_retrieve_*() ausgewertet werden.

fg_core_status_report_failed

Typ: Action

Wird bei einem Fehler der Statusübermittlung ausgelöst.

Parameter:

string $message
int $http_code

Weitere Details stehen unter Datenverarbeitung.

JavaScript Events

Conditional Asset Loading sendet folgende CustomEvents auf document:

fgperformance:assetload

document.addEventListener('fgperformance:assetload', (event) => {
  console.log(event.detail.id);
});

fgperformance:assetloaded

Wird nach erfolgreichem Laden aller Ressourcen eines Bundles ausgelöst.

fgperformance:asseterror

Enthält in event.detail die Bundle-ID und das Error-Objekt.

Nicht vorhandene öffentliche Schnittstellen

Der aktuelle Projektstand registriert keine eigenen:

• REST-API-Routen,
• AJAX-Endpunkte,
• WP-CLI-Kommandos.