Entwicklerschnittstellen

FG Image WP stellt eine statische PHP-Fassade unter FGImage bereit. Zusätzlich existieren WordPress Actions und Filter für Generierung, Frontend-Markup, Remote-Transport und Integrationen.

Die öffentliche API-Linie ist in Version 1.0.4 als FG_IMAGE_API_VERSION = '1.0' definiert.

Öffentliche PHP-API

Die Klasse FUNCKGROUP\Image\Facade wird beim Plugin-Boot als globale Klasse FGImage aliasiert.

Versions- und Capability-Informationen

$plugin_version = FGImage::pluginVersion();
$api_version = FGImage::apiVersion();
$enabled = FGImage::enabledFormats();
$webp_supported = FGImage::supports('webp');
$avif_supported = FGImage::supports('avif');

supports() akzeptiert nur webp und avif und berücksichtigt den effektiven Converter-Pfad aus lokalem Encoder und optionalem Remote-Fallback.

Varianten erzeugen und lesen

$result = FGImage::generateAttachment(123);

if (is_wp_error($result)) {
    error_log($result->get_error_message());
}

$metadata = FGImage::variants(123);
$health = FGImage::variantHealth(123);

generateAttachment() liefert einen Report oder WP_Error. variants() liefert die gespeicherten _fg_image_variants als Array.

Reparieren und löschen

$repair = FGImage::repairVariants(123);
$deleted_count = FGImage::deleteVariants(123);

deleteVariants() entfernt registrierte Variantendateien und das FG-Image-Attachment-Meta, nicht die Originaldatei.

Frontend-API

if (FGImage::frontendEnabled()) {
    $picture = FGImage::renderPicture($img_html, 123, 'my_integration');
}

$preferred = FGImage::preferredSource(123, 'large');

preferredSource() liefert nur dann einen bevorzugten modernen Source, wenn die Frontend-Ausgabe aktiv ist und die erforderliche Variantenabdeckung vorhanden ist.

Diagnose und Integrationen

$integrations = FGImage::integrationStatus();
$cache_payload = FGImage::cacheInvalidationPayload(123);
$remote = FGImage::remoteStatus();
$production = FGImage::productionCheck();

Wichtige Konstanten

Konstante	Wert/Funktion
FG_IMAGE_VERSION	aktuelle Plugin-Version 1.0.4
FG_IMAGE_API_VERSION	öffentliche API-Linie 1.0
FG_IMAGE_FILE	Hauptdatei des Plugins
FG_IMAGE_DIR	Plugin-Verzeichnis
FG_IMAGE_URL	Plugin-Basis-URL
FG_IMAGE_REMOTE_ENDPOINT	optionaler Override für den Remote-Endpoint
FG_IMAGE_REMOTE_TOKEN	optionaler Override für den Remote-Bearer-Token
FG_CORE_STATUS_REPORTING	bei exakt false: Statuskommunikation des FG Core deaktivieren
FG_CORE_STATUS_ENDPOINT	optionaler Override des FG-Core-Statusendpunkts

Varianten-Datenstruktur

Das Attachment-Metafeld _fg_image_variants verwendet aktuell Schema 2. Gekürzt sieht die Struktur so aus:

[
    'schema_version' => 2,
    'generated_at'   => 0,
    'plugin_version' => '1.0.4',
    'context'        => 'manual',
    'sizes'          => [
        'full' => [
            'source' => [
                'file'     => '2026/09/example.jpg',
                'mime'     => 'image/jpeg',
                'width'    => 1600,
                'height'   => 900,
                'filesize' => 0,
                'mtime'    => 0,
            ],
            'variants' => [
                'webp' => [
                    'file'            => '2026/09/example.webp',
                    'mime'            => 'image/webp',
                    'width'           => 1600,
                    'height'          => 900,
                    'filesize'        => 0,
                    'source_filesize' => 0,
                    'savings_percent' => 0.0,
                ],
            ],
        ],
    ],
]

Die Werte dienen als Schema-Beispiel; tatsächliche Dateinamen, Größen und Zahlen stammen aus dem jeweiligen Attachment. Externe Integrationen sollten diese Daten bevorzugt über FGImage::variants() lesen und nicht direkt verändern.

Hooks

Lifecycle- und Generierungs-Hooks

fg_image_loaded

Typ: Action
Parameter: FUNCKGROUP\Image\Plugin $plugin

Wird nach dem Boot der FG-Image-Komponenten ausgelöst.

