FFI in PHP für performancekritischen Code: native Bibliotheken einbinden

1. Was FFI ist und wann es sich lohnt

Die Foreign Function Interface, kurz FFI, ist seit PHP 7.4 fest im Sprachkern verankert und erlaubt es, Funktionen aus dynamisch gelinkten Bibliotheken direkt aus PHP-Code aufzurufen, ohne dafür eine eigene PHP-Erweiterung in C zu schreiben und zu kompilieren. Statt eines aufwendigen Build-Prozesses mit phpize, Autoconf und einer eigenen .so-Datei genügt eine Header-ähnliche Definition in PHP selbst, gegen die der Zend Engine zur Laufzeit die passenden Symbole aus einer bestehenden Bibliothek auflöst. Das senkt die Einstiegshürde für performancekritischen Code erheblich.

Sinnvoll ist FFI überall dort, wo eine native Bibliothek bereits existiert und lediglich aus PHP heraus angesprochen werden soll, etwa spezialisierte Bildverarbeitung, kryptografische Primitive, Kompressionsalgorithmen oder numerische Bibliotheken, die in reinem PHP um ein Vielfaches langsamer wären. FFI ersetzt in diesen Fällen keine PHP-Erweiterung, sondern den Umweg über einen externen Prozessaufruf per exec() oder proc_open(), der bei jedem Aufruf einen neuen Prozess startet und Daten über Textformate serialisiert.

Nicht sinnvoll ist FFI dort, wo die eigentliche Logik in PHP selbst liegt und lediglich algorithmisch ineffizient umgesetzt wurde. Bevor FFI in Erwägung gezogen wird, lohnt sich immer zuerst ein Blick auf Algorithmus, Datenstrukturen und mögliches Caching. Erst wenn diese Hausaufgaben erledigt sind und die verbleibende Rechenlast tatsächlich in nativer Geschwindigkeit gelöst werden muss, wird FFI zum richtigen Werkzeug für performancekritischen Code.

2. FFI aktivieren und die Header-Definition verstehen

FFI ist standardmäßig als Erweiterung in PHP enthalten, muss aber über php.ini aktiviert werden. Die Direktive ffi.enable steuert dabei genau, wo FFI-Code ausgeführt werden darf: "true" erlaubt es überall, "false" deaktiviert es vollständig, und "preload" erlaubt FFI ausschließlich in Skripten, die über den Preloader geladen wurden. Für Produktionsumgebungen ist "preload" die empfohlene Einstellung, weil sie verhindert, dass beliebiger, zur Laufzeit generierter Code native Symbole auflösen kann.

Der Kern jeder FFI-Nutzung ist die Header-Definition, ein String, der in einer C-ähnlichen Syntax die Signaturen der aufzurufenden Funktionen sowie eventuelle Structs beschreibt. Diese Definition wird nicht kompiliert, sondern von einem eingebauten Parser in der Zend Engine interpretiert, der daraus die passenden Aufrufkonventionen für die jeweilige Zielplattform ableitet. Fehler in dieser Definition führen nicht zu einem Compiler-Fehler, sondern zu Laufzeitfehlern beim ersten tatsächlichen Aufruf, weshalb sorgfältiges Testen der Definition unverzichtbar ist.

declare(strict_types=1);

// Minimal FFI setup: describe the C function signature and load libm
$ffi = FFI::cdef(<<<'CDEF'
    double sqrt(double x);
    double pow(double base, double exponent);
CDEF, 'libm.so.6');

// Call native math functions directly, no PHP userland implementation involved
$result = $ffi->sqrt(2.0);
printf("sqrt(2) via FFI: %.10f\n", $result);

$power = $ffi->pow(2.0, 10.0);
printf("2^10 via FFI: %.1f\n", $power);

3. Die erste native Funktion aus PHP aufrufen

Der einfachste Einstieg gelingt mit Funktionen aus bereits auf dem System vorhandenen Systembibliotheken wie libm oder libc, weil dort keine zusätzliche Installation notwendig ist. FFI::cdef() nimmt die Header-Definition als ersten Parameter und optional den Bibliotheksnamen als zweiten Parameter entgegen. Wird der zweite Parameter weggelassen, sucht FFI die Symbole im bereits geladenen Adressraum des PHP-Prozesses selbst, was für Aufrufe von Standardbibliotheksfunktionen häufig bereits ausreicht.

