Merge pull request #16 from petrknap/refactor

BC: removed public constants from coders, removed interfaces for abstract classes, rearranged exceptions

Author: petrknap

README.md

@@ -7,8 +7,8 @@ See the examples below for more information, or check out [`Encoder`](./src/Enco
 namespace PetrKnap\Binary;
 
 $data = base64_decode('hmlpFnFwbchsoQARSibVpfbWVfuwAHLbGxjFl9eC8fiGaWkWcXBtyGyhABFKJtWl9tZV+7AActsbGMWX14Lx+A==');
-$encoded = Binary::encode($data)->checksum()->zlib()->base64(urlSafe: true)->getData();
-$decoded = Binary::decode($encoded)->base64()->zlib()->checksum()->getData();
+$encoded = Binary::encode($data)->checksum()->zlib()->base64(urlSafe: true)->data;
+$decoded = Binary::decode($encoded)->base64()->zlib()->checksum()->data;
 
 printf('Data was coded into `%s` %s.', $encoded, $decoded === $data ? 'successfully' : 'unsuccessfully');
 ```

composer.json

@@ -41,7 +41,7 @@
   "require": {
     "php": ">=8.1",
     "petrknap/optional": "^3.1",
-    "petrknap/shorts": "^2.0"
+    "petrknap/shorts": "^3.0"
   },
   "require-dev": {
     "ext-igbinary": "*",
@@ -63,7 +63,7 @@
       "phpcs --colors --standard=PSR12 --exclude=Generic.Files.LineLength src tests",
       "phpstan analyse --level max src --ansi --no-interaction",
       "phpstan analyse --level 5 tests --ansi --no-interaction",
-      "phpinsights analyse src --ansi --no-interaction"
+      "phpinsights analyse src tests --ansi --no-interaction --format=github-action | sed -e \"s#::error file=$PWD/#::notice file=#g\""
     ],
     "check-requirements": [
       "composer update \"petrknap/*\"",

src/Binary.php

@@ -6,12 +6,12 @@
 
 final class Binary
 {
-    public static function encode(string $data): EncoderInterface
+    public static function encode(string $data): Encoder
     {
         return new Encoder($data);
     }
 
-    public static function decode(string $data): DecoderInterface
+    public static function decode(string $data): Decoder
     {
         return new Decoder($data);
     }

src/Byter.php

@@ -7,7 +7,7 @@
 use PetrKnap\Shorts\HasRequirements;
 use RuntimeException;
 
-class Byter
+final class Byter
 {
     use HasRequirements;
 
@@ -28,15 +28,15 @@ functions: [
      *
      * @return array<string> bites of specified sizes; and remains, if any
      *
-     * @throws Exception\CouldNotBiteData
+     * @throws Exception\ByterCouldNotBiteData
      */
     public function bite(string $data, int $size1, int ...$sizeN): array
     {
         $remains = $data;
         $bites = [];
         foreach ([$size1, ...$sizeN] as $size) {
             if (abs($size) > $this->size($remains)) {
-                throw new Exception\CouldNotBiteData(__METHOD__, $data, new RuntimeException(
+                throw new Exception\ByterCouldNotBiteData(__METHOD__, $data, new RuntimeException(
                     'Remains are smaller than bite',
                 ));
             }

src/Coder.php

@@ -4,34 +4,54 @@
 
 namespace PetrKnap\Binary;
 
-use PetrKnap\Shorts\Exception;
-
 /**
- * @internal please use subclass
- *
- * @phpstan-consistent-constructor override {@see self::create()} if not
- *
- * @implements CoderInterface<Exception\CouldNotProcessData>
+ * @internal shared logic
  */
-abstract class Coder implements CoderInterface
+abstract class Coder
 {
-    public function __construct(
-        protected readonly string $data = '',
+    final public function __construct(
+        public readonly string $data = '',
     ) {
     }
 
-    public function withData(string $data): static
+    final public function withData(string $data): static
     {
-        return static::create($this, $data);
+        return new static($data);
     }
 
-    public function getData(): string
+    /**
+     * @deprecated use readonly property $data
+     */
+    final public function getData(): string
     {
         return $this->data;
     }
 
-    protected static function create(self $coder, string $data): static
-    {
-        return new static($data);
-    }
+    /**
+     * @see Coder\Base64
+     *
+     * @throws Coder\Exception\CoderException
+     */
+    abstract public function base64(): static;
+
+    /**
+     * @see Coder\Checksum
+     *
+     * @throws Coder\Exception\CoderException
+     */
+    abstract public function checksum(string|null $algorithm = null): static;
+
+    /**
+     * @see Coder\Hex
+     *
+     * @throws Coder\Exception\CoderException
+     */
+    abstract public function hex(): static;
+
+    /**
+     * @see Coder\zlib
+     *
+     * @throws Coder\Exception\CoderException
+     */
+    abstract public function zlib(): static;
 }

src/Coder/Base64.php

@@ -12,18 +12,16 @@
  */
 final class Base64 extends Coder
 {
-    public const URL_SAFE = false;
-
     private const URL_REPLACE_TABLE = [
         ['+', '/', '='],
         ['-', '_', ''],
     ];
 
     private bool $urlSafe;
 
-    public function encode(string $decoded, ?bool $urlSafe = null): string
+    public function encode(string $decoded, bool|null $urlSafe = null): string
     {
-        $this->urlSafe = $urlSafe ?? self::URL_SAFE;
+        $this->urlSafe = $urlSafe ?? false;
         return parent::encode($decoded);
     }
 
@@ -42,7 +40,7 @@ protected function doDecode(string $encoded): string
             str_replace(self::URL_REPLACE_TABLE[1], self::URL_REPLACE_TABLE[0], $encoded),
             strict: true,
         ))->orElseThrow(
-            static fn () => new Exception\CouldNotDecodeData(__METHOD__, $encoded),
+            static fn () => new Exception\CoderCouldNotDecodeData(__METHOD__, $encoded),
         );
     }
 }

src/Coder/Checksum.php

@@ -13,7 +13,10 @@
  */
 final class Checksum extends Coder
 {
-    public const ALGORITHM = 'crc32';
+    /**
+     * @internal public for testing purposes only
+     */
+    public const DEFAULT_ALGORITHM = 'crc32';
 
     private string $algorithm;
     private readonly Byter $byter;
@@ -23,15 +26,15 @@ public function __construct()
         $this->byter = new Byter();
     }
 
-    public function encode(string $decoded, ?string $algorithm = null): string
+    public function encode(string $decoded, string|null $algorithm = null): string
     {
-        $this->algorithm = $algorithm ?? self::ALGORITHM;
+        $this->algorithm = $algorithm ?? self::DEFAULT_ALGORITHM;
         return parent::encode($decoded);
     }
 
-    public function decode(string $encoded, ?string $algorithm = null): string
+    public function decode(string $encoded, string|null $algorithm = null): string
     {
-        $this->algorithm = $algorithm ?? self::ALGORITHM;
+        $this->algorithm = $algorithm ?? self::DEFAULT_ALGORITHM;
         return parent::decode($encoded);
     }
 
@@ -46,7 +49,7 @@ protected function doDecode(string $encoded): string
         $checksumLength = $this->byter->size(hash($this->algorithm, '', binary: true));
         [,$decoded] = $this->byter->bite($encoded, -$checksumLength);
         if ($this->doEncode($decoded) !== $encoded) {
-            throw new Exception\CouldNotDecodeData(__METHOD__, $encoded);
+            throw new Exception\CoderCouldNotDecodeData(__METHOD__, $encoded);
         }
         return $decoded;
     }

src/Coder/Coder.php

@@ -6,29 +6,30 @@
 
 use Throwable;
 
+/**
+ * @internal shared logic
+ */
 abstract class Coder implements CoderInterface
 {
     public function encode(string $decoded): string
     {
         try {
             return $this->doEncode($decoded);
+        } catch (Exception\CoderCouldNotEncodeData $exception) {
+            throw $exception;
         } catch (Throwable $reason) {
-            if ($reason instanceof Exception\CouldNotEncodeData) {
-                throw $reason;
-            }
-            throw new Exception\CouldNotEncodeData(__METHOD__, $decoded, $reason);
+            throw new Exception\CoderCouldNotEncodeData(__METHOD__, $decoded, $reason);
         }
     }
 
     public function decode(string $encoded): string
     {
         try {
             return $this->doDecode($encoded);
+        } catch (Exception\CoderCouldNotDecodeData $exception) {
+            throw $exception;
         } catch (Throwable $reason) {
-            if ($reason instanceof Exception\CouldNotDecodeData) {
-                throw $reason;
-            }
-            throw new Exception\CouldNotDecodeData(__METHOD__, $encoded, $reason);
+            throw new Exception\CoderCouldNotDecodeData(__METHOD__, $encoded, $reason);
         }
     }
 

src/Coder/CoderInterface.php

@@ -7,12 +7,12 @@
 interface CoderInterface
 {
     /**
-     * @throws Exception\CouldNotEncodeData
+     * @throws Exception\CoderCouldNotEncodeData
      */
     public function encode(string $decoded): string;
 
     /**
-     * @throws Exception\CouldNotDecodeData
+     * @throws Exception\CoderCouldNotDecodeData
      */
     public function decode(string $encoded): string;
 }

src/Coder/Exception/CouldNotDecodeData.php renamed to src/Coder/Exception/CoderCouldNotDecodeData.php

@@ -9,6 +9,6 @@
 /**
  * @extends CouldNotProcessData<string>
  */
-final class CouldNotDecodeData extends CouldNotProcessData implements CoderException
+final class CoderCouldNotDecodeData extends CouldNotProcessData implements CoderException
 {
 }