add_action('fg_image_loaded', function ($plugin): void {
    // Integration initialisieren, nachdem FG Image geladen ist.
});

fg_image_upgraded

Typ: Action
Parameter: string $from_version, string $to_version, int $settings_schema

Wird nach einer Plugin-/Einstellungsmigration ausgelöst.

add_action('fg_image_upgraded', function (string $from, string $to, int $schema): void {
    error_log("FG Image: {$from} -> {$to}, schema {$schema}");
}, 10, 3);

fg_image_attachment_generated

Typ: Action
Parameter: int $attachment_id, array $report

Wird nach einem abgeschlossenen Generierungslauf ausgelöst.

add_action('fg_image_attachment_generated', function (int $attachment_id, array $report): void {
    $generated = (int) ($report['generated'] ?? 0);
}, 10, 2);

fg_image_attachment_generation_deferred

Typ: Action
Parameter: int $attachment_id, array $report

Wird ausgelöst, wenn ein paralleler Generierungslauf durch den Attachment-Lock zurückgestellt wird.

add_action('fg_image_attachment_generation_deferred', function (int $attachment_id, array $report): void {
    // Optionales Betriebslogging.
}, 10, 2);

fg_image_variants_changed

Typ: Action
Parameter: int $attachment_id, array $metadata

Wird beim Speichern oder vollständigen Leeren der registrierten Varianten ausgelöst.

add_action('fg_image_variants_changed', function (int $attachment_id, array $metadata): void {
    // Eigene abhängige Daten aktualisieren.
}, 10, 2);

fg_image_variants_repaired

Typ: Action
Parameter: int $attachment_id, array $report

Wird nach der Varianten-Prüfung/Reparatur ausgelöst.

add_action('fg_image_variants_repaired', function (int $attachment_id, array $report): void {
    $removed = (int) ($report['removed'] ?? 0);
}, 10, 2);

fg_image_automatic_generation_completed

Typ: Action
Parameter: int $attachment_id, array $report, string $context

Wird ausgelöst, wenn die automatische Verarbeitung nach WordPress-Metadatengenerierung erfolgreich bis zu einem Report durchgelaufen ist.

add_action('fg_image_automatic_generation_completed', function (int $id, array $report, string $context): void {
    // Automatische Verarbeitung beobachten.
}, 10, 3);

fg_image_automatic_generation_failed

Typ: Action
Parameter: int $attachment_id, WP_Error $error, string $context

Wird bei einem WP_Error oder einer abgefangenen Exception im automatischen Upload-Pfad ausgelöst.

add_action('fg_image_automatic_generation_failed', function (int $id, WP_Error $error, string $context): void {
    error_log($error->get_error_message());
}, 10, 3);

fg_image_source_mime_mismatch

Typ: Action
Parameter: string $path, string $declared_mime, string $detected_mime

Wird ausgelöst, wenn Metadaten-MIME und tatsächlich erkannter MIME-Typ voneinander abweichen.

add_action('fg_image_source_mime_mismatch', function (string $path, string $declared, string $detected): void {
    error_log("MIME mismatch: {$declared} -> {$detected} at {$path}");
}, 10, 3);

fg_image_attachment_variants_removed

Typ: Action
Parameter: int $attachment_id, int $deleted_count, string $context

Wird beim Lifecycle-bedingten Entfernen registrierter Varianten ausgelöst.

add_action('fg_image_attachment_variants_removed', function (int $id, int $deleted, string $context): void {
    // Beispielsweise eigene Derived-Assets invalidieren.
}, 10, 3);

fg_image_restore_generation_completed

Typ: Action
Parameter: int $attachment_id, array $report, string $context

Wird nach erfolgreicher Regenerierung bei einem Restore-Lifecycle ausgelöst.

add_action('fg_image_restore_generation_completed', function (int $id, array $report, string $context): void {
    // Restore-Regenerierung beobachten.
}, 10, 3);

fg_image_restore_generation_failed

Typ: Action
Parameter: int $attachment_id, WP_Error|Throwable $error, string $context

Wird ausgelöst, wenn die Regenerierung nach einem Restore fehlschlägt.

add_action('fg_image_restore_generation_failed', function (int $id, $error, string $context): void {
    $message = $error instanceof WP_Error ? $error->get_error_message() : $error->getMessage();
    error_log($message);
}, 10, 3);

fg_image_generation_lock_ttl