Nach erfolgreichem Aufruf von cdef() liefert FFI ein Objekt zurück, dessen Methoden und Eigenschaften exakt den in der Definition beschriebenen Funktionen und Structs entsprechen. Der Aufruf selbst, etwa $ffi->sqrt(2.0), sieht syntaktisch wie ein gewöhnlicher PHP-Methodenaufruf aus, springt intern aber direkt in nativen Maschinencode, ohne den Umweg über eine Zend-Opcode-Interpretation für die eigentliche Berechnung. Genau dieser direkte Sprung ist der Grund, warum FFI bei rechenintensiven Operationen spürbare Geschwindigkeitsvorteile gegenüber reinem PHP-Code bietet.

Ein wichtiger Unterschied zu gewöhnlichen PHP-Funktionsaufrufen: Typkonvertierungen zwischen PHP-Werten und den in der Definition deklarierten C-Typen erfolgen nicht automatisch in jedem Fall verlustfrei. Eine PHP-Ganzzahl, die eigentlich als float deklariert ist, wird stillschweigend konvertiert, was bei falscher Header-Definition zu subtilen, schwer auffindbaren Rundungsfehlern führen kann. Sorgfältiges Abgleichen der Typen zwischen PHP-Aufrufstelle und C-Definition ist deshalb Pflicht.

4. Datentypen und Speicherverwaltung über die Grenze

FFI überbrückt zwei grundverschiedene Speicherverwaltungsmodelle: PHP mit automatischer Referenzzählung und Garbage Collection auf der einen Seite, manuelles Speichermanagement auf C-Seite auf der anderen. Werte, die als einfache Skalare wie int, double oder char deklariert sind, werden bei jedem Aufruf automatisch zwischen den beiden Welten kopiert und benötigen keine manuelle Freigabe. Komplexere Strukturen wie Pointer auf allozierten Speicher verlangen dagegen explizite Verwaltung durch den PHP-Entwickler.

FFI::new() alloziert Speicher für einen in der Definition deklarierten Typ und gibt ein FFI-Datenobjekt zurück, über das lesend und schreibend auf den zugrundeliegenden Speicher zugegriffen werden kann. Wichtig: Dieser Speicher wird standardmäßig automatisch freigegeben, sobald das PHP-Objekt außer Scope gerät, es sei denn, owned: false wird explizit übergeben. Wer Speicher an eine C-Bibliothek übergibt, die selbst die Eigentümerschaft übernehmen soll, muss dieses Verhalten aktiv steuern, sonst entstehen Use-after-free-Fehler oder doppelte Freigaben.

declare(strict_types=1);

$ffi = FFI::cdef(<<<'CDEF'
    typedef struct {
        double x;
        double y;
    } Point;

    double distance(Point a, Point b);
CDEF);

// Allocate native memory for two Point structs, PHP owns and frees them
$a = $ffi->new('Point');
$a->x = 0.0;
$a->y = 0.0;

$b = $ffi->new('Point');
$b->x = 3.0;
$b->y = 4.0;

// Direct struct field access, no manual serialization required
echo $ffi->distance($a, $b), PHP_EOL; // 5.0, classic 3-4-5 triangle

5. Structs, Pointer und Arrays mit FFI verarbeiten

Structs sind das zentrale Werkzeug, um komplexe native Datenstrukturen aus PHP heraus abzubilden. Die Feldnamen und Typen einer Struct-Definition in FFI müssen exakt mit dem C-Header der Zielbibliothek übereinstimmen, inklusive der Reihenfolge der Felder, da diese das Speicherlayout und damit das sogenannte Padding beeinflusst. Ein falsch angeordnetes Struct-Feld führt nicht zu einem sofortigen Fehler, sondern zu falsch interpretierten Bytes an einer verschobenen Speicheradresse, was zu den schwerer diagnostizierbaren Fehlerklassen bei FFI zählt.

