Make FFI injection optional

By automagically finding and processing header files, or using preload
scope, when an FFI hasn’t been supplied.

Author: onethumb

README.md

@@ -39,14 +39,69 @@ Use [Composer](https://getcomposer.org) to install this library (note the [Requi
 composer require awesomized/crc-fast
 ```
 
+## Configuration
+[FFI ini](https://www.php.net/manual/en/ffi.configuration.php) settings must be configured properly for your environment.
+
+Optionally, opcache [preloading](https://www.php.net/manual/en/ffi.examples-complete.php) can also be used as an optimization.
 
 ## Usage
 
 Examples are for `CRC-64/NVME`, but `CRC-32/ISO-HDLC` is nearly identical, just in a different namespace (`Awesomized\Checksums\Crc32\IsoHdlc`).
 
-### Creating the CRC-64/NVME FFI object 
+Make sure you have the correct header file(s) for your CPU architecture and OS in [/include](include) for your project (e.g., [include/crc64nvme-aarch64-linux.h](include/crc64nvme-aarch64-linux.h)) which points to the correct shared library for your environment.
+
+### Calculate CRC-64/NVME checksums:
+
+```php
+use Awesomized\Checksums\Crc64\Nvme;
+
+// calculate the checksum of a string
+$checksum = Nvme\Computer::calculate(
+    string: 'hello, world!'
+    // optionally inject a different FFI here
+); // f8046e40c403f1d0
+
+// calculate the checksum of a file, which will chunk through the file optimally,
+// limiting RAM usage and maximizing throughput
+$checksum = Nvme\Computer::calculateFile(
+    filename: 'path/to/hello-world'
+    // optionally inject a different FFI here
+); // f8046e40c403f1d0
+```
+
+### Calculate CRC-64/NVME checksums with a Digest for intermittent / streaming / etc workloads:
+
+```php
+use Awesomized\Checksums\Crc64\Nvme;
 
-A [helper FFI Class](src/Ffi.php) is provided, which supplies many ways to easily create an FFI object for the [crc64fast-nvme](https://github.com/awesomized/crc64fast-nvme) shared library:
+$crc64Digest = new Nvme\Computer(
+    // optionally inject a different FFI here
+);
+
+// write some data to the digest
+$crc64Digest->write('hello,');
+
+// write some more data to the digest
+$crc64Digest->write(' world!');
+
+// calculate the entire digest
+$checksum = $crc64Digest->sum(); // f8046e40c403f1d0
+```
+
+### Creating an CRC-64/NVME FFI object 
+
+Alternatively, you can create an FFI object directly, and inject it into the `Computer` classes:
+
+#### - Via automagic loading via preloading and/or header files (recommended for most use cases):
+
+```php
+use Awesomized\Checksums\Crc64\Nvme;
+
+// uses the opcache preloaded shared library, if possible, otherwise uses the header file
+$crc64Fast = Nvme\Ffi::fromAuto();
+```
+
+Alternatively, a [helper FFI Class](src/Ffi.php) is provided, which supplies many ways to easily create an FFI object for the [crc64fast-nvme](https://github.com/awesomized/crc64fast-nvme) shared library:
 
 #### - Via [preloaded](https://www.php.net/manual/en/ffi.examples-complete.php) shared library (recommended for any long-running workloads, such as web requests):
 
@@ -67,7 +122,7 @@ use Awesomized\Checksums\Crc64\Nvme;
 
 // uses the FFI_LIB and FFI_SCOPE definitions in the header file
 $crc64Fast = Nvme\Ffi::fromHeaderFile(
-    headerFile: 'path/to/crc64fast_nvme.h', // optional, can likely be inferred from the OS
+    headerFile: 'path/to/crc64nvme-ARCH-OS.h', // optional, can likely be inferred from the OS
 );
 ```
 
@@ -86,49 +141,7 @@ $crc64Fast = Nvme\Ffi::fromCode(
     library: 'libcrc64fast_nvme.so',
 );
 ```
-### Using the CRC-64/NVME FFI object
-
-#### Calculate CRC-64/NVME checksums:
-
-```php
-use Awesomized\Checksums\Crc64\Nvme;
-
-/** @var \FFI $crc64Fast */
-
-// calculate the checksum of a string
-$checksum = Nvme\Computer::calculate(
-    ffi: $crc64Fast, 
-    string: 'hello, world!'
-); // f8046e40c403f1d0
-
-// calculate the checksum of a file, which will chunk through the file optimally,
-// limiting RAM usage and maximizing throughput
-$checksum = Nvme\Computer::calculateFile(
-    ffi: $crc64Fast, 
-    filename: 'path/to/hello-world'
-); // f8046e40c403f1d0
-```
-
-#### Calculate CRC-64/NVME checksums with a Digest for intermittent / streaming / etc workloads:
-
-```php
-use Awesomized\Checksums\Crc64\Nvme;
-
-/** @var \FFI $crc64FastNvme */
-
-$crc64Digest = new Nvme\Computer(
-    crc64Nvme: $crc64FastNvme,
-);
-
-// write some data to the digest
-$crc64Digest->write('hello,');
-
-// write some more data to the digest
-$crc64Digest->write(' world!');
 
-// calculate the entire digest
-$checksum = $crc64Digest->sum(); // f8046e40c403f1d0
-```
 
 ## Examples
 
@@ -140,16 +153,17 @@ This project uses [SemVer](https://semver.org), and has extensive coding standar
 
 Examples:
 
-#### Building the shared `crc64fast-nvme` Rust library for local development and testing
+#### Build, validate, and test everything:
 ```bash
-make build
-``` 
-#### Validating PHP code
+make
+```
+
+#### Building the shared Rust libraries for local development and testing
 ```bash
-make validate
-``` 
+make build
+```
 
-#### Repairing PHP code quality issues
+#### Repairing PHP coding standards issues
 ```bash
 make repair
 ```

src/ChecksumTrait.php

@@ -12,9 +12,13 @@
 trait ChecksumTrait
 {
     public static function calculate(
-        FFI $ffi,
         string $string,
+        ?FFI $ffi = null,
     ): string {
+        if (null === $ffi) {
+            $ffi = self::getFfi();
+        }
+
         return (new self($ffi))
             ->write(
                 string: $string,
@@ -23,10 +27,14 @@ public static function calculate(
     }
 
     public static function calculateFile(
-        FFI $ffi,
         string $filename,
         int $readChunkSize = self::READ_CHUNK_SIZE_DEFAULT,
+        ?FFI $ffi = null,
     ): string {
+        if (null === $ffi) {
+            $ffi = self::getFfi();
+        }
+
         $handle = fopen(
             filename: $filename,
             mode: 'rb',
@@ -62,4 +70,6 @@ public static function calculateFile(
 
         return $computer->sum();
     }
+
+    abstract protected static function getFfi(): FFI;
 }

src/Crc32/IsoHdlc/Computer.php

@@ -16,24 +16,30 @@ final class Computer implements Checksums\CrcInterface
 {
     use Checksums\ChecksumTrait;
 
-    private FFI\CData $hasherHandle;
+    private readonly FFI $crc32IsoHdlc;
+
+    private readonly FFI\CData $hasherHandle;
+
+    private static ?FFI $ffiAuto = null;
 
     /**
-     * @param FFI $crc32IsoHdlc The FFI instance for the CRC-32 IEEE library.
+     * @param FFI|null $crc32IsoHdlc The FFI instance for the CRC-32 IEEE library.
      *
      * @throws \InvalidArgumentException
      */
     public function __construct(
-        private readonly FFI $crc32IsoHdlc,
+        ?FFI $crc32IsoHdlc = null,
     ) {
+        $this->crc32IsoHdlc = $crc32IsoHdlc ?? self::getFfi();
+
         try {
             /**
-             * @var FFI\CData $digestHandle
+             * @var FFI\CData $hasherHandle
              *
              * @psalm-suppress UndefinedMethod - from FFI, we'll catch the Exception if the method is missing
              */
             // @phpstan-ignore-next-line
-            $digestHandle = $this->crc32IsoHdlc->hasher_new();
+            $hasherHandle = $this->crc32IsoHdlc->hasher_new();
         } catch (FFI\Exception $e) {
             throw new \InvalidArgumentException(
                 message: 'Could not create a new Hasher handle.'
@@ -42,7 +48,7 @@ public function __construct(
             );
         }
 
-        $this->hasherHandle = $digestHandle;
+        $this->hasherHandle = $hasherHandle;
     }
 
     public function write(
@@ -92,4 +98,16 @@ public function sum(): string
             $crc32,
         );
     }
+
+    /**
+     * @throws \InvalidArgumentException
+     */
+    protected static function getFfi(): FFI
+    {
+        if (null !== self::$ffiAuto) {
+            return self::$ffiAuto;
+        }
+
+        return self::$ffiAuto = Checksums\Crc32\IsoHdlc\Ffi::fromAuto();
+    }
 }

src/Crc64/Nvme/Computer.php

@@ -18,16 +18,22 @@ final class Computer implements Checksums\CrcInterface
 {
     use Checksums\ChecksumTrait;
 
-    private FFI\CData $digestHandle;
+    private readonly FFI $crc64Nvme;
+
+    private readonly FFI\CData $digestHandle;
+
+    private static ?FFI $ffiAuto = null;
 
     /**
      * @param FFI $crc64Nvme The FFI instance for the CRC-64 NVMe library.
      *
      * @throws \InvalidArgumentException
      */
     public function __construct(
-        private readonly FFI $crc64Nvme,
+        ?FFI $crc64Nvme = null,
     ) {
+        $this->crc64Nvme = $crc64Nvme ?? self::getFfi();
+
         try {
             /**
              * @var FFI\CData $digestHandle
@@ -94,4 +100,16 @@ public function sum(): string
             $crc64,
         );
     }
+
+    /**
+     * @throws \InvalidArgumentException
+     */
+    protected static function getFfi(): FFI
+    {
+        if (null !== self::$ffiAuto) {
+            return self::$ffiAuto;
+        }
+
+        return self::$ffiAuto = Checksums\Crc64\Nvme\Ffi::fromAuto();
+    }
 }

src/CrcInterface.php

@@ -26,8 +26,8 @@ interface CrcInterface
     /**
      * Calculates the CRC checksum for a string.
      *
-     * @param FFI    $ffi    The FFI instance for the CRC library.
-     * @param string $string The string to calculate the CRC checksum for.
+     * @param string   $string The string to calculate the CRC checksum for.
+     * @param FFI|null $ffi    The FFI instance for the CRC library.
      *
      * @return string The calculated CRC checksum as a hexadecimal string (due to signed large int issues in PHP for
      *                64-bit results).
@@ -36,17 +36,17 @@ interface CrcInterface
      * @throws \RuntimeException
      */
     public static function calculate(
-        FFI $ffi,
         string $string,
+        ?FFI $ffi = null,
     ): string;
 
     /**
      * Calculates the CRC checksum for a file.
      *
-     * @param FFI         $ffi           The FFI instance for the CRC library.
      * @param string      $filename      The file or URL.
      * @param int<1, max> $readChunkSize The size of the chunks to read from the file. Adjust as necessary for your
      *                                   environment.
+     * @param FFI|null    $ffi           The FFI instance for the CRC library.
      *
      * @return string The calculated CRC checksum as a hexadecimal string (due to signed large int issues in PHP for
      *                64-bit results).
@@ -55,9 +55,9 @@ public static function calculate(
      * @throws \RuntimeException
      */
     public static function calculateFile(
-        FFI $ffi,
         string $filename,
         int $readChunkSize = self::READ_CHUNK_SIZE_DEFAULT,
+        ?FFI $ffi = null,
     ): string;
 
     /**

src/FfiTrait.php

@@ -17,6 +17,20 @@ trait FfiTrait
      */
     private static array $ffis = [];
 
+    /**
+     * @throws \InvalidArgumentException
+     */
+    public static function fromAuto(): \FFI
+    {
+        try {
+            return self::fromPreloadScope();
+        } catch (\Throwable $e) {
+            // ignore
+        }
+
+        return self::fromHeaderFile();
+    }
+
     public static function fromCode(
         string $code,
         ?string $library = null,