Improve Exception handling

awesomized · Dec 29, 2024 · c200ac5 · c200ac5
1 parent 7e581ff
commit c200ac5
Show file tree

Hide file tree

Showing 9 changed files with 70 additions and 47 deletions.
diff --git a/src/Crc32/IsoHdlc/Computer.php b/src/Crc32/IsoHdlc/Computer.php
@@ -6,10 +6,15 @@
 
 use Awesomized\Checksums;
 use FFI;
+use FFI\Exception;
 
 /**
  * A wrapper around the CRC-32/ISO-HDLC FFI library.
  *
+ * This produces output compatible with crc32() and hash('crc32b') in PHP at >10X the speed.
+ *
+ * Input of "123456789" (no quotes) should produce a checksum of 0xCBF43926
+ *
  * @link https://reveng.sourceforge.io/crc-catalogue/all.htm#crc.cat.crc-32-iso-hdlc
  */
 final class Computer implements Checksums\CrcInterface
@@ -26,27 +31,20 @@ final class Computer implements Checksums\CrcInterface
      * @param FFI|null $crc32IsoHdlc The FFI instance for the CRC-32 IEEE library.
      *
      * @throws \InvalidArgumentException
+     * @throws Exception
      */
     public function __construct(
         ?FFI $crc32IsoHdlc = null,
     ) {
         $this->crc32IsoHdlc = $crc32IsoHdlc ?? self::getFfi();
 
-        try {
-            /**
-             * @var FFI\CData $hasherHandle
-             *
-             * @psalm-suppress UndefinedMethod - from FFI, we'll catch the Exception if the method is missing
-             */
-            // @phpstan-ignore-next-line
-            $hasherHandle = $this->crc32IsoHdlc->hasher_new();
-        } catch (FFI\Exception $e) {
-            throw new \InvalidArgumentException(
-                message: 'Could not create a new Hasher handle.'
-                . ' Is the library loaded, and has the hasher_new() method?',
-                previous: $e,
-            );
-        }
+        /**
+         * @var FFI\CData $hasherHandle
+         *
+         * @psalm-suppress UndefinedMethod - from FFI, we'll catch the Exception if the method is missing
+         */
+        // @phpstan-ignore-next-line
+        $hasherHandle = $this->crc32IsoHdlc->hasher_new();
 
         $this->hasherHandle = $hasherHandle;
     }
@@ -62,7 +60,7 @@ public function write(
                 $string,
                 \strlen($string),
             );
