PHP: полный мануал с примерами, функциями и ООП

<?php
declare(strict_types=1);

function cRuntimeLibrary(): string
{
    return match (PHP_OS_FAMILY) {
        'Windows' => 'msvcrt.dll',
        'Darwin' => 'libSystem.B.dylib',
        default => 'libc.so.6',
    };
}

$ffi = FFI::cdef('int abs(int value);', cRuntimeLibrary());
echo $ffi->abs(-17), "\n";

17

Объявление содержит ровно нужный символ. Имя runtime-библиотеки выбирается по ОС; произвольный путь от HTTP-клиента здесь недопустим.

<?php
declare(strict_types=1);

function cRuntimeLibrary(): string
{
    return match (PHP_OS_FAMILY) {
        'Windows' => 'msvcrt.dll',
        'Darwin' => 'libSystem.B.dylib',
        default => 'libc.so.6',
    };
}

$header = '#define FFI_LIB "' . cRuntimeLibrary() . '"' . "\nint abs(int value);\n";
$path = __DIR__ . '/manual_math.h';
file_put_contents($path, $header);
$ffi = FFI::load($path);
echo $ffi->abs(-9), "\n";

9

FFI_LIB — специально поддерживаемая директива load. Обычный include/macros FFI parser не выполняет; header хранится вместе с кодом приложения.

<?php
declare(strict_types=1);

try {
    FFI::scope('MANUAL_SCOPE_NOT_PRELOADED');
} catch (FFI\Exception $error) {
    echo "scope not loaded\n";
}

scope not loaded

Рабочий scope создаётся на старте через ffi.preload/FFI_SCOPE. Здесь показан реальный отказ текущего процесса, который приложение обязано диагностировать.

<?php
declare(strict_types=1);

$ffi = FFI::cdef();
$numbers = $ffi->new('int[3]');
$numbers[0] = 4;
$numbers[1] = 7;
$numbers[2] = 9;
echo $numbers[0] + $numbers[1] + $numbers[2], "\n";

20

Это C-память фиксированной длины, хотя синтаксис индексов похож на PHP-массив. Индекс 3 уже вышел бы за границу.

<?php
declare(strict_types=1);

$ffi = FFI::cdef();
$value = $ffi->new('int', owned: false);
$value->cdata = 42;
echo "before free: {$value->cdata}\n";
FFI::free($value);
echo "freed\n";

before free: 42
freed

После free переменную намеренно не читаем и не освобождаем повторно. Для owned:true ручной free не нужен.

<?php
declare(strict_types=1);

$ffi = FFI::cdef();
$value = $ffi->new('int');
$value->cdata = 21;
$pointer = $ffi->cast('int*', FFI::addr($value));
echo $pointer[0], "\n";

21

Cast не копирует 21 и не продлевает жизнь value. Пример хранит исходный CData до последнего чтения pointer.

<?php
declare(strict_types=1);

$ffi = FFI::cdef('typedef struct { int id; double total; char code[8]; } OrderRow;');
$type = $ffi->type('OrderRow');

echo $type->getKind() === FFI\CType::TYPE_STRUCT ? "struct\n" : "other type\n";
echo $type->getSize() > 0 ? "size known\n" : "incomplete type\n";

struct
size known

CType — схема памяти. Конкретную OrderRow создаёт отдельный new; это разделяет проверку договора и данные.

<?php
declare(strict_types=1);

$ffi = FFI::cdef();
$values = $ffi->new('double[2]');
$type = FFI::typeof($values);
echo $type->getKind() === FFI\CType::TYPE_ARRAY ? "array\n" : "not array\n";
echo $type->getArrayLength(), " elements\n";

array
2 elements

typeof читает фактическую схему CData; он не выводит значения элементов.

<?php
declare(strict_types=1);

$ffi = FFI::cdef();
$matrixType = FFI::arrayType($ffi->type('int'), [2, 3]);
$matrix = $ffi->new($matrixType);
$matrix[1][2] = 11;
echo $matrixType->getArrayLength(), 'x', $matrixType->getArrayElementType()->getArrayLength(), "\n";
echo $matrix[1][2], "\n";

2x3
11

Размеры становятся частью C-типа. Это не динамический PHP-массив: расширить матрицу после выделения нельзя.

<?php
declare(strict_types=1);

$ffi = FFI::cdef();
$count = $ffi->new('int');
$count->cdata = 15;
$pointer = FFI::addr($count);
$pointer[0] += 5;
echo $count->cdata, "\n";

20

Так моделируется C out-параметр: функция получает адрес и пишет в ту же ячейку. count обязан оставаться живым.

<?php
declare(strict_types=1);

$ffi = FFI::cdef();
$one = $ffi->type('int');
$four = $ffi->type('int[4]');
echo FFI::sizeof($four) === 4 * FFI::sizeof($one) ? "4 elements\n" : "ABI differs\n";

