[Guikingone]

Summary

Adds PHP's ext/ffi surface to elephc as a Rust bridge over bundled libffi, plus an AST-built prelude (FFI, FFI\CData, FFI\CType, FFI\Exception, FFI\ParserException) that is injected only when FFI is referenced or --with-ffi is passed.

The branch also commits the php-src ext/ffi fixture corpus (77 cases) and a harness that compiles/runs each case with its --INI--, --ENV--, preload and asset setup. The corpus is compiled with the PHP 8.3 profile matching its provenance.

What is included

• crates/elephc-ffi: C declaration parser, C type layout, libffi calls, CData/CType context, memory helpers, function-pointer callbacks, ownership handling, and a feature-gated php-src fixture shim module.
• src/ffi_prelude*: synthetic-AST prelude and detection. fragments.rs is #[cfg(test)] transcription/oracle only; production uses the generated build.rs and never parses PHP text.
• Pipeline/linker wiring for auto-detection and --with-ffi (including forced prelude/staticlib reachability).
• 77 committed php-src fixtures under tests/php_src/ffi/, the generated test cases, and scripts/gen_php_src_ffi_cases.py.
• docs/php/ffi.md and examples/ffi-callbacks/.

PHP-visible parity

• class_implements(FFI\CData::class) and get_class_methods(FFI\CData::class) are empty; any CData method call raises php-src's catchable Error: Object of type FFI\CData does not support method calls at run time; instanceof ArrayAccess/Countable/Iterator/Traversable/Stringable is false; class_implements(FFI::class) and class_implements(FFI\CType::class) are empty; only php-src's public method lists are exposed for FFI and FFI\CType. Array access, count() and foreach keep working through the compiler's internal dispatch.
• PHP 8.5+ emits Deprecated: Calling FFI::new() statically is deprecated; earlier profiles stay silent. The committed 8.3-era corpus compiles with the matching profile.
• FFI::new(..., persistent: true) marks the allocation persistent: the CData destructor does not release it, matching php-src's persistent-allocator lifetime, while an explicit FFI::free() still releases it.
• Scalar CData arithmetic raises php-src's TypeError: Unsupported operand types ...; only pointer/array CData supports +/-, and pointer difference returns int.
• CData comparisons match the internal handler: pointer/pointer by address, null pointers throw, and every non-pointer/incompatible combination raises Comparison of incompatible C types.
• (int)/(float) casts warn and yield 1; (string) reads a scalar payload and raises php-src's engine error for pointer/aggregate CData; (bool) is true.
• CData is not Traversable: is_iterable() and ReflectionClass::isIterable() are false, and iterator_to_array() raises its Traversable|array TypeError. Array access, count() and foreach still work through internal dispatch.
• Magic __get properties such as FFI globals stay mixed inside array literals, so __call argument arrays no longer cast CData to int.
• foreach over scalar C arrays yields PHP scalars; by-reference loops keep writable CData views.
• String-to-char/char[N] assignment follows php-src diagnostics, with numeric-prefix coercion for numeric fields.
• is_callable() on CData uses the bridge's pointer-to-function check, including when the value is boxed in a mixed slot; the generic string/closure/array path is unchanged.
• Callback aggregate arguments are owned copies instead of libffi stack views.
• Struct/array callback returns by value are supported through a staged libffi aggregate dispatcher; variadic function pointers reject PHP closures with php-src's Variadic function closures are not supported.
• PHP closures, function names, and array callables can be passed directly to a C function-pointer parameter (qsort comparators and similar); the call builder prepares a temporary libffi callback.
• CData method calls now raise php-src's catchable Error: Object of type FFI\CData does not support method calls at run time (including dynamic and non-null nullsafe forms) instead of failing at compile time; is_callable([$cdata, "method"]) throws the same error.
• --ini ffi.enable=0 disables every guarded FFI API entry point with php-src's FFI API is restricted by "ffi.enable" configuration directive; preload stays CLI-only and 1/On enables both CLI and web builds.
• FFI::addr(<temporary>) transfers ownership; reads from pointer fields/elements keep independent copies; FFI::free($array[$i]) still zeroes the originating element.
• Property ++/-- uses PHP string/number increment semantics, which fixes $charCData->cdata++.

Validation

• 77/77 php-src FFI fixtures
• codegen::ffi::: 93 passed, 3 ignored (external SDL)
• elephc-ffi unit tests: 10 passed
• ffi_prelude parity tests: 6 passed
• debug_info_dumps: 17; mixed_receiver_property_writes: 19
• SPL introspection/interfaces and iterator suites: green
• incdec/property operator and optimizer suites: green
• CLI --with-ffi and runtime-cache feature-key tests: green
• XML example and the iOS XML staticlib link: green (the FFI prelude is no longer injected by prelude-internal probes, so a non-FFI staticlib has no elephc_ffi references)
• Builtins/compatibility docs drift gate: green
• cargo build warning-free; git diff --check clean

No CHANGELOG.md edit and no Cargo package version bump.