Arrays und Pointer werden in FFI über eine einheitliche Zugriffssyntax mit eckigen Klammern abgebildet, unabhängig davon, ob im Hintergrund ein echtes C-Array oder ein Pointer auf einen zusammenhängenden Speicherbereich liegt. FFI::cast() erlaubt es, einen bereits vorhandenen Pointer explizit in einen anderen Typ umzuinterpretieren, was insbesondere beim Arbeiten mit generischen void*-Rückgabewerten häufig gebraucht wird. Bei der Arbeit mit Arrays variabler Länge ist zusätzlich FFI::sizeof() hilfreich, um die tatsächliche Byte-Größe einer Struktur zur Laufzeit zu bestimmen, statt sie fest zu verdrahten.

Ein häufiges Praxismuster: Eine native Bibliothek liefert einen Pointer auf ein Array von Structs zurück, zusammen mit einer separaten Längenangabe. FFI bildet diesen Fall über FFI::cast('MeinStruct[10]', $pointer) ab, wobei die Länge entweder aus der Bibliotheks-Dokumentation oder einem separaten Rückgabewert bekannt sein muss, da FFI selbst keine automatische Bounds-Prüfung für rohe Pointer vornimmt.

6. FFI in Produktion: Preloading richtig konfigurieren

Das Parsen einer FFI-Header-Definition kostet bei jedem Request spürbar Zeit, insbesondere bei umfangreichen Definitionen mit vielen Structs und Funktionssignaturen. Für Produktionsumgebungen ist deshalb ffi.preload die entscheidende Konfigurationsoption: Sie verweist auf ein PHP-Skript, das beim Start des PHP-FPM-Masterprozesses genau einmal ausgeführt wird und die FFI-Definitionen bereits geparst und für alle nachfolgenden Worker-Prozesse im Shared Memory bereitstellt.

In diesem Preload-Skript werden die FFI-Objekte typischerweise in statischen Klasseneigenschaften oder globalen Variablen abgelegt, auf die dann während der eigentlichen Request-Bearbeitung zugegriffen wird. Wichtig dabei: ffi.enable muss auf "preload" gesetzt sein, damit FFI-Aufrufe außerhalb des Preload-Kontexts überhaupt funktionieren, sonst schlagen alle FFI-Zugriffe zur Laufzeit mit einer Sicherheitsausnahme fehl, selbst wenn das Preload-Skript selbst fehlerfrei durchläuft.

declare(strict_types=1);

// preload-ffi.php — referenced via opcache.preload in php.ini
final class NativeMath
{
    private static ?FFI $ffi = null;

    public static function instance(): FFI
    {
        return self::$ffi ??= FFI::cdef(
            file_get_contents(__DIR__ . '/libm.h'),
            'libm.so.6'
        );
    }
}

// Parsing happens once here, at master process startup
NativeMath::instance();

// php.ini:
// opcache.preload=/var/www/html/preload-ffi.php
// ffi.enable=preload

Ein häufiger Stolperstein bei Preloading ist die Annahme, FFI-Objekte könnten problemlos über Worker-Prozessgrenzen hinweg geteilt werden wie gewöhnliche PHP-Klassen. Tatsächlich funktioniert das reibungslos, solange ausschließlich die geparste Definition und die Funktionspointer geteilt werden, nicht aber allozierter Instanzspeicher, der pro Request neu über FFI::new() angefordert werden sollte, um Zustandslecks zwischen unabhängigen Requests zu vermeiden.

7. Performance messen: FFI gegen reines PHP

Der tatsächliche Geschwindigkeitsgewinn durch FFI hängt stark von der Art der Operation ab. Bei einfachen arithmetischen Operationen, die der Zend Engine bereits mit dem JIT-Compiler effizient übersetzt, ist der Unterschied gering bis vernachlässigbar. Bei rechenintensiven Schleifen, etwa Bildverarbeitung Pixel für Pixel oder kryptografischen Operationen mit vielen Iterationen, zeigt FFI dagegen häufig Geschwindigkeitsvorteile im niedrigen bis mittleren zweistelligen Faktorbereich gegenüber reinem PHP-Code.