-        } catch (FFI\Exception $e) {
+        } catch (Exception $e) {
             throw new \RuntimeException(
                 message: 'Could not write to the Digest handle. '
                 . 'Is the library loaded, and has the digest_write() method?',
@@ -85,7 +83,7 @@ public function sum(): string
             $crc32 = $this->crc32IsoHdlc->hasher_finalize(
                 $this->hasherHandle,
             );
-        } catch (FFI\Exception $e) {
+        } catch (Exception $e) {
             throw new \RuntimeException(
                 message: 'Could not calculate the CRC-32 checksum. '
                 . ' Is the library loaded, and has the hasher_finalize() method?',
@@ -101,6 +99,7 @@ public function sum(): string
 
     /**
      * @throws \InvalidArgumentException
+     * @throws Exception
      */
     protected static function getFfi(): FFI
     {

diff --git a/src/Crc64/Nvme/Computer.php b/src/Crc64/Nvme/Computer.php
@@ -6,11 +6,13 @@
 
 use Awesomized\Checksums;
 use FFI;
+use FFI\Exception;
 
 /**
- * A wrapper around the CRC-64/NVME FFI library.
+ * A wrapper around the CRC-64/NVME FFI library which calculates checksums at >20GiB/s on modern CPUs.
+ *
+ * Input of "123456789" (no quotes) should produce a checksum of 0xAE8B14860A799888.
  *
- * @see  \Awesomized\Checksums\Crc64\Nvme\Ffi
  * @link https://github.com/awesomized/crc64fast-nvme
  * @link https://reveng.sourceforge.io/crc-catalogue/all.htm#crc.cat.crc-64-nvme
  */
@@ -25,30 +27,23 @@ final class Computer implements Checksums\CrcInterface
     private static ?FFI $ffiAuto = null;
 
     /**
-     * @param FFI $crc64Nvme The FFI instance for the CRC-64 NVMe library.
+     * @param FFI|null $crc64Nvme The FFI instance for the CRC-64 NVMe library.
      *
      * @throws \InvalidArgumentException
+     * @throws Exception
      */
     public function __construct(
         ?FFI $crc64Nvme = null,
     ) {
         $this->crc64Nvme = $crc64Nvme ?? self::getFfi();
 
-        try {
-            /**
-             * @var FFI\CData $digestHandle
-             *
-             * @psalm-suppress UndefinedMethod - from FFI, we'll catch the Exception if the method is missing
-             */
-            // @phpstan-ignore-next-line
-            $digestHandle = $this->crc64Nvme->digest_new();
-        } catch (FFI\Exception $e) {
-            throw new \InvalidArgumentException(
-                message: 'Could not create a new Digest handle.'
-                . ' Is the library loaded, and has the digest_new() method?',
-                previous: $e,
-            );
-        }
+        /**
+         * @var FFI\CData $digestHandle
+         *
+         * @psalm-suppress UndefinedMethod - from FFI, we'll catch the Exception if the method is missing
+         */
+        // @phpstan-ignore-next-line
+        $digestHandle = $this->crc64Nvme->digest_new();
 
         $this->digestHandle = $digestHandle;
     }
@@ -64,7 +59,7 @@ public function write(
                 $string,
                 \strlen($string),
             );
-        } catch (FFI\Exception $e) {
+        } catch (Exception $e) {
             throw new \RuntimeException(
                 message: 'Could not write to the Digest handle. '
                 . 'Is the library loaded, and has the digest_write() method?',
@@ -87,7 +82,7 @@ public function sum(): string
             $crc64 = $this->crc64Nvme->digest_sum64(
                 $this->digestHandle,
             );
-        } catch (FFI\Exception $e) {
+        } catch (Exception $e) {
             throw new \RuntimeException(
                 message: 'Could not calculate the CRC-64 checksum. '
                 . ' Is the library loaded, and has the digest_sum64() method?',
@@ -103,6 +98,7 @@ public function sum(): string
 
     /**
      * @throws \InvalidArgumentException
+     * @throws Exception
      */
     protected static function getFfi(): FFI
     {

diff --git a/src/CrcInterface.php b/src/CrcInterface.php
@@ -6,6 +6,7 @@
 
 use Awesomized\Checksums;
 use FFI;
+use FFI\Exception;
 
 /**
  * A common Interface for CRC checksum calculations via FFI (Foreign Function Interface) libraries.
@@ -34,6 +35,7 @@ interface CrcInterface
      *
      * @throws \InvalidArgumentException
      * @throws \RuntimeException
+     * @throws Exception
      */
     public static function calculate(
         string $string,
@@ -53,6 +55,7 @@ public static function calculate(
      *
      * @throws \InvalidArgumentException
      * @throws \RuntimeException
+     * @throws Exception
      */
     public static function calculateFile(
         string $filename,

diff --git a/src/FfiInterface.php b/src/FfiInterface.php
@@ -22,6 +22,12 @@ interface FfiInterface
     public const string OS_DARWIN = 'Darwin';
     public const string OS_WINDOWS = 'Windows';
 
+    /**
+     * @throws \InvalidArgumentException
+     * @throws Exception
+     */
+    public static function fromAuto(): \FFI;
+
     /**
      * Creates a new FFI instance from the given C declarations and library name.
      *
@@ -43,6 +49,8 @@ public static function fromCode(
      * @link https://www.php.net/manual/en/ffi.examples-complete.php
      *
      * @param string $ffiScopeName The FFI_SCOPE used during preloading
+     *
+     * @throws Exception
      */
     public static function fromPreloadScope(
         string $ffiScopeName = self::SCOPE_DEFAULT,
@@ -54,6 +62,7 @@ public static function fromPreloadScope(
      * @param string $headerFile The C header file
      *
      * @throws \InvalidArgumentException
+     * @throws Exception
      */
     public static function fromHeaderFile(
         string $headerFile = '',

diff --git a/src/FfiTrait.php b/src/FfiTrait.php
@@ -17,9 +17,6 @@ trait FfiTrait
      */
     private static array $ffis = [];
 
-    /**
-     * @throws \InvalidArgumentException
-     */
     public static function fromAuto(): \FFI
     {
         try {

diff --git a/tests/unit/Crc32/IsoHdlc/ComputerTest.php b/tests/unit/Crc32/IsoHdlc/ComputerTest.php
@@ -7,6 +7,7 @@
 use Awesomized\Checksums\Crc32;
 use Awesomized\Checksums\tests\unit\Definitions;
 use FFI;
+use FFI\Exception;
 use PHPUnit\Framework\TestCase;
 use Random\RandomException;
 
@@ -19,6 +20,7 @@ final class ComputerTest extends TestCase
 
     /**
      * @throws \InvalidArgumentException
+     * @throws  Exception
      */
     protected function setUp(): void
     {
@@ -27,11 +29,11 @@ protected function setUp(): void
 
     /**
      * @throws \InvalidArgumentException
-     * @throws \FFI\Exception
+     * @throws Exception
      */
     public function testConstructorInvalidLibraryShouldFail(): void
     {
-        $this->expectException(\InvalidArgumentException::class);
+        $this->expectException(Exception::class);
 
         $ffi = \FFI::cdef();
 
@@ -44,12 +46,13 @@ public function testConstructorInvalidLibraryShouldFail(): void
      * @depends testConstructorInvalidLibraryShouldFail
      *
      * @throws \InvalidArgumentException
+     * @throws Exception
      */
     public function testConstructorValidLibraryShouldSucceed(): void
     {
         $this->expectNotToPerformAssertions();
 
-        $ffi = new Crc32\IsoHdlc\Computer(
+        new Crc32\IsoHdlc\Computer(
             crc32IsoHdlc: $this->ffi,
         );
     }
@@ -59,6 +62,7 @@ public function testConstructorValidLibraryShouldSucceed(): void
      *
      * @throws \InvalidArgumentException
      * @throws \RuntimeException
+     * @throws Exception
      */
     public function testCalculateHelloWorldShouldSucceed(): void
     {
@@ -77,6 +81,7 @@ public function testCalculateHelloWorldShouldSucceed(): void
      *
      * @throws \InvalidArgumentException
      * @throws \RuntimeException
+     * @throws Exception
      */
     public function testCalculateFileHelloWorldShouldSucceed(): void
     {
@@ -99,6 +104,7 @@ public function testCalculateFileHelloWorldShouldSucceed(): void
      * @throws \InvalidArgumentException
      * @throws \RuntimeException
      * @throws RandomException
+     * @throws Exception
      */
     public function testCalculateBinaryDataShouldSucceed(): void
     {
@@ -114,6 +120,7 @@ public function testCalculateBinaryDataShouldSucceed(): void
      *
      * @throws \InvalidArgumentException
      * @throws \RuntimeException
+     * @throws Exception
      */
     public function testCalculateChunkedDataShouldSucceed(): void
     {
@@ -133,6 +140,7 @@ public function testCalculateChunkedDataShouldSucceed(): void
      *
      * @throws \InvalidArgumentException
      * @throws \RuntimeException
+     * @throws Exception
      */
     public function testCalculateCheckValueShouldMatch(): void
     {
@@ -151,6 +159,7 @@ public function testCalculateCheckValueShouldMatch(): void
      *
      * @throws \InvalidArgumentException
      * @throws \RuntimeException
+     * @throws Exception
      */
     public function testComparePhpFunctionKnownValuesShouldMatch(): void
     {

diff --git a/tests/unit/Crc32/IsoHdlc/FfiTest.php b/tests/unit/Crc32/IsoHdlc/FfiTest.php
@@ -69,6 +69,7 @@ public function testFfiFromCodeInvalidLibraryShouldFail(): void
      * @depends testFfiFromCodeInvalidLibraryShouldFail
      *
      * @throws \InvalidArgumentException
+     * @throws \FFI\Exception
      */
     public function testFfiFromHeaderInvalidHeaderShouldFail(): void
     {
-Original file line number
+Diff line change
@@ Expand Up / @@ -17,9 +17,6 @@ trait FfiTrait @@
          */
         private static array $ffis = [];
-        /**
-         * @throws \InvalidArgumentException
-         */
         public static function fromAuto(): \FFI
         {
             try {
@@ Expand Down @@