PHP FFI

Also Known As

TL;DR

Explanation

PHP FFI (available since PHP 7.4, ext-ffi) lets you declare C function signatures and call them from PHP using FFI::cdef() or FFI::load(). This enables calling libsodium directly, integrating with system libraries, and using high-performance native code for CPU-intensive operations. The trade-off: FFI calls have overhead (no JIT optimisation across the boundary), and incorrect memory management can segfault the process. Best for: wrapping C libraries that don't have a PHP extension, or when an extension cannot be installed.

Common Misconception

Why It Matters

Common Mistakes

• Using FFI for small frequent calls — the overhead per call is substantial; batch operations where possible.
• Not freeing FFI-allocated memory — PHP GC does not manage C memory; use $ffi->free() or CData destructors.
• FFI in web requests — FFI::cdef() parses C headers on every call; cache the FFI instance.
• Not checking if ext-ffi is enabled — it is disabled by default in some distributions.

Code Examples

// Parsing headers on every request — very slow:
function getOsInfo(): string {
    $ffi = FFI::cdef('char *getenv(const char *name);'); // Parsed every call
    return FFI::string($ffi->getenv('HOME'));
}

// Cache FFI instance — parse headers once:
class NativeLib {
    private static ?FFI $ffi = null;
    private static function ffi(): FFI {
        return self::$ffi ??= FFI::cdef(
            'int add(int a, int b);',
            '/usr/local/lib/mylib.so'
        );
    }
    public static function add(int $a, int $b): int {
        return self::ffi()->add($a, $b);
    }
}

References

• ↗ https://www.php.net/manual/en/book.ffi.php

Tags

Related Terms