klitsche/ffigen

FFI binding generator

v0.8.1 2023-01-21 00:42 UTC

Requires

• php: ^7.4 || ^8.0
• brick/varexporter: ^0.3.2
• ircmaxell/php-c-parser: dev-master#fd8f5efefd0fcc6c5119d945694acaa3a6790ada
• symfony/console: ^5.0
• symfony/filesystem: ^5.0
• symfony/yaml: ^5.0

Requires (Dev)

• phpunit/phpunit: ^9.1
• symplify/easy-coding-standard: ^11.2

MIT

• Dirk Adler

• generator
• binding
• ffi

README

ffigen is a simple cli helper to quickly generate and update low level PHP FFI bindings for C libraries.

It generates two PHP files out of provided C header file(s):

• constants.php - holding constant values
• Methods.php - holding function bindings as static methods plus phpdoc in a trait

It is heavily inspired by FFIMe and depends on PHPCParser by ircmaxell.

WIP: Expect breaking changes along all 0.* pre-releases.

Requirements

• PHP ^7.4 || ^8.0
• For examples: FFI extension must be available and enabled

Quick Start

Install in your project:

composer require --dev klitsche/ffigen

Install a c library (eg. uuid).

Add a config file to your project root:

.ffigen.yml

Tweak this config file (example):

headerFiles:
  - uuid/uuid.h
libraryFile: libuuid.so.1
parserClass: Klitsche\FFIGen\Examples\UUID\FFIGen\Parser
outputPath: ./
excludeConstants:
  - /^(?!(FFI|UUID)_).*/
excludeMethods:
namespace: Klitsche\FFIGen\Examples\UUID

Optional: add your own Parser class to customize pre oder post processing logic (example):

<?php

declare(strict_types=1);

namespace Klitsche\FFIGen\Examples\UUID\FFIGen;

use Klitsche\FFIGen\Config;

class Parser extends \Klitsche\FFIGen\Adapter\PHPCParser\Parser
{
    public function __construct(Config $config)
    {
        parent::__construct($config);

        $this->context->defineInt('_SYS_TYPES_H', 1);
        $this->context->defineInt('_SYS_TIME_H', 1);
        $this->context->defineInt('_TIME_H', 1);
    }

    protected function parseHeaderFile(string $file): array
    {
        $file = $this->searchHeaderFilePath($file);

        $prependHeaderFile = '
            typedef long time_t;
        ';
        $tmpfile = tempnam(sys_get_temp_dir(), 'ffigen');
        file_put_contents($tmpfile, $prependHeaderFile . file_get_contents($file));

        $declarations = parent::parseHeaderFile($tmpfile);

        unlink($tmpfile);

        return $declarations;
    }

    private function searchHeaderFilePath(string $file): string
    {
        if (file_exists($file)) {
            return $file;
        }
        foreach ($this->context->headerSearchPaths as $headerSearchPath) {
            if (file_exists($headerSearchPath . '/' . $file)) {
                return $headerSearchPath . '/' . $file;
            }
        }

        throw new \RuntimeException(sprintf('File not found: %s', $file));
    }
}

Do not forget to register the Parser namespace in your composer.json for autoloading (dev is okay):

    "autoload-dev": {
        "psr-4": {
            "Klitsche\\FFIGen\\Examples\\": "examples"
        }
    },

Dump autoloading with

composer dump-autoload

Run ffigen to generate binding files

vendor/bin/ffigen

This generates the two files in the output path:

• constants.php - add this to your autoloading
• Methods.php - add this to your own class context and use it within your own high level php library

Do not forget to add constants.php to your compose.json for autoloading:

    "autoload": {
        "files": [
          "tweak-path-to/constants.php",
        ]
    },

Play with examples

Build docker image with preinstalled c libraries (uuid, snappy & librdkafka):

 docker-compose build php74

Run uuid example

docker-compose run --rm php74 php bin/ffigen generate -c examples/UUID/.ffigen.yml
docker-compose run --rm php74 php examples/UUID/test.php

Run snappy example (see Snappy class for a simple high level example)

docker-compose run --rm php74 bin/ffigen generate -c examples/Snappy/.ffigen.yml
docker-compose run --rm php74 php examples/Snappy/test.php

Run rdkafka example (librdkafka 1.5.2 & mock cluster)

docker-compose run --rm php74 bin/ffigen generate -c examples/RdKafka/.ffigen.yml
docker-compose run --rm php74 php examples/RdKafka/test.php

Todos

• Add travis
• Add more tests
• Add documentation
• Add support for Windows, macOS
• Add more examples (and learn from them)
• Think about multi version support
• Think about custom interface / class generation for types
• Think about clang / cpp / readelf adapter (cpp defines only & clean file, clang -c11 ast-dump=json, readelf --dyn-syms)