Der Overhead pro einzelnem FFI-Funktionsaufruf, verursacht durch die Marshalling-Schicht zwischen Zend-Werten und C-Typen, ist nicht null. Bei sehr vielen kleinen Aufrufen in einer engen Schleife kann dieser Overhead den Geschwindigkeitsvorteil der eigentlichen nativen Berechnung teilweise wieder aufzehren. Das richtige Muster für performancekritischen Code ist deshalb, möglichst große Datenmengen in einem einzigen FFI-Aufruf zu verarbeiten, statt die Bibliothek in einer PHP-Schleife tausendfach mit kleinen Einzelwerten aufzurufen.

Für belastbare Zahlen empfiehlt sich immer eine eigene Messung mit hrtime(true) im konkreten Anwendungsfall, da generische Benchmark-Zahlen aus dem Internet selten die eigene Datenmenge, Hardware und PHP-Konfiguration widerspiegeln. Ein einfacher Vergleich zwischen einer reinen PHP-Implementierung und der FFI-Variante über realistische Datenmengen liefert verlässlichere Entscheidungsgrundlagen als jede pauschale Aussage über FFI-Performance.

8. Sicherheitsaspekte und typische Fallstricke

FFI hebelt einen zentralen Sicherheitsmechanismus von PHP aus: den automatischen Speicherschutz vor Buffer-Overflows und Typfehlern. Eine falsch dimensionierte Struct-Definition oder ein Zugriff außerhalb der allozierten Speichergrenzen führt bei FFI nicht zu einer PHP-Exception, sondern potenziell zu einem Segmentation Fault, der den gesamten PHP-Prozess und damit im Zweifel den kompletten Worker abstürzen lässt. Diese Fehlerklasse existiert bei reinem PHP-Code praktisch nicht.

Deshalb sollte FFI-Code niemals direkt mit ungeprüften Benutzereingaben arbeiten, insbesondere nicht bei Werten, die Speichergrößen oder Array-Längen beeinflussen. Eingaben müssen vor dem Erreichen der FFI-Schicht validiert und auf plausible Wertebereiche begrenzt werden. Ein zweiter häufiger Fallstrick betrifft String-Konvertierungen: PHP-Strings sind nicht automatisch Null-terminiert im C-Sinne an jeder Stelle, weshalb FFI::string() und explizite Null-Terminierung beim Erzeugen von C-Strings aus PHP-Strings sorgfältig beachtet werden müssen, um Off-by-one-Fehler zu vermeiden.

9. FFI im Vergleich zu Alternativen

FFI ist nicht die einzige Möglichkeit, native Performance in PHP zu erreichen. Ein direkter Vergleich mit den etablierten Alternativen zeigt, wann welcher Ansatz die bessere Wahl für performancekritischen Code ist.

Der Vergleich zeigt: FFI liegt beim Build-Aufwand nahe bei reinem PHP, bei der Performance aber deutlich näher an einer eigenen C-Erweiterung. Für Projekte, die eine bereits existierende native Bibliothek nutzen wollen, ohne eine eigene Erweiterung zu pflegen, ist FFI in den meisten Fällen der pragmatischste Weg zu performancekritischem Code.

10. Zusammenfassung

FFI eröffnet PHP-Projekten einen direkten Weg zu nativer Performance, ohne den Aufwand einer eigenen kompilierten Erweiterung. Die Header-Definition beschreibt Funktionssignaturen und Structs, FFI::cdef() lädt die Bibliothek, und der eigentliche Aufruf verhält sich syntaktisch wie ein gewöhnlicher PHP-Methodenaufruf, springt intern aber direkt in nativen Maschinencode. Preloading über ffi.preload und opcache.preload ist für den produktiven Einsatz unverzichtbar, weil es das wiederholte Parsen der Definition bei jedem Request vermeidet.

Wer FFI einsetzt, tauscht einen Teil der Sicherheitsgarantien von PHP gegen native Geschwindigkeit ein und muss deshalb besonders sorgfältig mit Speichergrenzen, Struct-Layouts und Benutzereingaben umgehen. Vor jedem FFI-Einsatz lohnt sich ein Blick auf Algorithmus und Datenstrukturen im eigenen PHP-Code, denn nicht jede Performance-Herausforderung braucht tatsächlich den Sprung in nativen Code, um gelöst zu werden.

11. FAQ: FFI in PHP für performancekritischen Code