feat: add Host Functions support

[mhmd-azeez]

Fixes #11

• Implement FFI calls
• Implement CurrentPlugin
• Implement HostFunction
• Fail fast when validating callback params
• Add PHPDoc comments
• Add README section
• Add tests
• Review for breaking changes
• User Data. Wasn't able to find a way to pin PHP objects and get their address. Users can use captured variables in the callback closures instead.

[nilslice]

cc @AtlantisPleb

[mhmd-azeez]

I will need to do some tests regarding memory leaks, since FFI callbacks seem to leak by default:
https://www.php.net/manual/en/ffi.examples-callback.php

Although this works, this functionality is not supported on all libffi platforms, is not efficient and leaks resources by the end of request.
It is therefore recommended to minimize the usage of PHP callbacks.

[nilslice]

@mhmd-azeez -- this is pretty neat! the ability to auto-cast (?) these types, e.g. (string $key, string $value) in the signature is impressive. Maybe it's just my lack of familiarity with PHP, but I think it would be really helpful to have some notes/docs on this in the source for this callback.

[mhmd-azeez]

Hi, I added parameter details to the README, not sure if that's what you meant. let me know if you think we need more info

[nilslice]

Those work great - thank you!

[nilslice]

(related to the previous comment)

I suppose the docs I'm looking for are primarily about how the transformation of the "higher level" types into these works. And, what are the limits? If my string for example, is actually bytes, is there any issue?

[mhmd-azeez]

AFAIK there is no byte[] type in php, and string is used in its place in the standard library

[zshipko]

The dynamic typing is great! And the host function bindings look good too - I read through several times and didn't see any issues.

I think this is ready to merge once you figure out if you need to release the callback memory.

[mhmd-azeez]

After a lot of experimenting, it seems like host functions leak memory, which is expected because it's a documented behavior of FFI + callbacks. So, I have decided to mark it as experimental for now, until we can find ways around this or maybe we get more user feedback.

However, the good news is, http servers like Apache are already designed to handle such scenarios fairly well, for example, let's consider this test:

for ($i = 0; $i < 10; $i++) {
    $kvstore = [];

    $kvRead = new HostFunction("kv_read", [ExtismValType::I64], [ExtismValType::I64], function (CurrentPlugin $p, string $key) use (&$kvstore) {
        return $kvstore[$key] ?? "\0\0\0\0";
    });

    $kvWrite = new HostFunction("kv_write", [ExtismValType::I64, ExtismValType::I64], [], function (string $key, string $value) use (&$kvstore) {
        $kvstore[$key] = $value;
    });

    $plugin = new Plugin($manifest, true, [$kvRead, $kvWrite]);
    $output = $plugin->call("count_vowels", "Hello World!");

    if ($i % 1 === 0) {
        echo "Iteration: $i => " . $lib->count . PHP_EOL;
    }
}

This is how Apache behaves under test:

php-sdk-memory-test.mp4

As for freeing memory,

Managed data lives together with the returned FFI\CData object, and is released when the last reference to that object is released by regular PHP reference counting or GC. Unmanaged data should be released by calling FFI::free(), when no longer needed.

-- PHP Docs

We are only using managed data, so we should be fine.

[nilslice]

Excellent! Thank you