Add registry support

Author: SerafimArts

composer.json

@@ -19,6 +19,7 @@
     ],
     "require": {
         "php": ">=7.4",
+        "symfony/polyfill-php80": "^1.23",
         "ext-ffi": "*"
     },
     "autoload": {

resources/.phpstorm.meta.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace PHPSTORM_META {
+
+    override(\FFI\Proxy\Registry::get(), type(0));
+
+    registerArgumentsSet('ProxyCType',
+        'void *',
+
+        'bool',
+
+        'float',
+        'double',
+        'long double',
+
+        'char',
+        'signed char',
+        'unsigned char',
+        'int',
+        'signed int',
+        'unsigned int',
+        'long',
+        'signed long',
+        'unsigned long',
+        'long long',
+        'signed long long',
+        'unsigned long long',
+
+        'intptr_t',
+        'uintptr_t',
+        'size_t',
+        'ssize_t',
+        'ptrdiff_t',
+        'off_t',
+        'va_list',
+        '__builtin_va_list',
+        '__gnuc_va_list',
+
+        // stdint.h
+        'int8_t',
+        'uint8_t',
+        'int16_t',
+        'uint16_t',
+        'int32_t',
+        'uint32_t',
+        'int64_t',
+        'uint64_t',
+    );
+
+    expectedArguments(\FFI\Proxy\ApiInterface::new(), 0, argumentsSet('ProxyCType'));
+    expectedArguments(\FFI\Proxy\ApiInterface::cast(), 0, argumentsSet('ProxyCType'));
+    expectedArguments(\FFI\Proxy\ApiInterface::type(), 0, argumentsSet('ProxyCType'));
+
+    expectedArguments(\FFI\Proxy\ApiAwareTrait::new(), 0, argumentsSet('ProxyCType'));
+    expectedArguments(\FFI\Proxy\ApiAwareTrait::cast(), 0, argumentsSet('ProxyCType'));
+    expectedArguments(\FFI\Proxy\ApiAwareTrait::type(), 0, argumentsSet('ProxyCType'));
+
+    expectedArguments(\FFI\Proxy\Proxy::new(), 0, argumentsSet('ProxyCType'));
+    expectedArguments(\FFI\Proxy\Proxy::cast(), 0, argumentsSet('ProxyCType'));
+    expectedArguments(\FFI\Proxy\Proxy::type(), 0, argumentsSet('ProxyCType'));
+
+}

src/ApiAwareTrait.php

@@ -22,40 +22,65 @@
  */
 trait ApiAwareTrait
 {
+    /**
+     * @param non-empty-string|CType $type
+     * @return bool
+     */
+    private function assertTypeArgument($type): bool
+    {
+        if (\is_string($type)) {
+            return $type !== '';
+        }
+
+        if (!$type instanceof CType) {
+            throw new \TypeError(
+                \sprintf('Type MUST be string|\FFI\CType, but %s passed', \get_debug_type($type))
+            );
+        }
+
+        return true;
+    }
+
     /**
      * @see ApiInterface::new()
      * @throws ParserException
      *
-     * @psalm-param string|CType $type
+     * @psalm-param CType|non-empty-string $type
      * @psalm-param bool $owned
      * @psalm-param bool $persistent
      * @psalm-return CData|null
      */
     public function new($type, bool $owned = true, bool $persistent = false): ?CData
     {
+        assert($this->assertTypeArgument($type));
+
         return $this->ffi->new($type, $owned, $persistent);
     }
 
     /**
      * @see ApiInterface::cast()
      *
-     * @psalm-param CType|string $type
+     * @psalm-param CType|non-empty-string $type
      * @psalm-param CData|int|float|bool|null $ptr
      * @psalm-return CData|null
      */
     public function cast($type, $ptr): ?CData
     {
+        assert($this->assertTypeArgument($type));
+
         return $this->ffi->cast($type, $ptr);
     }
 
     /**
      * @see ApiInterface::type()
      *
-     * @psalm-param string $type
+     * @psalm-param non-empty-string $type
      * @psalm-return CType|null
      */
     public function type(string $type): ?CType
     {
+        assert($type !== '', 'Type name MUST be not empty');
+
         return $this->ffi->type($type);
     }
 }

src/Proxy.php

@@ -33,6 +33,10 @@ public function __construct(\FFI $ffi = null)
         if ($ffi !== null) {
             $this->ffi = $ffi;
         }
+
+        if (! Registry::has(static::class)) {
+            Registry::register($this);
+        }
     }
 
     /**

src/ProxyAwareTrait.php

@@ -23,6 +23,8 @@ trait ProxyAwareTrait
      */
     public function __call(string $method, array $args)
     {
+        assert($method !== '', 'Method name MUST not be empty');
+
         return $this->ffi->$method(...$args);
     }
 
