{
    "slug": "php_ffi",
    "term": "PHP FFI",
    "category": "php",
    "difficulty": "advanced",
    "short": "Foreign Function Interface — allows PHP to call C library functions and use C data structures directly, enabling integration with native libraries without writing a PHP extension.",
    "long": "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.",
    "aliases": [
        "FFI",
        "Foreign Function Interface",
        "ext-ffi",
        "C library"
    ],
    "tags": [
        "php",
        "ffi",
        "performance",
        "advanced"
    ],
    "misconception": "FFI is faster than PHP — FFI calls have significant overhead at the PHP/C boundary; FFI is valuable for accessing native APIs, not for micro-optimisations.",
    "why_it_matters": "FFI enables PHP to call any C library without writing a compiled extension — useful for image processing libraries, hardware interfaces, and native crypto implementations.",
    "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."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "php_extensions",
        "jit_compilation_deep",
        "garbage_collection"
    ],
    "prerequisites": [
        "php_compilation_pipeline",
        "linux_processes",
        "performance_degradation"
    ],
    "refs": [
        "https://www.php.net/manual/en/book.ffi.php"
    ],
    "bad_code": "// Parsing headers on every request — very slow:\nfunction getOsInfo(): string {\n    $ffi = FFI::cdef('char *getenv(const char *name);'); // Parsed every call\n    return FFI::string($ffi->getenv('HOME'));\n}",
    "good_code": "// Cache FFI instance — parse headers once:\nclass NativeLib {\n    private static ?FFI $ffi = null;\n    private static function ffi(): FFI {\n        return self::$ffi ??= FFI::cdef(\n            'int add(int a, int b);',\n            '/usr/local/lib/mylib.so'\n        );\n    }\n    public static function add(int $a, int $b): int {\n        return self::ffi()->add($a, $b);\n    }\n}",
    "quick_fix": "Use PHP FFI to call native C libraries directly from PHP — useful for performance-critical code (image processing, cryptography) without writing a PHP extension",
    "severity": "info",
    "effort": "high",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/php_ffi",
        "html_url": "https://codeclaritylab.com/glossary/php_ffi",
        "json_url": "https://codeclaritylab.com/glossary/php_ffi.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[PHP FFI](https://codeclaritylab.com/glossary/php_ffi) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/php_ffi"
            }
        }
    }
}