4 elements

Вывод не обещает, что int всегда равен четырём байтам: он проверяет отношение в текущей ABI.

<?php
declare(strict_types=1);

$ffi = FFI::cdef('typedef struct { int id; double total; char code[8]; } OrderRow;');
$type = $ffi->type('OrderRow');

$alignment = FFI::alignof($type);
echo $alignment > 0 ? "positive alignment\n" : "alignment error\n";
echo $type->getSize() % $alignment === 0 ? "size aligned\n" : "check ABI\n";

positive alignment
size aligned

Конкретное число отличается между ABI. Для безопасного обмена структурой используют фактические sizeof/alignof/offset, а не цифры из чужого компьютера.

<?php
declare(strict_types=1);

$ffi = FFI::cdef();
$buffer = $ffi->new('char[6]');
$source = "hello\0";
FFI::memcpy($buffer, $source, strlen($source));
echo FFI::string($buffer), "\n";

hello

Размер 6 совпадает с буфером и включает NUL. Без проверки длины memcpy не защищает от переполнения.

<?php
declare(strict_types=1);

$first = 'abc';
$same = 'abc';
$later = 'abd';
echo FFI::memcmp($first, $same, 3) === 0 ? "equal\n" : "different\n";
echo FFI::memcmp($first, $later, 3) < 0 ? "abc before abd\n" : "other order\n";

equal
abc before abd

Для равенства важен только ноль; конкретная отрицательная величина реализационно зависима.

<?php
declare(strict_types=1);

$ffi = FFI::cdef();
$buffer = $ffi->new('char[4]');
FFI::memset($buffer, ord('A'), FFI::sizeof($buffer));
echo FFI::string($buffer, 4), "\n";

AAAA

Передаётся байт 65, а не строка A. Явная длина позволяет прочитать буфер без завершающего NUL.

<?php
declare(strict_types=1);

$ffi = FFI::cdef();
$buffer = $ffi->new('char[3]');
$bytes = "A\0B";
FFI::memcpy($buffer, $bytes, 3);
echo bin2hex(FFI::string($buffer, 3)), "\n";
echo FFI::string($buffer), "\n";

410042
A

С длиной возвращаются A, NUL и B; без длины чтение останавливается на первом NUL. Это ключевая граница бинарных данных.

<?php
declare(strict_types=1);

$ffi = FFI::cdef();
$null = $ffi->cast('void*', 0);
$value = $ffi->new('int');
$live = FFI::addr($value);
echo FFI::isNull($null) ? "null\n" : "not null\n";
echo FFI::isNull($live) ? "null\n" : "live address\n";

null
live address

Ненулевой адрес ещё не доказывает, что он действителен и достаточно велик; isNull решает только один вопрос.

<?php
declare(strict_types=1);

$ffi = FFI::cdef();
$type = $ffi->type('int32_t');
echo $type->getName(), "\n";

int32_t

Имя помогает строить отчёт о договоре, но совместимость ABI проверяют также size/alignment и исходный header.

<?php
declare(strict_types=1);

$ffi = FFI::cdef();
$type = $ffi->type('int[4]');
echo $type->getKind() === FFI\CType::TYPE_ARRAY ? "array\n" : "not array\n";

array

Проверка kind должна предшествовать специализированным getArray* методам.

<?php
declare(strict_types=1);

$ffi = FFI::cdef('typedef struct { int id; double total; char code[8]; } OrderRow;');
$type = $ffi->type('OrderRow');

echo $type->getSize() === FFI::sizeof($type) ? "sizes match\n" : "check type\n";
echo $type->getSize() > 0 ? "complete type\n" : "incomplete type\n";

sizes match
complete type

Число зависит от padding и ABI; в интерфейсе показываем проверенный факт текущего процесса.

<?php
declare(strict_types=1);

$ffi = FFI::cdef('typedef struct { int id; double total; char code[8]; } OrderRow;');
$type = $ffi->type('OrderRow');

echo $type->getAlignment() === FFI::alignof($type) ? "alignment matches\n" : "check ABI\n";
echo $type->getAlignment() > 0 ? "positive\n" : "error\n";

alignment matches
positive

Alignment нужен для корректного размещения структуры в буфере; это не декоративное число.

<?php
declare(strict_types=1);

$ffi = FFI::cdef();
$type = $ffi->type('const int');
$attributes = $type->getAttributes();
echo ($attributes & FFI\CType::ATTR_CONST) !== 0 ? "const\n" : "mutable\n";

mutable

Маску проверяют побитовым &: равенство всей маски одной константе потеряло бы остальные флаги.

<?php
declare(strict_types=1);

