FFI

The method creates a binding on the existing C function.

All variables and functions defined by first arguments are bound to corresponding native symbols in a DSO library and then may be accessed as FFI object methods and properties. C types of argument, return value, and variables are automatically converted to/from PHP types (if possible). Otherwise, they are wrapped in a special CData proxy object and may be accessed by elements.

Instead of embedding of a long C definition into a PHP string and creating FFI through {FFI::cdef()}, it's possible to separate it into a C header file. Note that C preprocessor directives (e.g., #define or #ifdef) are not supported. And only a couple of special macros may be used, especially for FFI.

#define FFI_LIB "libc.so.6"

int printf(const char *format, ...);

Here, FFI_LIB specifies that the given library should be loaded.

$ffi = FFI::load(__DIR__ . "/printf.h");
$ffi->printf("Hello world!\n");

FFI definition parsing and shared library loading may take significant time. It's not useful to do it on each HTTP request in the WEB environment. However, it's possible to preload FFI definitions and libraries at php startup, and instantiate FFI objects when necessary. Header files may be extended with FFI_SCOPE define (default preloading scope is "C"). This name is going to be used as {FFI::scope()} argument. It's possible to preload a few files into a single scope.

#define FFI_LIB "libc.so.6"
#define FFI_SCOPE "libc"

int printf(const char *format, ...);

These files are loaded through the same FFI::load() load function, executed from a file loaded by opcache.preload in the php.ini directive.

ffi.preload=/etc/php/ffi/printf.h

Finally, FFI::scope() instantiates an FFI object that implements all C definitions from the given scope.

$ffi = FFI::scope("libc");
$ffi->printf("Hello world!\n");

Method that creates an arbitrary C structure.

Creates a native data structure of the given C type. Any type declared for the instance is allowed.

Note: Calling {\FFI::new()} statically is deprecated since PHP 8.3.

Manually removes previously created "not-owned" data structure.

Creates a new {FFI\CData} object, that references the same C data structure, but is associated with a different type. The resulting object does not own the C data, and the source ptr must survive the result. The C type may be specified as a {string} with any valid C type declaration or as {FFI\CType} object, created before. Any type declared for the instance is allowed.

Note: Calling {\FFI::cast()} statically is deprecated since PHP 8.3.

$ffi = FFI::cdef();

$int32Value = $ffi->new('int32_t');
$int16Array = $ffi->cast('int16_t[2]', $int32Value);

This function creates and returns a {FFI\CType} object for the given string containing a C type declaration. Any type declared for the instance is allowed.

$ffi = FFI::cdef();

$type = $ffi->type('int[2][3]');

This function returns the FFI\CType object, representing the type of the given {FFI\CData} object.

Constructs a new C array type with elements of $type and dimensions specified by $dimensions.

$ffi = FFI::cdef();

$t1 = $ffi->type('int[2][3]');
$t2 = FFI::arrayType($ffi->type('int'), [2, 3]);

Returns a C pointer to the given C data structure. The pointer is not "owned" and won't be free. Anyway, this is a potentially unsafe operation, because the life-time of the returned pointer may be longer than the life-time of the source object, and this may cause dangling pointer dereference (like in regular C).

Returns the size of a C data type of the given {FFI\CData} or {FFI\CType}.

Returns the size of a C data type of the given {FFI\CData} or {FFI\CType}.

Copies $size bytes from the memory area $from to the memory area $to.

Compares $size bytes from the memory areas $ptr1 and $ptr2.

Both $ptr1 and $ptr2 can be any native data structures ({\FFI\CData}) or PHP strings.

Fills $size bytes of the memory area pointed to by $ptr with the given byte $value.

Creates a PHP string from $size bytes of the memory area pointed by $ptr. If size is omitted, $ptr must be a zero-terminated array of C chars.

Checks whether the FFI\CData is a null pointer.