@@ -32,6 +34,8 @@ public function __call(string $method, array $args)
      */
     public function __get(string $name)
     {
+        assert($name !== '', 'Property name MUST not be empty');
+
         return $this->ffi->$name;
     }
 
@@ -42,6 +46,8 @@ public function __get(string $name)
      */
     public function __set(string $name, $value): void
     {
+        assert($name !== '', 'Property name MUST not be empty');
+
         $this->ffi->$name = $value;
     }
 
@@ -51,6 +57,8 @@ public function __set(string $name, $value): void
      */
     public function __isset(string $name): bool
     {
+        assert($name !== '', 'Property name MUST not be empty');
+
         return isset($this->ffi->$name);
     }
 
@@ -60,6 +68,8 @@ public function __isset(string $name): bool
      */
     public function __unset(string $name): void
     {
+        assert($name !== '', 'Property name MUST not be empty');
+
         unset($this->ffi->$name);
     }
 }

src/Registry.php

@@ -0,0 +1,106 @@
+<?php
+
+/**
+ * This file is part of FFI package.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace FFI\Proxy;
+
+/**
+ * @psalm-type ApiName = class-string<ApiInterface>|non-empty-string
+ * @psalm-type ApiImplementation = ApiInterface|\FFI
+ */
+final class Registry
+{
+    /**
+     * @var string
+     */
+    private const ERROR_NOT_FOUND = 'The FFI API implementation named "%s" was not registered';
+
+    /**
+     * @var string
+     */
+    private const ERROR_EMPTY_NAME = 'The FFI API implementation name MUST not be empty';
+
+    /**
+     * List of FFI API clients
+     *
+     * @var array<ApiName, ApiImplementation>
+     */
+    private static array $implementations = [];
+
+    /**
+     * Returns FFI API instance by its name or creates a new FFI API instance.
+     *
+     * @param ApiName $name
+     * @return ApiImplementation
+     * @throws \OutOfRangeException
+     */
+    public static function get(string $name): object
+    {
+        assert($name !== '', self::ERROR_EMPTY_NAME);
+
+        if (isset(self::$implementations[$name])) {
+            return self::$implementations[$name];
+        }
+
+        if (\is_subclass_of($name, ApiInterface::class, true)) {
+            return self::$implementations[$name] = new $name();
+        }
+
+        throw new \OutOfRangeException(\sprintf(self::ERROR_NOT_FOUND, $name));
+    }
+
+    /**
+     * Returns {@see true} if FFI API instance is defined or {@see false} otherwise.
+     *
+     * @param ApiName $name
+     * @return bool
+     */
+    public static function has(string $name): bool
+    {
+        assert($name !== '', self::ERROR_EMPTY_NAME);
+
+        return isset(self::$implementations[$name]);
+    }
+
+    /**
+     * Clean registry storage.
+     *
+     * @return void
+     */
+    public static function dispose(): void
+    {
+        self::$implementations = [];
+    }
+
+    /**
+     * Register proxy implementation by its name.
+     *
+     * @param ApiInterface $api
+     * @return void
+     */
+    public static function register(ApiInterface $api): void
+    {
+        self::$implementations[\get_class($api)] = $api;
+    }
+
+    /**
+     * Register FFI API implementation bu custom name.
+     *
+     * @param non-empty-string $name
+     * @param ApiImplementation $api
+     * @return void
+     */
+    public static function registerAs(string $name, $api): void
+    {
+        assert($name !== '', self::ERROR_EMPTY_NAME);
+
+        self::$implementations[$name] = $api;
+    }
+}