$ffi = FFI::cdef('typedef enum { MODE_STOP = 0, MODE_RUN = 1 } DeviceMode;');
$type = $ffi->type('DeviceMode');
$kind = $type->getEnumKind();
echo in_array($kind, [FFI\CType::TYPE_SINT32, FFI\CType::TYPE_UINT32], true)
    ? "32-bit enum\n" : "other ABI\n";

32-bit enum

Не подменяйте enum обычным int по предположению: фиксируйте header и проверяйте фактическое представление.

<?php
declare(strict_types=1);

$ffi = FFI::cdef();
$array = $ffi->type('double[4]');
$element = $array->getArrayElementType();
echo $element->getKind() === FFI\CType::TYPE_DOUBLE ? "double\n" : "other element\n";

double

В многомерном массиве результат может снова быть TYPE_ARRAY; проход повторяют по каждому измерению.

<?php
declare(strict_types=1);

$ffi = FFI::cdef();
$type = $ffi->type('uint16_t[5]');
echo $type->getArrayLength(), " elements\n";

5 elements

Это длина одного измерения CType, не число заполненных элементов и не strlen.

<?php
declare(strict_types=1);

$ffi = FFI::cdef();
$pointer = $ffi->type('int*');
$target = $pointer->getPointerType();
echo $target->getKind() === FFI\CType::TYPE_SINT32 ? "int32\n" : $target->getName() . "\n";

int32

Тип цели не подтверждает действительность адреса. Перед чтением отдельно проверяют null, владение и длину.

<?php
declare(strict_types=1);

$ffi = FFI::cdef('typedef struct { int id; double total; char code[8]; } OrderRow;');
$type = $ffi->type('OrderRow');

echo implode(', ', $type->getStructFieldNames()), "\n";

id, total, code

Имена приходят из C-декларации. Они помогают сопоставить формат, но не заменяют проверку offset/type.

<?php
declare(strict_types=1);

$ffi = FFI::cdef('typedef struct { int id; double total; char code[8]; } OrderRow;');
$type = $ffi->type('OrderRow');

$id = $type->getStructFieldOffset('id');
$total = $type->getStructFieldOffset('total');
echo $id === 0 ? "id starts at 0\n" : "unexpected layout\n";
echo $total > $id ? "total follows id\n" : "check ABI\n";

id starts at 0
total follows id

Мы не хардкодим число offset: компилятор ABI может вставить padding перед double.

<?php
declare(strict_types=1);

$ffi = FFI::cdef('typedef struct { int id; double total; char code[8]; } OrderRow;');
$type = $ffi->type('OrderRow');

$field = $type->getStructFieldType('total');
echo $field->getKind() === FFI\CType::TYPE_DOUBLE ? "double\n" : "other type\n";

double

Перед записью гидратор может проверить схему поля. Это всё равно не разрешает передавать непроверенные имена полей от клиента.

<?php
declare(strict_types=1);

$ffi = FFI::cdef('typedef int (*calculator_t)(double value, int mode);');
$type = $ffi->type('calculator_t')->getPointerType();

echo $type->getKind() === FFI\CType::TYPE_FUNC ? "function\n" : "not function\n";
echo $type->getFuncABI() === FFI\CType::ABI_DEFAULT ? "ABI default\n" : "special ABI\n";

function
special ABI

Неправильная calling convention особенно опасна на Windows: стек/регистры могут не совпасть даже при одинаковых параметрах.

<?php
declare(strict_types=1);

$ffi = FFI::cdef('typedef int (*calculator_t)(double value, int mode);');
$type = $ffi->type('calculator_t')->getPointerType();

$return = $type->getFuncReturnType();
echo $return->getKind() === FFI\CType::TYPE_SINT32 ? "returns int32\n" : $return->getName() . "\n";

returns int32

Return type входит в ABI. Объявление void вместо int или наоборот нельзя исправить приведением результата в PHP.

<?php
declare(strict_types=1);

$ffi = FFI::cdef('typedef int (*calculator_t)(double value, int mode);');
$type = $ffi->type('calculator_t')->getPointerType();

echo $type->getFuncParameterCount(), " parameters\n";

2 parameters

Для variadic-функции фиксированная часть и ATTR_VARIADIC рассматриваются отдельно.

<?php
declare(strict_types=1);

$ffi = FFI::cdef('typedef int (*calculator_t)(double value, int mode);');
$type = $ffi->type('calculator_t')->getPointerType();

$first = $type->getFuncParameterType(0);
$second = $type->getFuncParameterType(1);
echo $first->getKind() === FFI\CType::TYPE_DOUBLE ? "0: double\n" : "0: other\n";
echo $second->getKind() === FFI\CType::TYPE_SINT32 ? "1: int32\n" : "1: other\n";

0: double
1: int32

Перед getFuncParameterType проверяют count; индекс 2 в этой сигнатуре выбросит FFI\Exception.