Typ: Filter
Parameter: int $ttl
Standard: 300; Ergebnis wird auf 30 bis 3600 Sekunden begrenzt.

add_filter('fg_image_generation_lock_ttl', static fn (int $ttl): int => 600);

fg_image_generation_time_limit

Typ: Filter
Parameter: int $target, string $context, int $current_limit
Standard: 120; Ergebnis wird auf 0 bis 600 Sekunden begrenzt.

add_filter('fg_image_generation_time_limit', function (int $target, string $context, int $current): int {
    return $context === 'batch' ? 180 : $target;
}, 10, 3);

fg_image_encoder_order

Typ: Filter
Parameter: array $backends, string $mime_type

Standardmäßig wird ['imagick', 'gd'] bevorzugt. Unbekannte oder nicht verfügbare Backends werden nicht zu funktionierenden Encodern.

add_filter('fg_image_encoder_order', function (array $backends, string $mime_type): array {
    return ['gd', 'imagick'];
}, 10, 2);

Batch-Hooks

fg_image_batch_size

Typ: Filter
Parameter: int $size
Standard: 1; Ergebnis wird auf 1 bis 20 begrenzt.

add_filter('fg_image_batch_size', static fn (int $size): int => 2);

fg_image_batch_started

Typ: Action
Parameter: int $user_id, array $state

add_action('fg_image_batch_started', function (int $user_id, array $state): void {
    // Batch-Start beobachten.
}, 10, 2);

fg_image_batch_progress

Typ: Action
Parameter: int $user_id, array $state

add_action('fg_image_batch_progress', function (int $user_id, array $state): void {
    // Zwischenstand auswerten.
}, 10, 2);

fg_image_batch_completed

Typ: Action
Parameter: int $user_id, array $state

add_action('fg_image_batch_completed', function (int $user_id, array $state): void {
    // Abschluss auswerten.
}, 10, 2);

fg_image_batch_reset

Typ: Action
Parameter: int $user_id

add_action('fg_image_batch_reset', function (int $user_id): void {
    // Eigene Batch-Begleitdaten entfernen.
});

Frontend-Hooks

fg_image_frontend_enabled

Typ: Filter
Parameter: bool $enabled, int $attachment_id, string $html

Kann die Frontend-Umschreibung für ein konkretes Attachment/Markup deaktivieren.

add_filter('fg_image_frontend_enabled', function (bool $enabled, int $attachment_id, string $html): bool {
    return $attachment_id === 123 ? false : $enabled;
}, 10, 3);

fg_image_picture_sources

Typ: Filter
Parameter: array $sources, int $attachment_id, string $html, string $context

Erhält die von FG Image ermittelten modernen Sources vor dem Rendern.

add_filter('fg_image_picture_sources', function (array $sources, int $attachment_id, string $html, string $context): array {
    return $sources;
}, 10, 4);

fg_image_variant_url

Typ: Filter
Parameter: string $variant_url, string $original_url, string $variant_basename

Geeignet für CDN-/Storage-URL-Rewrites.

add_filter('fg_image_variant_url', function (string $url, string $original, string $basename): string {
    return $url;
}, 10, 3);

fg_image_picture_html

Typ: Filter
Parameter: string $picture, string $original_html, int $attachment_id, string $context, array $sources

Filtert ein von FG Image neu erzeugtes <picture>.

add_filter('fg_image_picture_html', function (string $picture, string $original, int $id, string $context, array $sources): string {
    return $picture;
}, 10, 5);

fg_image_existing_picture_html

Typ: Filter
Parameter: string $picture, string $original_picture, int $attachment_id, string $context, array $used_sources

Filtert ein vorhandenes <picture>, nachdem FG Image es in-place erweitert hat.

add_filter('fg_image_existing_picture_html', function (string $picture, string $original, int $id, string $context, array $sources): string {
    return $picture;
}, 10, 5);

Remote-Hooks

fg_image_remote_endpoint

Typ: Filter
Parameter: string $endpoint

add_filter('fg_image_remote_endpoint', function (string $endpoint): string {
    return $endpoint;
});

fg_image_remote_allow_insecure_endpoint

Typ: Filter
Parameter: bool $allow, string $endpoint
Standard: false

Erlaubt einen HTTP-Endpoint ausdrücklich. Für Produktionsbetrieb ist HTTPS die vom Code vorgesehene Standardkonfiguration.

