FFI\Exception — Klasse · PHP-Referenz

Signatur

class FFI\Exception extends \RuntimeException

Beschreibung

FFI\Exception ist die zentrale Ausnahmeklasse der PHP-FFI-Erweiterung (Foreign Function Interface). Sie wird geworfen, wenn bei der Interaktion mit nativen C-Bibliotheken oder beim Parsen von C-Deklarationen ein Fehler auftritt – zum Beispiel wenn eine Bibliothek nicht geladen werden kann, eine C-Typdefinition ungültig ist oder ein unzulässiger Speicherzugriff versucht wird.

Da FFI\Exception von \RuntimeException erbt, lässt sie sich mit einem normalen try/catch-Block abfangen. Alle Methoden der \RuntimeException-Klasse – wie getMessage(), getCode() oder getTrace() – stehen damit zur Verfügung.

Typische Situationen, in denen diese Ausnahme geworfen wird:

Aufruf von FFI::cdef() oder FFI::load() mit fehlerhafter C-Deklaration
Laden einer nicht vorhandenen oder nicht kompatiblen Shared Library
Verwendung von FFI::cast() mit inkompatiblen Typen
Zugriff auf ein undefiniertes Symbol in der geladenen Bibliothek

Es empfiehlt sich, FFI-Operationen grundsätzlich in try/catch-Blöcken zu kapseln, da Fehler in der nativen Ebene andernfalls unkontrolliert zu einem PHP-Fehler führen können.

Beispiele

Abfangen eines Fehlers beim Laden einer C-Bibliothek

<?php
try {
    $ffi = FFI::cdef(
        'int nicht_existierende_funktion(void);',
        'libNichtVorhanden.so'
    );
} catch (\FFI\Exception $e) {
    echo 'FFI-Fehler: ' . $e->getMessage() . PHP_EOL;
}

FFI-Fehler: Failed loading 'libNichtVorhanden.so'

Abfangen eines Fehlers bei ungültiger C-Deklaration

<?php
try {
    // Syntaxfehler in der C-Deklaration (fehlende schließende Klammer)
    $ffi = FFI::cdef('int foo(void;');
} catch (\FFI\Exception $e) {
    echo 'Ungültige Deklaration: ' . $e->getMessage() . PHP_EOL;
} catch (\Throwable $t) {
    echo 'Anderer Fehler: ' . $t->getMessage() . PHP_EOL;
}

Ungültige Deklaration: Failed parsing 'int foo(void;'

Typunsichere Cast-Operation abfangen

<?php
try {
    $ffi = FFI::cdef('typedef struct { int x; } Point;');
    $point = $ffi->new('Point');
    // Versuch, auf ein undefiniertes Feld zuzugreifen
    $value = $point->y;
} catch (\FFI\Exception $e) {
    echo 'FFI-Zugriffsfehler: ' . $e->getMessage() . PHP_EOL;
}

FFI-Zugriffsfehler: Attempt to read property "y" of non-object

// Wichtig · Fallstricke

Sicherheitshinweis: Die FFI-Erweiterung erlaubt direkten Zugriff auf nativen Speicher. Fehler, die nicht als FFI\Exception aufgefangen werden (z. B. Segmentation Faults auf C-Ebene), können den gesamten PHP-Prozess zum Absturz bringen und sind nicht durch PHP-Fehlerbehandlung abzufangen.

Ab PHP 8.0 ist FFI standardmäßig deaktiviert (ffi.enable=preload oder ffi.enable=true in der php.ini erforderlich). Wird FFI ohne korrekte Konfiguration verwendet, wird ebenfalls eine FFI\Exception geworfen.

Da FFI\Exception \RuntimeException erweitert, kann sie auch über catch (\RuntimeException $e) oder catch (\Exception $e) abgefangen werden – für eine präzise Fehlerbehandlung sollte jedoch explizit catch (\FFI\Exception $e) verwendet werden.

Siehe auch

FFI FFI::cdef FFI::load RuntimeException FFI\ParserException