add_filter('fg_image_remote_allow_insecure_endpoint', function (bool $allow, string $endpoint): bool {
    return wp_get_environment_type() === 'local';
}, 10, 2);

fg_image_remote_request_args

Typ: Filter
Parameter: array $args, string $endpoint, string $source, string $mime_type, int $quality

Nach dem Filter erzwingt FG Image sicherheitsrelevante Request-Eigenschaften erneut.

add_filter('fg_image_remote_request_args', function (array $args, string $endpoint, string $source, string $mime, int $quality): array {
    $args['headers']['X-My-Integration'] = '1';
    return $args;
}, 10, 5);

Integrations-Hooks

fg_image_performance_preload_entry

Typ: Filter
Parameter: array $rewritten_entry, array $original_entry, int $attachment_id

Wird nach der Auswahl eines modernen Preload-Eintrags für FG Performance ausgeführt.

add_filter('fg_image_performance_preload_entry', function (array $rewritten, array $original, int $id): array {
    return $rewritten;
}, 10, 3);

fg_image_static_export_html

Typ: Filter
Parameter: string $html, array $context

Wird innerhalb des von FG Static Export bereitgestellten fg_static_export_html-Durchlaufs aufgerufen.

add_filter('fg_image_static_export_html', function (string $html, array $context): string {
    return $html;
}, 10, 2);

fg_image_cache_invalidation_requested

Typ: Action
Parameter: int $attachment_id, array $payload

Wird nach Änderungen an registrierten Varianten ausgelöst. FG Image selbst leert keinen Page Cache.

add_action('fg_image_cache_invalidation_requested', function (int $attachment_id, array $payload): void {
    $urls = (array) ($payload['variant_urls'] ?? []);
    // Cache-Plugin kann hier seinen eigenen Purge-Scope bestimmen.
}, 10, 2);

Der Payload enthält aktuell:

[
    'attachment_id'  => 123,
    'attachment_url' => '…',
    'has_variants'   => true,
    'variant_paths'  => ['…'],
    'variant_urls'   => ['…'],
    'reason'         => 'variants_changed', // oder variants_removed
    'plugin_version' => '1.0.4',
]

FG-Core-Status-Hooks

Die folgenden Hooks gehören zum eingebetteten, gemeinsam nutzbaren FG Core und nicht zur FG-Image-API-Linie. Sie sind für die Statuskommunikation relevant.

fg_core_status_reporting_enabled

Typ: Filter
Parameter: bool $enabled
Standard: true, sofern FG_CORE_STATUS_REPORTING nicht exakt false ist.

add_filter('fg_core_status_reporting_enabled', '__return_false');

fg_core_status_endpoint

Typ: Filter
Parameter: string $endpoint

add_filter('fg_core_status_endpoint', function (string $endpoint): string {
    return $endpoint;
});

fg_core_status_payload

Typ: Filter
Parameter: array $payload

add_filter('fg_core_status_payload', function (array $payload): array {
    return $payload;
});

fg_core_status_report_sent

Typ: Action
Parameter: array $payload, array $response

add_action('fg_core_status_report_sent', function (array $payload, $response): void {
    // Technischen Versandstatus beobachten.
}, 10, 2);

fg_core_status_report_failed

Typ: Action
Parameter: string $message, int $http_code

add_action('fg_core_status_report_failed', function (string $message, int $http_code): void {
    error_log("FG Core status failed ({$http_code}): {$message}");
}, 10, 2);

Keine REST-, AJAX- oder WP-CLI-API

FG Image WP 1.0.4 registriert im aktuellen Projekt keine eigenen REST-Routen, keine wp_ajax_*-Endpunkte und keine WP-CLI-Kommandos. Admin-Schreibaktionen verwenden admin-post.php.

Sicherheitsrelevante Eigenschaften für Integrationen

• Schreibende FG-Image-Adminaktionen prüfen manage_options und einen Nonce.
• Lokale Quell-/Variantenpfade werden gegen das aktuelle Upload-Verzeichnis validiert.
• Generierte und remote empfangene Dateien werden vor Aktivierung anhand des MIME-Typs geprüft.
• Remote-Bildrequests verwenden wp_safe_remote_post(), keine Cookies und keine Redirects; HTTPS-Zertifikatsprüfung wird bei HTTPS nach dem Filter erneut erzwungen.
• Fremde Integrationen sollten _fg_image_variants nicht direkt schreiben, sondern die öffentlichen Methoden/Hooks verwenden.